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

Captures and finalizes a previously approved IAP (Interac Automated Payment) Pre-Authorization, converting the reserved Interac debit funds into a settled charge. The completion amount must not exceed the amount reserved in the original IAP Pre-Authorization. Only one Completion per IAP Pre-Authorization is permitted.

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 must match the company and merchant numbers of the original IAP 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 space characters and ExpirationDate as 4 space characters.

🏦

IAP — Interac Automated Payment

IAP (Interac Automated Payment) endpoints handle Interac debit transactions processed through integrated systems. This endpoint is exclusively for IAP transactions and must only be used as the second step following an approved /v1/iapPreAuthorization. For credit card completions, use /v1/completion instead.

🔄

IAP Pre-Authorization / Completion Flow

This endpoint is the second step of the IAP Pre-Authorization / Completion flow. An IAP Pre-Authorization (/v1/iapPreAuthorization) must be approved first. The OriginalAuthorizationNumber, OriginalTransactionNumber, and OriginalInvoiceNumber from the IAP 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 IAP Pre-Authorization is allowed — to release the reservation without charging, use Void (/v1/void).

Request

POST https://test.api.payfacto.cloud/v1/iapCompletion

ℹ️

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 IAP Pre-Authorization. Example: `12345`
MerchantNumber	Numeric(8)	Identifies the merchant to PayFacto's network. Must match the merchant number of the original IAP 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 IAP Pre-Authorization. Example: `00000010000` = $100.00
InvoiceNumber	Alphanumeric(12)	Merchant-generated invoice number for this IAP 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 IAP 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. 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 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`
OriginalInvoiceNumber	Alphanumeric(12)	The merchant's invoice number from the original IAP Pre-Authorization request and response. Must match the invoice number recorded on the original IAP Pre-Authorization exactly. Example: `INV000000001`
OriginalAuthorizationNumber	Alphanumeric(8)	The authorization number returned in the response of the original IAP Pre-Authorization. Example: `APPROV99`
OriginalTransactionNumber	Numeric(12)	The transaction number returned in the response of the original IAP Pre-Authorization. Example: `000111222333`
OriginalAmount	Numeric(11)	The original amount of the IAP 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. 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.

Request — Code Example

⚠️

The example below uses the test endpoint and a sandbox API key, and shows a terminal (InputType=N) IAP Completion. Replace credentials and base URL before going live.

cURL

# IAP Completion -- POST /v1/iapCompletion
# Step 1: Build the cleartext payload (InputType=N, terminal reads card directly)
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&Amount=00000010000&InvoiceNumber=CMP000000001&InputType=N&CardType= &CardNumber=                                        &ExpirationDate=    &MerchantTerminalNumber=12345&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/iapCompletion" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "auth-api-key=YOUR_TEST_API_KEY&payload=$ENCODED"

Response

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 of the IAP Completion. Mandatory to display on all customer receipts. Example: `APPROV99`
transactionNumber	Numeric(12)	Unique PayFacto gateway transaction identifier for this IAP 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 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. `D` = Debit (Interac) is expected for IAP transactions.
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 an IAP 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: `D@1`
trxTime	Numeric(6)	Transaction time at the banking acquirer. Format: `HHMMSS`. May differ from timeStamp.
trxType	Alphanumeric(1)	Type of card used. For IAP transactions this will be `D` = Debit.

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: `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.

Response — Code Example

JSON — 200 Approved

{
  "returnCode":          "00",
  "authorizationNumber": "APPROV99",
  "transactionNumber":   "000111222444",
  "referenceNumber":     "0000000002",
  "amount":              "00000010000",
  "accountType":         "C",
  "cardNumber":          "457300XXXXXX0001                       ",
  "cardType":            "D",
  "trxType":             "D",
  "trxCode":             "02",
  "trxDate":             "05152024",
  "trxTime":             "150001",
  "trxMethod":           "D@1",
  "timeStamp":           "20240515-15000100",
  "batchNumber":         "0001",
  "sequenceNumber":      "000011112223",
  "serverNumber":        "0001",
  "terminalNumber":      "12345",
  "bankTerminalNumber":  "00000001",
  "companyNumber":       "12345",
  "merchantNumber":      "53400000",
  "invoiceNumber":       "CMP000000001",
  "expirationDate":      "    ",
  "languageCode":        "E",
  "operatorId":          "USER0001",
  "receiptDisp":         "APPROVED-THANK-YOU      ",
  "terminalDisp":        "APPROVED        "
}

JSON — Declined / Error

{
  "returnCode":        "9110",
  "errorDescription":  "AMOUNT TOO HIGH FOR TRANSACTION",
  "terminalDisp":      "DECLINED        ",
  "receiptDisp":       "DECLINED                ",
  "transactionNumber": "000111222445",
  "timeStamp":         "20240515-15000200"
}

Error / Return Codes

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 IAP Pre-Authorization was completed and the Interac debit charge was captured successfully.	Display the `authorizationNumber` on the customer receipt. Store the `transactionNumber` for potential Void operations.
05	Transaction declined	The IAP 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, 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.
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.
9031	"Null" value: POS terminal number	`MerchantTerminalNumber` is null or blank when a terminal transaction is being attempted.	Check your application. 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.
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 IAP 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 the original IAP Pre-Authorization was processed under your company number.
9063	Merchant number mismatch	The original transaction number exists but is not associated with your merchant number.	Check your application. Make sure the original IAP 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 IAP Pre-Authorization.	The original invoice number must be identical to the one used in the original IAP Pre-Authorization request.
9066	Invalid original transaction status	The original IAP Pre-Authorization's status does not allow a Completion — it was most likely declined or cancelled.	Make sure the original IAP Pre-Authorization was approved. If the problem persists, contact PayFacto customer service.
9067	Original authorization number mismatch	The `OriginalAuthorizationNumber` is not associated with the submitted original transaction number.	Make sure the `OriginalAuthorizationNumber` matches the value returned in the original IAP 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 IAP Pre-Authorization response.
9069	Original transaction is not a pre-authorization	The original transaction referenced is not an IAP Pre-Authorization. IAP Completions can only be applied to IAP Pre-Authorization transactions.	Make sure the original transaction number corresponds to an approved IAP Pre-Authorization, not a standard pre-authorization or other transaction type.
9108	Completion error	An error occurred while completing the IAP Pre-Authorization.	Retry the transaction. If the problem persists, contact PayFacto customer service.
9109	Pre-authorization already completed	A Completion has already been performed for this IAP Pre-Authorization. Only one Completion per IAP Pre-Authorization is allowed.	Check your application. Make sure the Completion has not already been performed for this IAP transaction.
9110	Amount too high for transaction	The completion `Amount` is higher than the `OriginalAmount` reserved in the IAP 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.