Obtains a credit card authorization for a financial transaction using a previously stored card token instead of raw card data. Supports E-Commerce (Internet), MOTO (Mail Order / Telephone Order).
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 Purchase with Token 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}.
Card Token
A Token is a security token linked to a client's credit card. Tokens are returned by the PayFacto platform when tokenization is enabled on a prior transaction. The token must be active, have a valid card on file, and not be expired.
All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. For terminal transactions (InputType=N), send MerchantTerminalNumber as the assigned terminal number; for E-Commerce, send 5 blank spaces.
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 transaction. Example: CLIENT12 |
| Amount | Numeric(11) | Transaction amount including the decimal portion, left (0) padded. Example: 00000010000 = $100.00 |
| InvoiceNumber | Alphanumeric(12) | Merchant-generated invoice number associated with the transaction. May be unique or reused per merchant needs. Example: 123456789123 |
| InputType | Alphanumeric(1) | How the transaction is initiated. N = terminal/pinpad (Semi-Integrated), I = Internet/E-Commerce, M = MOTO, U = Unattended. |
| Token | Alphanumeric(35) | Security token linked to the client's credit card, used in place of raw card data. Returned by PayFacto when tokenization is enabled on a prior transaction. Example: 2079wo00wbwp916d3l2mutd8t7965o99mp9 |
| 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 hosted pages. 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 |
Optional fields
| Field | Type | Description |
|---|---|---|
| CardHolderAddress | Alphanumeric(20) | Cardholder's billing address. Used for Address Verification Service (AVS) validation. |
| CardHolderPostalCode | Alphanumeric(9) | Cardholder's billing postal code for AVS. Right-padded with spaces to 9 characters. Example: J6A2T8 |
| CardHolderAVV | AlphaHex(40) | Verified by Visa (VbV) authentication token. Required for 3-D Secure Visa transactions. |
| xID | AlphaHex(40) | Transaction identifier returned by a successful Verified by Visa login. Required for 3-D Secure flows. |
| uCAF | Alphanumeric(64) | Mastercard SecureCode authentication data. Required for 3-D Secure Mastercard transactions. |
| taxAmount | Numeric(11) | Total tax amount included in Amount, left (0) padded. Required to enable pre-tax tip prompts on the terminal. Without it, tip is calculated on the full amount including tax. Example: 00000000374 = $3.74 |
| TrxOption | Alpha(50) | Adds transaction-level options. For Credential-on-File initial transactions, pass twice: TrxOption=isCredentialOnFile&TrxOption=isFirst. 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. |
The example below uses the test endpoint and a sandbox API key. Replace credentials and base URL before going live.
# Purchase with Token β POST /v1/purchaseWithToken
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&Amount=00000010000&InvoiceNumber=INV000000001&InputType=I&Token=2079wo00wbwp916d3l2mutd8t7965o99mp9&MerchantTerminalNumber= &LanguageCode=E&CurrencyCode=CAD&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/purchaseWithToken" \
-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 exact status of the transaction result. 00 = approved. All other values indicate a failure. Refer to Section 6 for endpoint-specific codes. |
| authorizationNumber | Alphanumeric(8) | Authorization code obtained following the successful completion of the transaction. Mandatory to display on all customer receipts. Example: APPROV99 |
| transactionNumber | Numeric(12) | Unique PayFacto gateway transaction identifier. Store this β required for Void and Refund operations. Example: 000111222333 |
| amount | Numeric(11) | Echo of the requested transaction amount. |
| accountType | Alphanumeric(1) | Account type used for the transaction. C = Chequing, S = Savings. |
| bankTerminalNumber | Alphanumeric(8) | Terminal identifier at the banking acquirer that processed the transaction. |
| batchNumber | Numeric(4) | Batch number used by the terminal when the transaction was processed. Can be used when generating client receipts. Example: 0001 |
| cardNumber | Alphanumeric(40) | Masked card number resolved from the token. |
| cardType | Alphanumeric(1) | Card brand determined by the network. A = Amex, D = Debit, F = Datacandy, I = Diners, J = JCB, M = Mastercard, O = Discover, V = Visa. |
| companyNumber | Numeric(5) | Echo of the request CompanyNumber. |
| expirationDate | Numeric(4) | Expiration date of the card resolved from the token, 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. Can be used to produce a receipt. Example: APPROVED-THANK-YOU |
| referenceNumber | Alphanumeric(10) | Reference number obtained following the successful completion of the transaction. |
| 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 on the payment server. Format: YYYYMMDD-HHMMSSCC. Example: 20240515-14300100 |
| trxCode | Alphanumeric(2) | Transaction type code. For a Purchase with Token this is always 52. |
| 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, 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. C = Credit, D = Debit, F = Fidelity/Gift. |
Conditionally returned
| Field | Type | Description |
|---|---|---|
| customerNumber | Alphanumeric(8) | Only returned when provided in the request. Echo of the request CustomerNumber. |
| avsStatus | Alphanumeric(1) | Only returned when CardHolderAddress or CardHolderPostalCode were sent. M = Both match, N = Neither match, Z = Postal only, A = Address only, U = Unavailable. |
| cashbackAmount | Numeric(11) | Only returned when a cash-back amount was applied. Left (0) padded. |
| 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: A000000277 |
| emvLabel | Alphanumeric(16) | Only returned for chip (EMV) transactions. Human-readable application label. Example: Visa, Interac |
| emvTC | Alphanumeric(40) | Only returned for chip (EMV) transactions. EMV Transaction Cryptogram. Example: TC: A2E51243D4C7E551 |
| 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. |
| threeDSStatus | Alphanumeric(1) | Only returned when 3-D Secure data was sent. P = Passed, F = Failed, N = Not validated. |
| tipAmount | Numeric(11) | Only returned when a tip was added at the terminal. Left (0) padded. |
| token | Alphanumeric(35) | Only returned when tokenization is enabled. Echo or updated token linked to the cardholder for future token-based transactions. |
{
"returnCode": "00",
"authorizationNumber": "APPROV99",
"transactionNumber": "000111222333",
"referenceNumber": "0000000001",
"amount": "00000010000",
"accountType": "C",
"cardNumber": "411111XXXXXX1111 ",
"cardType": "V",
"trxType": "C",
"trxCode": "52",
"trxDate": "05152024",
"trxTime": "143001",
"trxMethod": "T@1",
"timeStamp": "20240515-14300100",
"batchNumber": "0001",
"sequenceNumber": "000011112222",
"serverNumber": "0001",
"terminalNumber": "00001",
"bankTerminalNumber": "00000001",
"companyNumber": "12345",
"merchantNumber": "53400000",
"invoiceNumber": "INV000000001",
"expirationDate": "1226",
"languageCode": "E",
"operatorId": "USER0001",
"receiptDisp": "APPROVED-THANK-YOU ",
"terminalDisp": "APPROVED "
}{
"returnCode": "9126",
"errorDescription": "INVALID TOKEN",
"terminalDisp": "DECLINED ",
"receiptDisp": "DECLINED ",
"transactionNumber": "000111222334",
"timeStamp": "20240515-14300200"
}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 transaction was authorized successfully by the card issuer. | Display the authorizationNumber on the customer receipt. Store the transactionNumber for potential Void or Refund operations. |
| 05 | Transaction declined | The transaction was declined by the issuing bank. | Retry the transaction. If the problem persists, contact PayFacto customer service. |
| 51 | Insufficient funds | The client does not have sufficient funds in the account linked to the token's card. | Ask the customer to use a different payment method. |
| 54 | Expired card | The card associated with the token has expired at the issuing bank. | Update the customer's card information in their profile and obtain a new token. |
| 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, or not in the list of accepted values (N, I, M, U) or not associated with the merchant. | Check your application. The field must correspond to the specification in the documentation. |
| 9126 | Invalid token | The received token does not follow the length described in the documentation or is valid but not associated with the merchant or client. | Verify your data. The field must match the specification. If it does, contact PayFacto customer service. |
| 9127 | Inactive client | The received token matches a client who has been removed from the recurrence system. | Verify your data. Reactivate the client or use a different token. |
| 9133 | Token with expired credit card | The received token matches a customer whose credit card on file is expired. | Obtain the customer's new credit card information, update their profile, and re-tokenize before processing the transaction. |
| 9134 | Token with no credit card | The received token corresponds to a customer who has no credit card in their profile. | Obtain the customer's credit card information, update their profile, and obtain a new token before processing the transaction. |
| 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. |