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

Creates a new recurring billing subscription on a credit card. The first charge is processed immediately; subsequent charges are automatically billed at the defined frequency until the end date. A subscriptionId and a token are returned on approval.

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 Add 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}. E-Commerce transactions send 5 blank spaces for MerchantTerminalNumber.

💳

Credit Card Only

Recurring subscriptions are supported for credit card transactions only. Interac debit (IAP) is not supported for this endpoint.

🔁

Immediate First Charge — Automatic Subsequent Billing

The first billing is processed immediately as part of this request. Subsequent charges are automatically triggered by the PayFacto platform at the defined Frequency between StartDate and EndDate. No further API calls are needed for recurring charges.

💾

Store the Subscription ID and Token

On approval, persist both the subscriptionId and the token returned in the response. The subscriptionId is required to manage or cancel the subscription later. The token can be used for additional token-based transactions against the same card.

Request

POST https://test.api.payfacto.cloud/v1/recur/AddSubscription

ℹ️

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. E-Commerce transactions send 5 blank spaces for MerchantTerminalNumber.

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. Associates a client record with the subscription. Example: `CLIENT12`
Amount	Numeric(11)	Amount to charge on each billing cycle, including the decimal portion, left (0) padded. This same amount is charged on the first and all subsequent recurring billings. Example: `00000002999` = $29.99
InvoiceNumber	Alphanumeric(12)	Merchant-generated invoice number for the first billing of this subscription. Example: `SUB000000001`
InputType	Alphanumeric(1)	How the transaction is initiated. `I` = Internet/E-Commerce, `M` = MOTO, `N` = terminal/pinpad (Semi-Integrated), `U` = Unattended.
CardType	Alphanumeric(1)	Card brand. For `InputType=N` send a blank space. For `I`/`M`: `A` = Amex, `M` = Mastercard, `V` = Visa, `I` = Diners, `O` = Discover. Blank for unknown.
CardNumber	Alphanumeric(40)	Cardholder's card number, left-justified and space-padded to 40 characters. For `InputType=N`, send 40 space characters — the terminal reads the card directly.
ExpirationDate	Numeric(4)	Card expiration date in `MMYY` format. For `InputType=N`, send 4 space characters. Example: `1226`
Cvv2Cvc2Number	Alphanumeric(4)	Card security code (3 digits for Visa/Mastercard/Discover, 4 digits for Amex). For `InputType=N`, send a blank space. Example: `123`
MerchantTerminalNumber	Numeric(5)	Identifies the terminal on PayFacto's network. For E-Commerce transactions, send 5 blank spaces. Example: `12345`
LanguageCode	Alphanumeric(1)	Language for PayFacto responses and terminal display. `F` = French, `E` = English.
CurrencyCode	Alphanumeric(3)	Currency of the transaction (indicative only). `CAD` = Canadian dollars, `USD` = US dollars (requires a US merchant number).
OperatorID	Alphanumeric(8)	Identifies the cashier, agent, or system that initiated the transaction. Example: `USER0001`
SubscriptionID	Alphanumeric	Merchant-assigned unique identifier for this subscription. Used to manage or cancel the subscription later. Must be unique per subscription. Example: `SUBSCRIP0001`
StartDate	Numeric(8)	Date on which the subscription begins and the first billing is processed. Format: `YYYYMMDD`. Example: `20240601`
EndDate	Numeric(8)	Date on which the subscription ends and no further billings are processed. Format: `YYYYMMDD`. Example: `20250601`
Frequency	Alphanumeric	Billing frequency for recurring charges. Accepted values: `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY`. Example: `MONTHLY`

Optional fields

