Reserves funds on a credit card without capturing or settling the transaction immediately. This is Step 1 of the Pre-Authorization / Completion flow. The four response values authorizationNumber, transactionNumber, invoiceNumber, and amount must be stored and passed to /v1/completion to capture the funds.
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 Pre-Authorization 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}. For terminal transactions (InputType=N), send CardNumber as 40 space characters and ExpirationDate as 4 space characters. E-Commerce transactions send 5 blank spaces for MerchantTerminalNumber.
Store These Response Values for Completion
A successful Pre-Authorization does not settle funds. You must persist the following four values from the response and supply them to /v1/completion to capture the transaction:
| Pre-Authorization Response | Pass to Completion as |
|---|---|
| authorizationNumber | OriginalAuthorizationNumber |
| transactionNumber | OriginalTransactionNumber |
| invoiceNumber | OriginalInvoiceNumber |
| amount | OriginalAmount |
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 space characters and ExpirationDate as 4 space characters. 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 transaction. Example: CLIENT12 |
| Amount | Numeric(11) | Amount to reserve on the cardholder's credit card, including the decimal portion, left (0) padded. Funds are not settled until /v1/completion is called. Example: 00000010000 = $100.00 |
| InvoiceNumber | Alphanumeric(12) | Merchant-generated invoice number. Must be stored and passed as OriginalInvoiceNumber in the subsequent Completion. Example: PRE000000001 |
| 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 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 |
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. Required to enable pre-tax tip prompts on the terminal. 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. |
| ThreeDsEci | Numeric(2) | 3-D Secure Electronic Commerce Indicator. Indicates the authentication outcome. Example: 05 = fully authenticated. |
| ThreeDsAuthValue | Alphanumeric(40) | 3-D Secure authentication value (CAVV for Visa, UCAF for Mastercard). Provided by the 3DS server after successful authentication. |
| ThreeDsXid | Alphanumeric(40) | 3-D Secure transaction identifier. Provided by the 3DS server. Used for 3DS 1.0. |
| ThreeDsVersion | Alphanumeric(8) | 3-D Secure protocol version used. Example: 2.1.0 |
| ThreeDsAuthTimestamp | Numeric(14) | Date and time of the 3-D Secure authentication. Format: YYYYMMDDHHMMSS. Example: 20240515150000 |
| ThreeDsDsTransId | Alphanumeric(40) | Directory Server Transaction ID assigned by the card scheme's 3DS server. Used for 3DS 2.x. Example: 9ac54b73-1234-4321-abcd-1234567890ab |
The example below uses the test endpoint and a sandbox API key, and shows an E-Commerce (InputType=I) Pre-Authorization. Replace credentials and base URL before going live. Store the four key response values to pass to /v1/completion.
# Pre-Authorization -- POST /v1/preAuthorization
# Step 1: Build the cleartext payload (InputType=I, E-Commerce)
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&Amount=00000010000&InvoiceNumber=PRE000000001&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/preAuthorization" \
-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) | β
Store for Completion. Authorization code from the issuing bank. Must be displayed on all customer receipts and passed as OriginalAuthorizationNumber to /v1/completion. Example: APPROV01 |
| transactionNumber | Numeric(12) | β
Store for Completion. Unique PayFacto gateway transaction identifier. Must be passed as OriginalTransactionNumber to /v1/completion. Example: 000111222333 |
| amount | Numeric(11) | β
Store for Completion. Echo of the reserved amount. Must be passed as OriginalAmount to /v1/completion. |
| invoiceNumber | Alphanumeric(12) | β
Store for Completion. Echo of the request InvoiceNumber. Must be passed as OriginalInvoiceNumber to /v1/completion. |
| bankTerminalNumber | Alphanumeric(8) | Terminal identifier at the banking acquirer that processed the transaction. |
| batchNumber | Numeric(4) | Batch number at the time the reservation was recorded. 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. |
| 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: 20240515-14300100 |
| trxCode | Alphanumeric(2) | Transaction type code. For a Pre-Authorization this is always 01. |
| 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. C = Credit, D = Debit. |
Conditionally returned
| Field | Type | Description |
|---|---|---|
| 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. 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. |
| 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. Token linked to the cardholder for future token-based transactions. |
{
"returnCode": "00",
"authorizationNumber": "APPROV01",
"transactionNumber": "000111222333",
"referenceNumber": "0000000001",
"amount": "00000010000",
"cardNumber": "411111XXXXXX1111 ",
"cardType": "V",
"trxType": "C",
"trxCode": "01",
"trxDate": "05152024",
"trxTime": "143000",
"trxMethod": "T@1",
"timeStamp": "20240515-14300100",
"batchNumber": "0001",
"sequenceNumber": "000011112222",
"serverNumber": "0001",
"terminalNumber": "00000",
"bankTerminalNumber": "00000001",
"companyNumber": "12345",
"merchantNumber": "53400000",
"invoiceNumber": "PRE000000001",
"expirationDate": "1226",
"languageCode": "E",
"operatorId": "USER0001",
"cvv2Response": "M",
"receiptDisp": "APPROVED-THANK-YOU ",
"terminalDisp": "APPROVED "
}{
"returnCode": "05",
"errorDescription": "TRANSACTION DECLINED",
"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 | Funds have been reserved on the cardholder's credit card. No settlement has occurred yet. | Store the authorizationNumber, transactionNumber, invoiceNumber, and amount. Call /v1/completion to capture funds when ready. |
| 05 | Transaction declined | The Pre-Authorization was declined by the issuing bank. No funds have been reserved. | Retry the transaction. 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 terminal transactions send 40 space characters. 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. For terminal transactions send 4 space characters. |
| 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. |