PayFacto API - v1.0 - POST /v1/recur/ModSubscription
PayFacto API - v1.0 - POST /v1/recur/ModSubscription
Updates the configuration of an existing recurring subscription. Only the fields being changed need to be submitted alongside the required identifiers β fields not included remain unchanged. Changes take effect on the next billing cycle. No transaction is processed.
π
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 Subscription request.
π¦
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}. This endpoint does not require card data or terminal numbers.
βοΈ
Partial Updates β Submit Only What Changes
Include only the modifiable fields you want to change (Amount, EndDate, Frequency) alongside the required identifiers. Fields not submitted remain unchanged on the subscription.
βοΈ
Changes Take Effect on the Next Billing Cycle
Modifications do not affect the current in-progress billing cycle. The updated Amount, EndDate, and Frequency will apply starting from the next scheduled charge. No transaction is processed by this call.
βΉοΈ
All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. Include only the modifiable fields you want to change alongside the required identifiers.
Required fields
| Field | Type | Description |
|---|
| CompanyNumber | Numeric(5) | Identifies the merchant on PayFacto's network. Provided by PayFacto during onboarding. Example: 12345 |
| MerchantNumber | Numeric(8) | Identifies the merchant to PayFacto's network. Provided by the integration team. Example: 53400000 |
| CustomerNumber | Alphanumeric(8) | Merchant-assigned customer identifier associated with the subscription. Example: CLIENT12 |
| LanguageCode | Alphanumeric(1) | Language for PayFacto responses. F = French, E = English. |
| OperatorID | Alphanumeric(8) | Identifies the cashier, agent, or system that initiated the request. Example: USER0001 |
| SubscriptionID | Alphanumeric | The subscription identifier to modify. Must match the SubscriptionID originally assigned when the subscription was created via /v1/recur/AddSubscription. Example: SUBSCRIP0001 |
Modifiable fields β include at least one
| Field | Type | Description |
|---|
| Amount | Numeric(11) | New billing amount per cycle, including the decimal portion, left (0) padded. Applies from the next scheduled charge. Example: 00000003999 = $39.99 |
| EndDate | Numeric(8) | New end date for the subscription. Format: YYYYMMDD. Must be a future date. No billing cycles will be processed after this date. Example: 20260601 |
| Frequency | Alphanumeric | New billing frequency. Accepted values: DAILY, WEEKLY, MONTHLY, YEARLY. Example: YEARLY |
3
Request β Code Example
β οΈ
The example below uses the test endpoint and a sandbox API key, and updates both the billing amount and end date of an existing subscription. Replace credentials and base URL before going live. Only include the modifiable fields you actually want to change.
cURL
# Modify Subscription -- POST /v1/recur/ModSubscription
# Step 1: Build the cleartext payload
# This example updates the Amount and extends the EndDate.
# Frequency is not included, so it remains unchanged.
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&LanguageCode=E&OperatorID=USER0001&SubscriptionID=SUBSCRIP0001&Amount=00000003999&EndDate=20260601"
# 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/ModSubscription" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "auth-api-key=YOUR_TEST_API_KEY&payload=$ENCODED"
Always returned
| Field | Type | Description |
|---|
| returnCode | Alphanumeric(4) | Identifies the result of the modification. 00 = modification successful. All other values indicate a failure. Refer to Section 6 for endpoint-specific codes. |
| serverNumber | Alphanumeric(4) | Identifies the PayFacto Network server that processed the request. |
| timeStamp | Alphanumeric(17) | Date and time the request was processed. Format: YYYYMMDD-HHMMSSCC. Example: 20240901-10000100 |
| companyNumber | Numeric(5) | Echo of the request CompanyNumber. |
| merchantNumber | Numeric(8) | Echo of the request MerchantNumber. |
| languageCode | Alphanumeric(1) | Echo of the request LanguageCode. |
Conditionally returned β Updated subscription configuration
Returned when returnCode is 00. These fields reflect the full subscription configuration after the modification has been applied, including both changed and unchanged fields.
| Field | Type | Description |
|---|
| subscriptionId | Alphanumeric | Echo of the request SubscriptionID. |
| status | Alphanumeric | Current state of the subscription after modification. Values: ACTIVE, CANCELLED, COMPLETED, SUSPENDED. |
| amount | Numeric(11) | Billing amount per cycle as it stands after the modification, left (0) padded. |
| startDate | Numeric(8) | Original start date of the subscription. Format: YYYYMMDD. Unchanged by this endpoint. |
| endDate | Numeric(8) | End date of the subscription as it stands after the modification. Format: YYYYMMDD. |
| frequency | Alphanumeric | Billing frequency as it stands after the modification. Values: DAILY, WEEKLY, MONTHLY, YEARLY. |
| errorDescription | Alphanumeric(50) | Only returned when the modification fails. Human-readable description of the failure reason. |
5
Response β Code Example
JSON β 200 Success (amount and end date updated)
{
"returnCode": "00",
"serverNumber": "0001",
"timeStamp": "20240901-10000100",
"companyNumber": "12345",
"merchantNumber": "53400000",
"languageCode": "E",
"subscriptionId": "SUBSCRIP0001",
"status": "ACTIVE",
"amount": "00000003999",
"startDate": "20240601",
"endDate": "20260601",
"frequency": "MONTHLY"
}JSON β Error
{
"returnCode": "9006",
"errorDescription": "INVALID COMPANY NUMBER",
"serverNumber": "0001",
"timeStamp": "20240901-10000200",
"companyNumber": "12345",
"merchantNumber": "53400000",
"languageCode": "E"
}The following codes are most relevant to this endpoint. For the complete catalogue see the Return Code Index.
| Return Code | Meaning | When it occurs | Recommended Action |
|---|
| 00 | Modification successful | The subscription configuration has been updated successfully. Changes will take effect on the next billing cycle. | Verify the updated configuration in the response fields. Update your local records to reflect the new amount, endDate, and/or frequency as applicable. |
| 9004 | "Null" value: company number | CompanyNumber is null or blank in the payload. | Check your application. The field must correspond to the specification in the documentation. |
| 9005 / 9006 | Invalid / rejected: company number | CompanyNumber does not match the required 5-digit length or is not configured in the payment solution. | Make sure the application uses the correct company number provided by PayFacto. If it does, contact PayFacto customer service. |
| 9007 | "Null" value: merchant number | MerchantNumber is null or blank in the payload. | Check your application. The field must correspond to the specification in the documentation. |
| 9008 / 9009 | Invalid / rejected: merchant number | MerchantNumber does not match the required 8-digit length or is not configured in the payment solution. | Make sure the application uses the merchant number provided by PayFacto. If it does, contact PayFacto customer service. |
| 9051 | Time out | Request processing timed out. | Retry the request. If the problem persists, contact PayFacto customer service. |
| 9049 / 9050 | Fatal error | A critical error occurred while processing the request. | Retry the request. If the problem persists, contact PayFacto customer service.
|