Captures and finalizes a previously approved Pre-Authorization, converting the reserved funds into a settled charge. The completion amount must not exceed the amount reserved in the original Pre-Authorization for Card Not Present transactions. Only one Completion per Pre-Authorization is permitted.
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 must match the company and merchant numbers of the original Pre-Authorization.
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 spaces and ExpirationDate as 4 spaces.
Pre-Authorization / Completion Flow
This endpoint is the second step of the Pre-Authorization / Completion flow. A Pre-Authorization (/v1/preAuthorization or /v1/preAuthorizationWithToken) must be approved first. The OriginalAuthorizationNumber, OriginalTransactionNumber, and OriginalInvoiceNumber from the Pre-Authorization response are all required here. The completion amount must be equal to or lower than the pre-authorized amount. Only one Completion per Pre-Authorization is allowed β to release the reservation without charging, use Void (/v1/void).
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.
Required fields
| Field | Type | Description |
|---|---|---|
| CompanyNumber | Numeric(5) | Identifies the merchant on PayFacto's network. Must match the company number of the original Pre-Authorization. Example: 12345 |
| MerchantNumber | Numeric(8) | Identifies the merchant to PayFacto's network. Must match the merchant number of the original Pre-Authorization. Example: 53400000 |
| CustomerNumber | Alphanumeric(8) | Merchant-assigned customer identifier. Associates a client record with the transaction. Example: CLIENT12 |
| Amount | Numeric(11) | Amount to capture, including the decimal portion, left (0) padded. Must be equal to or lower than the OriginalAmount reserved in the Pre-Authorization. Example: 00000010000 = $100.00 |
| InvoiceNumber | Alphanumeric(12) | Merchant-generated invoice number for this Completion transaction. May be unique or reused per merchant needs. Example: CMP000000001 |
| InputType | Alphanumeric(1) | How the transaction is initiated. N = terminal/pinpad (Semi-Integrated), I = Internet/E-Commerce, M = MOTO, U = Unattended. Must match the input type of the original Pre-Authorization. |
| 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. |
| ExpirationDate | Numeric(4) | Card expiration date in MMYY format. The card issuer is responsible for expiration date validation. For InputType=N, send 4 space characters. Example: 1226 |
| 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 |
| OriginalInvoiceNumber | Alphanumeric(12) | The merchant's invoice number from the original Pre-Authorization, as generated in the initial request and returned in its response. Must match the invoice number recorded on the original Pre-Authorization exactly. Example: INV000000001 |
| OriginalAuthorizationNumber | Alphanumeric(8) | The authorization number obtained in the response of the original Pre-Authorization. Example: APPROV99 |
| OriginalTransactionNumber | Numeric(12) | The transaction number obtained in the response of the original Pre-Authorization. Example: 000111222333 |
| OriginalAmount | Numeric(11) | The original amount of the Pre-Authorization, including the decimal portion, left (0) padded. Used to validate that the completion amount does not exceed the reserved amount. Example: 00000010000 = $100.00 |
Optional fields
| Field | Type | Description |
|---|---|---|
| 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, and shows an E-Commerce (InputType=I) Completion. Replace credentials and base URL before going live.
# Completion β POST /v1/completion
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&Amount=00000010000&InvoiceNumber=CMP000000001&InputType=I&CardType=V&CardNumber=4111111111111111 &ExpirationDate=1226&MerchantTerminalNumber= &LanguageCode=E&CurrencyCode=CAD&OperatorID=USER0001&OriginalInvoiceNumber=INV000000001&OriginalAuthorizationNumber=APPROV99&OriginalTransactionNumber=000111222333&OriginalAmount=00000010000"
# 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/completion" \
-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 successful approval. Mandatory to display on all customer receipts. Example: APPROV99 |
| transactionNumber | Numeric(12) | Unique PayFacto gateway transaction identifier for this Completion. Store this value for potential Void operations. Example: 000111222444 |
| amount | Numeric(11) | Echo of the requested completion 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) | Echo of the request CardNumber (masked). |
| 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) | Echo of the request ExpirationDate, 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 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 Completion this is always 02. |
| 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. |
| 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. |
| 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": "APPROV99",
"transactionNumber": "000111222444",
"referenceNumber": "0000000002",
"amount": "00000010000",
"accountType": "C",
"cardNumber": "411111XXXXXX1111 ",
"cardType": "V",
"trxType": "C",
"trxCode": "02",
"trxDate": "05152024",
"trxTime": "150001",
"trxMethod": "T@1",
"timeStamp": "20240515-15000100",
"batchNumber": "0001",
"sequenceNumber": "000011112223",
"serverNumber": "0001",
"terminalNumber": "00001",
"bankTerminalNumber": "00000001",
"companyNumber": "12345",
"merchantNumber": "53400000",
"invoiceNumber": "CMP000000001",
"expirationDate": "1226",
"languageCode": "E",
"operatorId": "USER0001",
"receiptDisp": "APPROVED-THANK-YOU ",
"terminalDisp": "APPROVED "
}{
"returnCode": "9110",
"errorDescription": "AMOUNT TOO HIGH FOR TRANSACTION",
"terminalDisp": "DECLINED ",
"receiptDisp": "DECLINED ",
"transactionNumber": "000111222445",
"timeStamp": "20240515-15000200"
}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 Pre-Authorization was completed and the charge was captured successfully. | Display the authorizationNumber on the customer receipt. Store the transactionNumber for potential Void operations. |
| 05 | Transaction declined | The Completion was declined by the issuing bank. | 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 (N, I, M, U), 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; for E-Commerce use one of the accepted card type codes. |
| 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, send the card number left-justified and space-padded to 40 characters. |
| 9028 / 9029 / 9030 | Null / invalid / rejected: expiration date | ExpirationDate is null, not 4 characters, or does not follow the specification. | For terminal transactions send 4 space characters. For E-Commerce, send in MMYY format. |
| 9056 / 9057 / 9058 | Null / invalid / rejected: original invoice number | OriginalInvoiceNumber is null, exceeds 12 characters, or was rejected because it does not follow the specification. | Make sure you are sending the invoice number exactly as it appeared on the original Pre-Authorization request. |
| 9062 | Company number mismatch | The original transaction number exists but is not associated with your company number. | Check your application. Make sure you have the correct original transaction number and that the original Pre-Authorization was processed under your company. |
| 9063 | Merchant number mismatch | The original transaction number exists but is not associated with your merchant number. | Check your application. Make sure you have the correct original transaction number and that the original Pre-Authorization was processed under your merchant number. |
| 9064 | Original invoice number mismatch | The OriginalInvoiceNumber sent does not match the invoice number recorded on the original Pre-Authorization. | The original invoice number must be identical to the one used in the original Pre-Authorization request. |
| 9066 | Invalid original transaction status | The original Pre-Authorization's status does not allow a Completion β it was most likely declined or cancelled. | Make sure the original Pre-Authorization was approved. If the problem persists, contact PayFacto customer service. |
| 9067 | Original authorization number mismatch | The OriginalAuthorizationNumber exists but is not associated with your merchant number, or the original transaction number may be incorrect. | Make sure the OriginalAuthorizationNumber matches the value returned in the original Pre-Authorization response. |
| 9068 | Original transaction number not found | No transaction matching the submitted OriginalTransactionNumber exists in the system. | Check your application. Make sure you are sending the correct transaction number from the original Pre-Authorization response. |
| 9069 | Original transaction is not a pre-authorization | The original transaction referenced is not a Pre-Authorization. Completions can only be applied to Pre-Authorization transactions. | Make sure you have the correct original transaction number and that it corresponds to an approved Pre-Authorization. |
| 9108 | Completion error | An error occurred while completing the Pre-Authorization. | Retry the transaction. If the problem persists, contact PayFacto customer service. |
| 9109 | Preauthorization already completed | A Completion has already been performed for this Pre-Authorization. Only one Completion per Pre-Authorization is allowed. | Check your application. Make sure the Completion has not already been performed for this transaction. |
| 9110 | Amount too high for transaction | The completion Amount is higher than the OriginalAmount reserved in the Pre-Authorization. | Check your application. The completion amount must be equal to or lower than the pre-authorized amount. |
| 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. |