PayFacto API - v1.0 - POST /v1/purchase

PayFacto API - v1.0 - POST /v1/purchase

POST   /v1/purchase

Purchase

Obtains a credit card authorization for a financial transaction. Supports E-Commerce (Internet), MOTO (Mail Order / Telephone Order), and Semi-Integrated terminal input types.

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

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

2

  Request

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

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

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
CustomerNumberAlphanumeric(8)Merchant-assigned customer identifier. Associates a client record with the transaction. Example: CLIENT12
AmountNumeric(11)Transaction amount in the smallest currency unit, zero-padded left. Includes decimal digits. Example: 00000000429 = $4.29
InvoiceNumberAlphanumeric(12)Merchant-generated invoice number. May be unique or reused per merchant needs. Example: 123456789123
InputTypeAlphanumeric(1)How the transaction is initiated. N = terminal/pinpad (Semi-Integrated), I = Internet/E-Commerce, M = MOTO, U = Unattended.
CardTypeAlphanumeric(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.
CardNumberAlphanumeric(40)Cardholder's card number, left-justified and space-padded. For InputType=N, send 40 space characters.
ExpirationDateNumeric(4)Card expiration date in MMYY format. For InputType=N, send 4 space characters. Example: 0726 = July 2026.
MerchantTerminalNumberNumeric(5)Identifies the terminal on PayFacto's network. For E-Commerce, send 5 blank spaces. Example: 12345
LanguageCodeAlphanumeric(1)Language for PayFacto responses and hosted pages. F = French, E = English.
CurrencyCodeAlphanumeric(3)Currency of the transaction (indicative only). CAD = Canadian dollars, USD = US dollars (requires a US merchant number).
OperatorIDAlphanumeric(8)Identifies the cashier, agent, or system that initiated the transaction. Example: USER0001

Optional fields

FieldTypeDescription
Cvv2Cvc2NumberNumeric(4)Card security code. 3 digits for Visa/Mastercard, 4 digits for Amex. Send 3 spaces to make it optional.
CardHolderAddressAlphanumeric(20)Cardholder's billing address. Used for Address Verification Service (AVS) validation.
CardHolderPostalCodeAlphanumeric(9)Cardholder's billing postal code for AVS. Right-padded with spaces to 9 characters. Example: J6A2T8
CardHolderAVVAlphaHex(40)Verified by Visa (VbV) authentication token. Required for 3-D Secure Visa transactions.
xIDAlphaHex(40)Transaction identifier returned by a successful Verified by Visa login. Required for 3-D Secure flows.
uCAFAlphanumeric(64)Mastercard SecureCode authentication data. Required for 3-D Secure Mastercard transactions.
UserEchoDataAlphanumeric(256)Custom data printed on the terminal receipt (Semi-Integrated only). Pipe-delimited line segments. Contact PayFacto integration before use.
taxAmountNumeric(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
TrxOptionAlpha(50)Adds transaction-level options. For Credential-on-File initial transactions, pass twice: TrxOption=isCredentialOnFile&TrxOption=isFirst. Values: isCredentialOnFile, isRecurring, isInstallment (mutually exclusive).
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
# 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"
4

  Response

Always returned

FieldTypeDescription
returnCodeAlphanumeric(4)00 = approved. Any other value indicates a failure. Refer to the Return Code reference for the complete list.
authorizationNumberAlphanumeric(8)Authorization code issued on successful approval. Mandatory to display on all customer receipts. Example: APPROV99
transactionNumberNumeric(12)Unique PayFacto gateway transaction identifier. Store this β€” required for Void and Refund operations. Example: 000111222333
amountNumeric(11)Echo of the requested transaction amount.
accountTypeAlphanumeric(1)Account type used. C = Chequing, S = Savings.
bankTerminalNumberAlphanumeric(8)Terminal identifier at the banking acquirer that processed the transaction.
batchNumberNumeric(4)Batch number used by the terminal. Can be used when generating client receipts.
cardNumberAlphanumeric(40)Echo of the request CardNumber (masked).
cardTypeAlphanumeric(1)Card brand determined by the network. A=Amex, D=Debit, M=Mastercard, V=Visa, O=Discover, I=Diners, J=JCB, F=Datacandy.
companyNumberNumeric(5)Echo of the request CompanyNumber.
expirationDateNumeric(4)Echo of the request ExpirationDate.
invoiceNumberAlphanumeric(12)Echo of the request InvoiceNumber.
languageCodeAlphanumeric(1)Echo of the request LanguageCode.
merchantNumberNumeric(8)Echo of the request MerchantNumber.
operatorIdAlphanumeric(8)Echo of the request OperatorID.
receiptDispAlphanumeric(32)PayFacto-generated receipt message. Can be used to produce a receipt. Example: APPROVED-THANK-YOU
referenceNumberAlphanumeric(10)Reference number issued on successful transaction completion.
sequenceNumberAlphanumeric(12)Sequence number generated by the banking acquirer.
serverNumberAlphanumeric(4)Identifies the PayFacto Network server that processed the transaction.
terminalDispAlphanumeric(24)Transaction message displayed on the terminal or payment page. Example: APPROVED
terminalNumberNumeric(5)Identifies the terminal in the PayFacto Network used to process the transaction.
timeStampAlphanumeric(17)Date and time the transaction was processed. Format: YYYYMMDD-HHMMSSCC. Example: 20240515-14300100
trxCodeAlphanumeric(2)Transaction type code. For a standard Purchase this is 00.
trxDateNumeric(8)Transaction date at the banking acquirer. Format: MMDDYYYY. May differ from timeStamp.
trxMethodAlphanumeric(3)Summarizes the transaction method. First char: D=Swiped, T=Manual. Third char: 1=Authorized. Example: D@1
trxTimeNumeric(6)Transaction time at the banking acquirer. Format: HHMMSS. May differ from timeStamp.
trxTypeAlphanumeric(1)Card type used. C = Credit, D = Debit, F = Fidelity/Gift.

Conditionally returned

FieldTypeDescription
customerNumberAlphanumeric(8)Only returned when provided in the request. Echo of the request CustomerNumber.
avsStatusAlphanumeric(1)Only returned when CardHolderAddress or CardHolderPostalCode were sent. M=Both match, N=Neither match, Z=Postal only, A=Address only, U=Unavailable.
cashbackAmountNumeric(11)Only returned when a cash-back amount was applied. Zero-padded left. Example: 00000000429 = $4.29
cvmResultsAlphanumeric(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.
cvv2Cvc2StatusAlphanumeric(1)Only returned when Cvv2Cvc2Number was sent. M=Matches, N=Does not match, blank=Unknown.
demoModeAlphanumeric(4)Only returned when the terminal is in demo mode. Value will be true.
emailAlphanumeric(250)Only returned when an email was entered on a hosted payment page.
emvAIDAlphanumeric(32)Only returned for chip (EMV) transactions. EMV Application Identifier. Example: AID: A000000277
emvLabelAlphanumeric(16)Only returned for chip (EMV) transactions. Human-readable application label. Example: Visa, Interac
emvTCAlphanumeric(40)Only returned for chip (EMV) transactions. EMV Transaction Cryptogram. Example: TC: A2E51243D4C7E551
emvTSIAlphanumeric(4)Only returned for chip (EMV) transactions. EMV Transaction Status Information.
emvTVRAlphanumeric(10)Only returned for chip (EMV) transactions. EMV Terminal Verification Result.
errorDescriptionAlphanumeric(50)Only returned when the transaction is not approved. Human-readable description of the failure reason.
holderNameAlphanumeric(50)Only returned when the cardholder name was entered on a hosted payment page.
iopIssuerConfirmationNumberAlphanumeric(1–15)Only returned when payment was guaranteed via Interac Online. Must be displayed on the merchant's confirmation screen.
iopIssuerNameAlphanumeric(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.
secureIDAlphanumeric(35)Only returned for redirect / PayFacto Objects sessions. Used when retrieving the transaction result.
surchargeAmountNumeric(11)Only returned when a surcharge was applied. Zero-padded left.
taxAmountNumeric(11)Only returned when taxAmount was included in the request. Echo of the submitted tax amount.
terminalInvoiceNumberNumeric(12)Only returned for terminal transactions. Terminal-assigned invoice number.
threeDSStatusAlphanumeric(1)Only returned when 3-D Secure data was sent. P=Passed, F=Failed, N=Not validated.
tipAmountNumeric(11)Only returned when a tip was added at the terminal. Zero-padded left.
tokenAlphanumeric(35)Only returned when tokenization is enabled. Represents the cardholder's card for future token-based transactions.
5

  Response β€” Code Example

JSON β€” 200 Approved
{
  "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        "
}
JSON β€” Declined / Error
{
  "returnCode":        "9121",
  "errorDescription":  "CARD DECLINED",
  "terminalDisp":      "DECLINED        ",
  "receiptDisp":       "DECLINED                ",
  "transactionNumber": "000111222334",
  "timeStamp":         "20240515-14300200"
}
6

  Error / Return Codes

The following codes are specific to this endpoint. For the complete catalogue see the Return Code Index.

Return CodeMeaningWhen it occursRecommended Action
00ApprovedThe 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-00Declined / ErrorTransaction 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.
TimeoutUnknown stateNo 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.

    • Related Articles

    • PayFacto API - v1.0 - POST /v1/refund

      POST /v1/refund Refund Returns the value of a purchase in whole or in part. A successful refund credits the cardholder's account and debits the merchant's account. Refunds are not matched to a purchase at the PayFacto host. Version: v1.0 | Last ...

    • PayFacto API - v1.0 - POST /v1/void

      POST /v1/void Void Cancels a previously captured transaction that has not yet been included in a bank deposit. Use this endpoint to void a credit card purchase, refund, completion, or force. A successful void ensures the original transaction is never ...

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

    • PayFacto API - v1.0 - POST /v1/refundWithTuid

      POST /v1/refundWithTuid Refund with TUID Performs a refund in the same way as the standard Refund endpoint, except that it identifies the original transaction using a TUID (PayFacto switch unique transaction identifier) instead of card data. Use this ...

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