Field	Type	Description
AvsStreetNumber	Alphanumeric(10)	Street number portion of the cardholder's billing address for Address Verification Service (AVS). Example: `123`
AvsStreetName	Alphanumeric(28)	Street name portion of the cardholder's billing address for AVS. Example: `Main Street`
AvsZipCode	Alphanumeric(9)	Postal/ZIP code of the cardholder's billing address for AVS. Example: `H1A1A1`
taxAmount	Numeric(11)	Total tax amount included in `Amount`, left (0) padded. Example: `00000000374` = $3.74
TrxOption	Alpha(50)	Adds transaction-level options. Accepted values: `isCredentialOnFile`, `isRecurring`, `isInstallment` (mutually exclusive).
UserEchoData	Alphanumeric(256)	Custom data printed on the terminal receipt (Semi-Integrated only). Pipe-delimited line segments. Contact PayFacto integration before use.

Request — Code Example

⚠️

The example below uses the test endpoint and a sandbox API key, and shows an E-Commerce (InputType=I) monthly subscription. Replace credentials and base URL before going live. Store the subscriptionId and token from the response.

cURL

# Add Subscription -- POST /v1/recur/AddSubscription
# Step 1: Build the cleartext payload (InputType=I, E-Commerce, monthly billing)
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&Amount=00000002999&InvoiceNumber=SUB000000001&InputType=I&CardType=V&CardNumber=4111111111111111                       &ExpirationDate=1226&Cvv2Cvc2Number=123&MerchantTerminalNumber=     &LanguageCode=E&CurrencyCode=CAD&OperatorID=USER0001&SubscriptionID=SUBSCRIP0001&StartDate=20240601&EndDate=20250601&Frequency=MONTHLY"

# 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/AddSubscription" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "auth-api-key=YOUR_TEST_API_KEY&payload=$ENCODED"

Response

Always returned

Field	Type	Description
returnCode	Alphanumeric(4)	Identifies the exact status of the transaction result. `00` = first charge approved and subscription created. All other values indicate a failure. Refer to Section 6 for endpoint-specific codes.
authorizationNumber	Alphanumeric(8)	Authorization code for the first billing. Mandatory to display on all customer receipts. Example: `APPROV01`
transactionNumber	Numeric(12)	Unique PayFacto gateway transaction identifier for the first billing. Example: `000111222333`
amount	Numeric(11)	Echo of the requested billing amount.
bankTerminalNumber	Alphanumeric(8)	Terminal identifier at the banking acquirer that processed the transaction.
batchNumber	Numeric(4)	Batch number used when the first billing was processed. Example: `0001`
cardNumber	Alphanumeric(40)	Echo of the request CardNumber (masked).
cardType	Alphanumeric(1)	Card brand determined by the network. `A` = Amex, `M` = Mastercard, `V` = Visa, `I` = Diners, `O` = Discover.
companyNumber	Numeric(5)	Echo of the request CompanyNumber.
expirationDate	Numeric(4)	Echo of the request ExpirationDate, in `MMYY` format.
invoiceNumber	Alphanumeric(12)	Echo of the request InvoiceNumber.
languageCode	Alphanumeric(1)	Echo of the request LanguageCode.
merchantNumber	Numeric(8)	Echo of the request MerchantNumber.
operatorId	Alphanumeric(8)	Echo of the request OperatorID.
receiptDisp	Alphanumeric(32)	PayFacto-generated receipt message. Example: `APPROVED-THANK-YOU`
referenceNumber	Alphanumeric(10)	Reference number obtained following successful approval.
sequenceNumber	Alphanumeric(12)	Sequence number generated by the banking acquirer.
serverNumber	Alphanumeric(4)	Identifies the PayFacto Network server that processed the transaction.
terminalDisp	Alphanumeric(24)	Transaction message displayed on the terminal or payment page. Example: `APPROVED`
terminalNumber	Numeric(5)	Identifies the terminal in the PayFacto Network used to process the transaction.
timeStamp	Alphanumeric(17)	Date and time the transaction was processed. Format: `YYYYMMDD-HHMMSSCC`. Example: `20240601-09000100`
trxCode	Alphanumeric(2)	Transaction type code. For the first billing of an Add Subscription this is always `00`.
trxDate	Numeric(8)	Transaction date at the banking acquirer. Format: `MMDDYYYY`. May differ from timeStamp.
trxMethod	Alphanumeric(3)	Summarizes how the transaction was processed. First character: `D` = swiped/inserted, `T` = manual entry. Third character: `1` = authorized. Example: `T@1`
trxTime	Numeric(6)	Transaction time at the banking acquirer. Format: `HHMMSS`. May differ from timeStamp.
trxType	Alphanumeric(1)	Type of card used. For credit card subscriptions this is always `C` = Credit.

