Obtains a credit card authorization for a financial transaction. Supports E-Commerce (Internet), MOTO (Mail Order / Telephone Order), and Semi-Integrated terminal input types.
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 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}.
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 CardNumber as 40 spaces and ExpirationDate as 4 spaces.
Required fields
| Field | Type | Description |
|---|---|---|
| CompanyNumber | Numeric(5) | Identifies the merchant on PayFacto's network. Provided by PayFacto. 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 in the smallest currency unit, zero-padded left. Includes decimal digits. Example: 00000000429 = $4.29 |
| InvoiceNumber | Alphanumeric(12) | Merchant-generated invoice number. 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. |
| 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. For InputType=N, send 40 space characters. |
| ExpirationDate | Numeric(4) | Card expiration date in MMYY format. For InputType=N, send 4 space characters. Example: 0726 = July 2026. |
| MerchantTerminalNumber | Numeric(5) | Identifies the terminal on PayFacto's network. For E-Commerce, 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 |
|---|---|---|
| Cvv2Cvc2Number | Numeric(4) | Card security code. 3 digits for Visa/Mastercard, 4 digits for Amex. Send 3 spaces to make it optional. |
| 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. |
| UserEchoData | Alphanumeric(256) | Custom data printed on the terminal receipt (Semi-Integrated only). Pipe-delimited line segments. Contact PayFacto integration before use. |
| taxAmount | Numeric(11) | Total tax amount included in Amount, zero-padded left. Required to enable pre-tax tip prompts on the terminal. Without it, tip is prompted 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. Values: isCredentialOnFile, isRecurring, isInstallment (mutually exclusive). |
The example below uses the test endpoint and a sandbox API key. Replace credentials and base URL before going live.
# Purchase β POST /v1/purchase
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&Amount=00000010000&InvoiceNumber=INV000000001&InputType=I&CardType=V&CardNumber=4111111111111111&ExpirationDate=1226&Cvv2Cvc2Number=123&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/purchase" -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) | 00 = approved. Any other value indicates a failure. Refer to the Return Code reference for the complete list. |
| authorizationNumber | Alphanumeric(8) | Authorization code issued on successful approval. 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. 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. Can be used when generating client receipts. |
| cardNumber | Alphanumeric(40) | Echo of the request CardNumber (masked). |
| cardType | Alphanumeric(1) | Card brand determined by the network. A=Amex, D=Debit, M=Mastercard, V=Visa, O=Discover, I=Diners, J=JCB, F=Datacandy. |
| companyNumber | Numeric(5) | Echo of the request CompanyNumber. |
| expirationDate | Numeric(4) | Echo of the request ExpirationDate. |
| 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 issued on successful transaction completion. |
| 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: 20240515-14300100 |
| trxCode | Alphanumeric(2) | Transaction type code. For a standard Purchase this is 00. |
| trxDate | Numeric(8) | Transaction date at the banking acquirer. Format: MMDDYYYY. May differ from timeStamp. |
| trxMethod | Alphanumeric(3) | Summarizes the transaction method. First char: D=Swiped, T=Manual. Third char: 1=Authorized. Example: D@1 |
| trxTime | Numeric(6) | Transaction time at the banking acquirer. Format: HHMMSS. May differ from timeStamp. |
| trxType | Alphanumeric(1) | Card type 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. Zero-padded left. Example: 00000000429 = $4.29 |
| cvmResults | Alphanumeric(6) | Only returned for chip 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. |
| cvv2Cvc2Status | Alphanumeric(1) | Only returned when Cvv2Cvc2Number was sent. M=Matches, N=Does not match, blank=Unknown. |
| demoMode | Alphanumeric(4) | Only returned when the terminal is in demo mode. Value will be true. |
| Alphanumeric(250) | Only returned when an email was entered on a hosted payment page. | |
| 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. |
| holderName | Alphanumeric(50) | Only returned when the cardholder name was entered on a hosted payment page. |
| iopIssuerConfirmationNumber | Alphanumeric(1β15) | Only returned when payment was guaranteed via Interac Online. Must be displayed on the merchant's confirmation screen. |
| iopIssuerName | Alphanumeric(1β30) | Only returned when payment was guaranteed via Interac Online. Issuer name in the customer's banking language. Must be displayed on the confirmation screen. |
| secureID | Alphanumeric(35) | Only returned for redirect / PayFacto Objects sessions. Used when retrieving the transaction result. |
| surchargeAmount | Numeric(11) | Only returned when a surcharge was applied. Zero-padded left. |
| 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. Zero-padded left. |
| token | Alphanumeric(35) | Only returned when tokenization is enabled. Represents the cardholder's card for future token-based transactions. |
{
"returnCode": "00",
"authorizationNumber": "APPROV99",
"transactionNumber": "000111222333",
"referenceNumber": "0000000001",
"amount": "00000010000",
"accountType": "C",
"cardNumber": "411111XXXXXX1111 ",
"cardType": "V",
"trxType": "C",
"trxCode": "00",
"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": "9121",
"errorDescription": "CARD DECLINED",
"terminalDisp": "DECLINED ",
"receiptDisp": "DECLINED ",
"transactionNumber": "000111222334",
"timeStamp": "20240515-14300200"
}The following codes are specific to this endpoint. For the complete catalogue see the Return Code Index.
| Return Code | Meaning | When it occurs | Recommended Action |
|---|---|---|---|
| 00 | 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. |
| Non-00 | Declined / Error | Transaction was declined by the issuer or a processing error occurred. Check errorDescription for details. | Do not retry automatically for issuer declines (customer action required). For network errors, retry with exponential backoff. Refer to the Return Code Index for code-specific guidance. |
| Timeout | Unknown state | No response received within the expected window β transaction state is unknown. | Use the Recover endpoint with the original InvoiceNumber to retrieve the transaction result before retrying. |