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

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 restored.

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

⚠️

Deletion is permanent

Deleting a subscription is irreversible. All future invoices associated with the subscription will be cancelled and will not be processed. If you only need to temporarily pause billing, use Recurring — Modify Invoice to set the invoice status to Suspended (06) instead.

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 Delete Subscription 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}.

📄

Subscription ID & Token

You must have stored both the subscription ID and the subscriber Token from prior recurring API responses. Use Recurring — Info Subscription to retrieve these values if needed before proceeding.

2

Request

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

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. Both the Token and the ID are required to uniquely identify and authorize deletion of the subscription.

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
TokenAlphanumeric(35)Security token linked to the subscriber's credit card. Obtained from a prior transaction or recurring session response. Example: 2079wo00wbwp916d3l2mutd8t7965o99mp9
IDNumeric(12)Unique identifier of the subscription to delete. Left zero-padded. Obtained from the subscription creation response or InfoSubscription. Example: 000000000010
OperatorIDAlphanumeric(8)Identifies the operator or system performing the deletion. Example: USER0001
3

Request — Code Example

⚠️

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

cURL
# Recurring: Delete Subscription — POST /v1/recur/DelSubscription
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345\
&MerchantNumber=53400000\
&Token=2079wo00wbwp916d3l2mutd8t7965o99mp9\
&ID=000000000010\
&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/DelSubscription" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "auth-api-key=YOUR_TEST_API_KEY&payload=$ENCODED"
4

Response

Always returned

FieldTypeDescription
recurReturnCodeAlphanumeric(4)00=the subscription was deleted successfully. Any other value indicates a failure. Check this field first before inspecting the remaining response fields.
idNumeric(12)Unique identifier of the subscription that was deleted. Left zero-padded. Confirms which subscription was affected.

Conditionally returned

FieldTypeDescription
transactionReturnCodeAlphanumeric(4)Return code of any transaction triggered as part of the deletion operation, if applicable.
transactionNumberNumeric(12)Unique PayFacto gateway identifier of any transaction associated with this operation, if applicable.
subscriptionIdNumeric(12)Identifier of the subscription that was deleted. May echo the ID sent in the request.
clientAlphanumeric(8)Subscriber (customer) number associated with the deleted subscription.
statusNumeric(2)Final status of the subscription after deletion. Expected to reflect a terminal or inactive state.
amountNumeric(11)Amount associated with the deleted subscription. Zero-padded left.
currencyCodeAlphanumeric(3)Currency of the subscription. CAD=Canadian dollars, USD=US dollars.
frequencyNumeric(2)Frequency code of the deleted subscription.
numberOfPaymentsNumeric(3)Number of payments that were scheduled for the deleted subscription.
startDateNumeric(8)Start date of the deleted subscription. Format: YYYYMMDD.
endDateNumeric(8)End date of the deleted subscription, or 8 spaces if it was open-ended. Format: YYYYMMDD.
lastInvoiceDateNumeric(8)Date the last invoice was processed before deletion. Format: YYYYMMDD.
nextInvoiceDateNumeric(8)Date the next invoice would have been processed. Format: YYYYMMDD.
nameAlphanumeric(50)Subscriber name associated with the deleted subscription.
accountNumberAlphanumeric(50)Merchant reference number for the subscriber account.
descriptionAlphanumeric(50)Merchant reference description for the deleted subscription.
emailAlphanumeric(240)Email address of the subscriber, if on file.
languageCodeAlphanumeric(1)Language preference of the subscriber. F=French, E=English.
cardNumberAlphanumeric(40)Masked card number on file for the subscriber.
cardTypeAlphanumeric(1)Card brand on file. A=Amex, D=Debit, M=Mastercard, V=Visa, O=Discover, I=Diners, J=JCB, F=Datacandy.
expirationDateNumeric(4)Card expiration date on file. Format: MMYY.
avsStatusAlphanumeric(1)AVS verification status from the most recent transaction. M=Both match, N=Neither match, Z=Postal only, A=Address only, U=Unavailable.
cvv2Cvc2StatusAlphanumeric(1)CVD verification status from the most recent transaction. 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 Subscription Deleted
{
  "recurReturnCode":       "00",
  "id":                    "000000000010",
  "subscriptionId":        "000000000010",
  "client":                "CLIENT12",
  "status":                "04",
  "amount":                "00000010000",
  "currencyCode":          "CAD",
  "frequency":             "03",
  "numberOfPayments":      "012",
  "startDate":             "20240101",
  "endDate":               "20251231",
  "lastInvoiceDate":       "20240501",
  "name":                  "Jane Doe",
  "accountNumber":         "ACC00012345",
  "description":           "Monthly subscription",
  "email":                 "jane.doe@example.com",
  "languageCode":          "E",
  "cardNumber":            "411111XXXXXX1111",
  "cardType":              "V",
  "expirationDate":        "1226"
}
JSON — Deletion Failed
{
  "recurReturnCode":  "9121",
  "errorDescription": "SUBSCRIPTION 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
00Subscription deletedThe subscription was permanently deleted. No further invoices will be generated or processed.No further action required. Confirm the returned id matches the subscription you intended to delete. Update your records accordingly.
Non-00Deletion failedThe subscription could not be deleted. Common causes: the ID was not found, the Token did not match the subscription, or the subscription was already deleted.Check errorDescription. Use Recurring — Info Subscription to confirm the ID and Token are correct. 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/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 | ...

    • 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 ...