PayFacto API - v1.0 - POST /v1/recur/ModUser

PayFacto API - v1.0 - POST /v1/recur/ModUser

POST /v1/recur/ModUser

Recurring — Modify User

Updates the information linked to a Token in the PayFacto recurring billing module. Supports full card replacement or expiry-date-only updates without changing the stored card number.

Version: v1.0   |   Last updated: 2026-05-25  |   Author: Annick Lachapelle 

ℹ️

Expiry-date-only update

To update only the expiry date without replacing the card number stored in the Token Vault, send the literal string NO_CHANGE in the CardNumber field along with the new ExpirationDate.

To replace the full card, send the new card number in CardNumber and the new expiry date in ExpirationDate as usual.

1

Prerequisites

🔑

API Key

Generate your API key from the Payments Manager: Administrator Client → API Key → Add New Key. Pass it as auth-api-key in every request.

🏪

Company & Merchant Numbers

Your CompanyNumber (5-digit) and MerchantNumber (8-digit) are issued by PayFacto during onboarding. Both are required on every Modify User request.

🌐

Environment Base URL

Test: https://test.api.payfacto.cloud/v1   |   Production: Provided by the PayFacto Integration team upon certification.

📦

Request Format — Base64-Encoded Payload

Requests use HTTP POST with an application/x-www-form-urlencoded body. Assemble all parameters as a cleartext query string, Base64-encode it, then send: auth-api-key={key}&payload={base64}.

📄

Existing Token

You must have stored the Token from a prior transaction or recurring session response. This token identifies the subscriber record to update in the PayFacto Token Vault. Use Recurring — Info User to retrieve the token if needed.

2

Request

POST https://test.api.payfacto.cloud/v1/recur/ModUser
ℹ️

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. All fields listed below are required on every request — send NO_CHANGE in CardNumber when updating the expiry date only.

Required fields

FieldTypeDescription
CompanyNumberNumeric(5)Identifies the merchant on PayFacto's network. Provided by PayFacto. Example: 12345
MerchantNumberNumeric(8)Identifies the merchant to PayFacto's network. Provided by the integration team. Example: 53400000
CustomerNumberAlphanumeric(8)The merchant-assigned identifier of the subscriber whose information is being updated. Example: CLIENT12
TokenAlphanumeric(35)Security token linked to the subscriber's credit card on the PayFacto Token Vault. Identifies the record to update. Example: 2079wo00wbwp916d3l2mutd8t7965o99mp9
NameAlphanumeric(50)Updated cardholder name for the subscriber. The value can be URI-encoded to allow special characters. Must be at least 3 characters long.
EmailAlphanumeric(240)Updated email address for the subscriber. Example: jane.doe@example.com
CardNumberAlphanumeric(40)Updated card number for the subscriber, left-justified and space-padded to 40 characters. To update the expiry date only without changing the card number, send the literal value NO_CHANGE in this field along with the new ExpirationDate.
ExpirationDateNumeric(4)Updated card expiration date in MMYY format. Required even when sending NO_CHANGE in CardNumber to update the expiry date only. Example: 0128 = January 2028.
LanguageCodeAlphanumeric(1)Language preference for the subscriber. F=French, E=English.
OperatorIDAlphanumeric(8)Identifies the operator or system performing the update. Example: USER0001
3

Request — Code Example

⚠️

The examples below use the test endpoint and a sandbox API key. Replace credentials and base URL before going live.

Example A — Full card replacement

cURL
# Recurring: Modify User — Full card replacement
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345\
&MerchantNumber=53400000\
&CustomerNumber=CLIENT12\
&Token=2079wo00wbwp916d3l2mutd8t7965o99mp9\
&Name=Jane Doe\
&Email=jane.doe@example.com\
&CardNumber=5500005555555559\
&ExpirationDate=0128\
&LanguageCode=E\
&OperatorID=USER0001"

# Step 2: Base64-encode the payload
ENCODED=$(echo -n "$PAYLOAD" | base64)

# Step 3: Submit the request
curl -X POST "https://test.api.payfacto.cloud/v1/recur/ModUser" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "auth-api-key=YOUR_TEST_API_KEY&payload=$ENCODED"

Example B — Expiry date update only (NO_CHANGE)

cURL
# Recurring: Modify User — Expiry date only (card number unchanged)
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345\
&MerchantNumber=53400000\
&CustomerNumber=CLIENT12\
&Token=2079wo00wbwp916d3l2mutd8t7965o99mp9\
&Name=Jane Doe\
&Email=jane.doe@example.com\
&CardNumber=NO_CHANGE\
&ExpirationDate=0130\
&LanguageCode=E\
&OperatorID=USER0001"

# Step 2: Base64-encode the payload
ENCODED=$(echo -n "$PAYLOAD" | base64)

# Step 3: Submit the request
curl -X POST "https://test.api.payfacto.cloud/v1/recur/ModUser" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "auth-api-key=YOUR_TEST_API_KEY&payload=$ENCODED"
4

Response

ℹ️

The source specification does not designate any response fields as unconditionally mandatory for this endpoint. Always check recurReturnCode first. The remaining fields reflect the full state of the subscriber record after the update.

Response fields

