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

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

POST   /v1/verifyAccount

Verify Account

Determines whether a credit card is valid, and optionally performs address verification (AVS) and/or CVD verification at the same time. No funds are captured.

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 Verify Account 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/verifyAccount
ℹ️

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. Note: Amount is not sent for this transaction β€” no funds are captured.

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
InvoiceNumberAlphanumeric(12)Merchant-generated invoice number associated with the transaction. 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. 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. When provided, the response includes cvv2Cvc2Status.
CardHolderAddressAlphanumeric(20)Cardholder's billing address for Address Verification Service (AVS). When provided, the response includes avsStatus.
CardHolderPostalCodeAlphanumeric(9)Cardholder's billing postal code for AVS. Right-padded with spaces to 9 characters. Example: J6A2T8
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
# Verify Account β€” POST /v1/verifyAccount
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345\
&MerchantNumber=53400000\
&CustomerNumber=CLIENT12\
&InvoiceNumber=INV000000002\
&InputType=I\
&CardType=V\
&CardNumber=4111111111111111\
&ExpirationDate=1226\
&Cvv2Cvc2Number=123\
&CardHolderAddress=123 Main St\
&CardHolderPostalCode=H3Z2Y7  \
&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/verifyAccount" \
  -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=card is valid. Any other value indicates the card could not be verified. Refer to the Return Code reference for the complete list.
authorizationNumberAlphanumeric(8)Authorization code issued on successful verification. Example: APPROV99
transactionNumberNumeric(12)Unique PayFacto gateway transaction identifier. Store this for auditing purposes. Example: 000111222333
amountNumeric(11)Always returned as zero for a Verify Account transaction (no funds are captured).
accountTypeAlphanumeric(1)Account type used. C=Chequing, S=Savings.
bankTerminalNumberAlphanumeric(8)Terminal identifier at the banking acquirer that processed the verification.
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. Example: APPROVED-THANK-YOU
referenceNumberAlphanumeric(10)Reference number issued on successful verification.
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 Verify Account this is 08.
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: T@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.
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 Verified (with AVS & CVD)
{
  "returnCode":          "00",
  "authorizationNumber": "APPROV99",
  "transactionNumber":   "000111222444",
  "referenceNumber":     "0000000002",
  "amount":              "00000000000",
  "accountType":         "C",
  "cardNumber":          "411111XXXXXX1111                       ",
  "cardType":            "V",
  "trxType":             "C",
  "trxCode":             "08",
  "trxDate":             "05152024",
  "trxTime":             "150001",
  "trxMethod":           "T@1",
  "timeStamp":           "20240515-15000100",
  "avsStatus":           "M",
  "cvv2Cvc2Status":      "M",
  "batchNumber":         "0001",
  "sequenceNumber":      "000011112223",
  "serverNumber":        "0001",
  "terminalNumber":      "00001",
  "bankTerminalNumber":  "00000001",
  "companyNumber":       "12345",
  "merchantNumber":      "53400000",
  "invoiceNumber":       "INV000000002",
  "expirationDate":      "1226",
  "languageCode":        "E",
  "operatorId":          "USER0001",
  "receiptDisp":         "APPROVED-THANK-YOU      ",
  "terminalDisp":        "APPROVED        "
}
JSON β€” Declined / Invalid Card
{
  "returnCode":        "9121",
  "errorDescription":  "CARD DECLINED",
  "terminalDisp":      "DECLINED        ",
  "receiptDisp":       "DECLINED                ",
  "transactionNumber": "000111222445",
  "timeStamp":         "20240515-15000200"
}
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
00VerifiedThe card is valid and was successfully verified by the issuer.Check avsStatus and cvv2Cvc2Status if those optional fields were requested. Store the transactionNumber for auditing.
Non-00Not verifiedThe card could not be verified. Check errorDescription for details.Do not proceed with a payment on this card. Prompt the customer to provide a different card. Refer to the Return Code Index for code-specific guidance.
TimeoutUnknown stateNo response received within the expected window.Use the Recover endpoint with the original InvoiceNumber to retrieve the result before retrying.

    • Related Articles

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