Conditionally returned

Field	Type	Description
subscriptionId	Alphanumeric	★ Store this value. Returned on approval. Confirms the subscription was created. Required to manage or cancel the subscription later.
token	Alphanumeric(35)	★ Store this value. Returned when tokenization is enabled. Token linked to the cardholder for future token-based transactions against the same card.
accountType	Alphanumeric(1)	Only returned for debit transactions. `C` = Chequing, `S` = Savings.
avsResponse	Alphanumeric(1)	Only returned when AVS fields were submitted. Address Verification Service result code from the card issuer. Example: `Y` = address and ZIP match.
cvv2Response	Alphanumeric(1)	Only returned when `Cvv2Cvc2Number` was submitted. CVV2/CVC2 validation result. `M` = match, `N` = no match, `P` = not processed.
customerNumber	Alphanumeric(8)	Only returned when provided in the request. Echo of the request CustomerNumber.
cvmResults	Alphanumeric(6)	Only returned for chip (EMV) transactions. Cardholder Verification Method result. Print a signature line on the receipt if the first 2 digits are `03`, `05`, `43`, `45`, `1E`, or `5E`.
demoMode	Alphanumeric(4)	Only returned when the terminal is in demo mode. Value will be `true`.
emvAID	Alphanumeric(32)	Only returned for chip (EMV) transactions. EMV Application Identifier. Example: `AID: A000000003`
emvLabel	Alphanumeric(16)	Only returned for chip (EMV) transactions. Human-readable application label. Example: `VISA CREDIT`
emvTC	Alphanumeric(40)	Only returned for chip (EMV) transactions. EMV Transaction Cryptogram.
emvTSI	Alphanumeric(4)	Only returned for chip (EMV) transactions. EMV Transaction Status Information.
emvTVR	Alphanumeric(10)	Only returned for chip (EMV) transactions. EMV Terminal Verification Result.
errorDescription	Alphanumeric(50)	Only returned when the transaction is not approved. Human-readable description of the failure reason.
surchargeAmount	Numeric(11)	Only returned when a surcharge was applied. Left (0) padded.
taxAmount	Numeric(11)	Only returned when `taxAmount` was included in the request. Echo of the submitted tax amount.
terminalInvoiceNumber	Numeric(12)	Only returned for terminal transactions. Terminal-assigned invoice number.
tipAmount	Numeric(11)	Only returned when a tip was added at the terminal. Left (0) padded.

Response — Code Example

JSON — 200 Approved

{
  "returnCode":          "00",
  "authorizationNumber": "APPROV01",
  "transactionNumber":   "000111222333",
  "referenceNumber":     "0000000001",
  "amount":              "00000002999",
  "cardNumber":          "411111XXXXXX1111                       ",
  "cardType":            "V",
  "trxType":             "C",
  "trxCode":             "00",
  "trxDate":             "06012024",
  "trxTime":             "090000",
  "trxMethod":           "T@1",
  "timeStamp":           "20240601-09000100",
  "batchNumber":         "0001",
  "sequenceNumber":      "000011112222",
  "serverNumber":        "0001",
  "terminalNumber":      "00000",
  "bankTerminalNumber":  "00000001",
  "companyNumber":       "12345",
  "merchantNumber":      "53400000",
  "invoiceNumber":       "SUB000000001",
  "expirationDate":      "1226",
  "languageCode":        "E",
  "operatorId":          "USER0001",
  "cvv2Response":        "M",
  "subscriptionId":      "SUBSCRIP0001",
  "token":               "4111110000001111000000000000000001 ",
  "receiptDisp":         "APPROVED-THANK-YOU      ",
  "terminalDisp":        "APPROVED        "
}