FieldTypeDescription
recurReturnCodeAlphanumeric(4)00=the subscriber information was updated successfully. Any other value indicates a failure. Check this field first before inspecting the remaining response fields.
tokenAlphanumeric(35)Echo of the Token associated with the updated subscriber record. Confirms which token was affected.
transactionReturnCodeAlphanumeric(4)Return code of any transaction triggered as part of the update operation, if applicable.
transactionNumberNumeric(12)Unique PayFacto gateway identifier of any transaction associated with this operation, if applicable.
idNumeric(12)Unique identifier of the subscriber record that was updated. Left zero-padded.
subscriptionIdNumeric(12)Identifier of the subscription associated with the updated subscriber.
clientAlphanumeric(8)Subscriber (customer) number echoed from the request.
nameAlphanumeric(50)Subscriber name after the update.
emailAlphanumeric(240)Subscriber email address after the update.
languageCodeAlphanumeric(1)Language preference after the update. F=French, E=English.
cardNumberAlphanumeric(40)Updated masked card number on file for the subscriber.
cardTypeAlphanumeric(1)Card brand determined from the updated card. A=Amex, D=Debit, M=Mastercard, V=Visa, O=Discover, I=Diners, J=JCB, F=Datacandy.
expirationDateNumeric(4)Updated card expiration date on file. Format: MMYY.
statusNumeric(2)Current status of the subscriber's record after the update.
amountNumeric(11)Amount associated with the subscriber's subscription. Zero-padded left.
currencyCodeAlphanumeric(3)Currency of the subscription. CAD=Canadian dollars, USD=US dollars.
frequencyNumeric(2)Frequency code of the subscription associated with this subscriber.
numberOfPaymentsNumeric(3)Number of payments scheduled for the subscription.
startDateNumeric(8)Start date of the subscription. Format: YYYYMMDD.
endDateNumeric(8)End date of the subscription, or 8 spaces if open-ended. Format: YYYYMMDD.
lastInvoiceDateNumeric(8)Date the last invoice was processed. Format: YYYYMMDD.
nextInvoiceDateNumeric(8)Date the next invoice is scheduled. Format: YYYYMMDD.
accountNumberAlphanumeric(50)Merchant reference number for the subscriber account.
descriptionAlphanumeric(50)Merchant reference description for the subscription.
avsStatusAlphanumeric(1)AVS verification status from the most recent transaction on this token. M=Both match, N=Neither match, Z=Postal only, A=Address only, U=Unavailable.
cvv2Cvc2StatusAlphanumeric(1)CVD verification status from the most recent transaction on this token. M=Matches, N=Does not match, blank=Unknown.
secureIDAlphanumeric(35)Secure session identifier, if a hosted session was used during the operation.
errorDescriptionAlphanumeric(50)Only returned when recurReturnCode is not 00. Human-readable description of the failure reason.
5

Response — Code Example

JSON — 200 User Updated
{
  "recurReturnCode":       "00",
  "token":                 "2079wo00wbwp916d3l2mutd8t7965o99mp9",
  "id":                    "000000000001",
  "subscriptionId":        "000000000010",
  "client":                "CLIENT12",
  "name":                  "Jane Doe",
  "email":                 "jane.doe@example.com",
  "languageCode":          "E",
  "cardNumber":            "550000XXXXXX5559",
  "cardType":              "M",
  "expirationDate":        "0128",
  "status":                "01",
  "amount":                "00000010000",
  "currencyCode":          "CAD",
  "frequency":             "03",
  "numberOfPayments":      "012",
  "startDate":             "20240101",
  "endDate":               "20251231",
  "lastInvoiceDate":       "20240501",
  "nextInvoiceDate":       "20240601",
  "accountNumber":         "ACC00012345",
  "description":           "Monthly subscription"
}
JSON — Update Failed
{
  "recurReturnCode":  "9121",
  "errorDescription": "TOKEN NOT FOUND"
}
6

Error / Return Codes

The following codes are specific to this endpoint. For the complete catalogue see the Return Code Index.

recurReturnCodeMeaningWhen it occursRecommended Action
00User updatedThe subscriber record was updated successfully in the Token Vault.Confirm the returned cardNumber (masked) and expirationDate reflect the intended update. No further action required.
Non-00Update failedThe subscriber record could not be updated. Common causes: the Token was not found in the vault, the CustomerNumber did not match the token, or an invalid ExpirationDate was submitted.Check errorDescription. Verify the Token and CustomerNumber are correct using Recurring — Info User. Refer to the Return Code Index for code-specific guidance.

    • Related Articles

    • PayFacto API - v1.0 - POST /v1/recur/InfoUser

      POST /v1/recur/InfoUser Recurring — Info User Retrieves all available information on an existing Token stored in the PayFacto Token Vault. Use this endpoint to look up a subscriber's card details, subscription state, and billing history before ...

    • PayFacto API - v1.0 - POST /v1/recur/ModInvoice

      POST /v1/recur/ModInvoice Recurring — Modify Invoice Updates the status of a recurring invoice. Use this endpoint to activate, suspend, or otherwise change the processing state of a specific invoice within a subscription. Version: v1.0 | Last ...

    • PayFacto API - v1.0 - POST /v1/recur/DelSubscription

      POST /v1/recur/DelSubscription Recurring — Delete Subscription Permanently deletes an active subscription from the PayFacto recurring billing module. Once deleted, all associated invoices will cease to be processed and the subscription cannot be ...

    • PayFacto API - v1.0 - POST /v1/recur/nack

      POST /v1/recur/nack Recurring — Nack Declines a CVV or AVS verification result from a recurring session and triggers deletion of the associated token. Use this endpoint when your application determines that the CVV or AVS result from a prior ...

    • PayFacto API - v1.0 - POST /v1/standaloneCompletion

      POST /v1/standaloneCompletion Standalone Completion Sends a Pre-Authorization Completion to any properly configured Semi-Integrated terminal. The target terminal can be the one where the original Pre-Authorization was performed, or any other terminal ...