JSON — Declined

{
  "returnCode":        "05",
  "errorDescription":  "TRANSACTION DECLINED",
  "terminalDisp":      "DECLINED        ",
  "receiptDisp":       "DECLINED                ",
  "transactionNumber": "000111222334",
  "timeStamp":         "20240601-09000200"
}

Error / Return Codes

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	Transaction approved	The first billing was approved and the recurring subscription has been created on the PayFacto platform.	Store the `subscriptionId` and `token`. Display the `authorizationNumber` on the customer receipt. No further action is required — subsequent billings are handled automatically by PayFacto.
05	Transaction declined	The first billing was declined by the issuing bank. The subscription was not created.	Retry the transaction or ask the cardholder to provide an alternative payment method. If the problem persists, contact PayFacto customer service.
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.
9013 / 9014 / 9015	Null / invalid / rejected: amount	`Amount` is null, does not match the required 11-digit length, or does not follow the specification.	Confirm the amount is left (0) padded to 11 digits and includes the decimal portion. If the problem persists, contact PayFacto customer service.
9016 / 9017 / 9018	Null / invalid / rejected: invoice number	`InvoiceNumber` is null, exceeds 12 characters, or does not follow the specification.	Check your application. The field must correspond to the specification in the documentation.
9019 / 9020 / 9021	Null / invalid / rejected: input type	`InputType` is null, not a single character, not in the list of accepted values, or not associated with the merchant.	Check your application. The field must correspond to the specification in the documentation.
9022 / 9023 / 9024	Null / invalid / rejected: card type	`CardType` is null, not a single character, or not in the list of accepted values.	Check your application. For terminal transactions send a blank space.
9025 / 9026 / 9027	Null / invalid / rejected: card number	`CardNumber` is null, exceeds 40 characters, or does not follow the specification.	For E-Commerce, ensure the card number is left-justified and padded to 40 characters.
9028 / 9029 / 9030	Null / invalid / rejected: expiration date	`ExpirationDate` is null, not 4 characters, or does not follow the specification.	Ensure the date is in `MMYY` format.
9031	"Null" value: POS terminal number	`MerchantTerminalNumber` is null or blank when a terminal transaction is being attempted.	For terminal transactions provide a valid terminal number; for E-Commerce send 5 blank spaces.
9032 / 9033	Invalid / rejected: POS terminal number	`MerchantTerminalNumber` does not follow the specification, or the merchant is not configured as a POS terminal merchant.	Check your application. The field must correspond to the specification in the documentation. If the problem persists, contact PayFacto customer service.
3666	One or more terminals are busy	All of the merchant's terminals are currently processing transactions.	Wait and retry. If the problem persists, contact PayFacto customer service.
3667	Semi-integrated terminal is busy	The target terminal is currently processing another transaction or a recovery is in progress.	Wait 15 seconds and retry. If the problem persists, contact PayFacto customer service.
3668	Waiting for a recovery	An error occurred with the semi-integrated terminal. A recovery must be completed before another operation can be processed.	Make sure everything is plugged in correctly. If needed, restart the driver and unplug then replug the terminal power. Wait 35 seconds and retry. If the problem persists, contact PayFacto customer service.
3777	Inexistent terminal and/or merchant	The merchant or terminal has not been configured in the Dispatcher module.	If the problem persists, contact PayFacto customer service.
9051	Time out	Transaction processing timed out. Often caused by an inactive Dispatcher module.	Retry the transaction. If the problem persists, contact PayFacto customer service.
9049 / 9050	Fatal error	A critical error occurred while processing the transaction.	Retry the transaction. If the problem persists, contact PayFacto customer service.