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

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 assigned to the same merchant.

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

πŸ“„

Original Pre-Authorization Details

You must have stored the terminalInvoiceNumber and authorizationNumber from the original Pre-Authorization response. Both are required to route the completion to the correct terminal and match the pre-auth record. The terminal must be configured for the Semi-Integrated solution.

πŸ“±

Semi-Integrated Terminal Required

This endpoint is exclusively for the Semi-Integrated solution (InputType=N). The target terminal must be properly configured and reachable on PayFacto's network at the time the request is submitted.

2

   Request

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

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. This endpoint is Semi-Integrated only β€” always send CardNumber as 40 spaces, CardType as a blank space, and ExpirationDate as 4 spaces. The terminal supplies all card data.

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)Final completion amount in the smallest currency unit, zero-padded left. May differ from OriginalAmount if the authorization amount is being adjusted. Example: 00000010000 = $100.00
OriginalAmountNumeric(11)The amount of the original Pre-Authorization transaction, zero-padded left. Must match the amount that was authorized on the terminal. Example: 00000010000 = $100.00
InvoiceNumberAlphanumeric(12)Merchant-generated invoice number for the completion transaction. Example: INV000000010
OriginalTerminalInvoiceNumberNumeric(12)The terminal invoice number returned in the original Pre-Authorization response. Used to locate the pre-auth on any terminal assigned to the same merchant. Zero-padded left.
OriginalAuthorizationNumberAlphanumeric(8)The authorization number returned in the original Pre-Authorization response. Example: AUTH7766
InputTypeAlphanumeric(1)Must be N for Semi-Integrated terminal transactions.
CardTypeAlphanumeric(1)For InputType=N, send a blank space. The terminal resolves the card brand.
CardNumberAlphanumeric(40)For InputType=N, send 40 space characters. The terminal supplies card data.
ExpirationDateNumeric(4)For InputType=N, send 4 space characters. The terminal supplies expiry data.
MerchantTerminalNumberNumeric(5)Identifies the target terminal on PayFacto's network. Can be the terminal where the original Pre-Authorization was processed, or any other terminal assigned to the same merchant. 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 or system that initiated the completion. Example: USER0001
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
# Standalone Completion β€” POST /v1/standaloneCompletion
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345\
&MerchantNumber=53400000\
&CustomerNumber=CLIENT12\
&Amount=00000010000\
&OriginalAmount=00000010000\
&InvoiceNumber=INV000000010\
&OriginalTerminalInvoiceNumber=000000000042\
&OriginalAuthorizationNumber=AUTH7766  \
&InputType=N\
&CardType= \
&CardNumber=                                        \
&ExpirationDate=    \
&MerchantTerminalNumber=12345\
&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/standaloneCompletion" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "auth-api-key=YOUR_TEST_API_KEY&payload=$ENCODED"
4

  Response

ℹ️

The source specification does not designate any response fields as unconditionally mandatory for this endpoint. All fields listed below may be returned depending on the terminal configuration, card type, and transaction outcome. Always check returnCode first to determine whether the completion succeeded.

Response fields

FieldTypeDescription
returnCodeAlphanumeric(4)00=completion was applied successfully. Any other value indicates a failure. Refer to the Return Code reference for the complete list.
authorizationNumberAlphanumeric(8)Authorization code issued on successful completion. Mandatory to display on all customer receipts. Example: APPROV99
transactionNumberNumeric(12)Unique PayFacto gateway identifier for the completion transaction. Store this for auditing purposes. Example: 000111222777
amountNumeric(11)Echo of the completion amount.
accountTypeAlphanumeric(1)Account type used. C=Chequing, S=Savings.
bankTerminalNumberAlphanumeric(8)Terminal identifier at the banking acquirer.
batchNumberNumeric(4)Batch number in which the completion was processed.
cardNumberAlphanumeric(40)Masked card number supplied by the terminal.
cardTypeAlphanumeric(1)Card brand determined by the terminal. A=Amex, D=Debit, M=Mastercard, V=Visa, O=Discover, I=Diners, J=JCB, F=Datacandy.
companyNumberNumeric(5)Echo of the request CompanyNumber.
customerNumberAlphanumeric(8)Only returned when provided in the request. Echo of the request CustomerNumber.
expirationDateNumeric(4)Expiration date supplied by the terminal.
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 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. Example: APPROVED
terminalInvoiceNumberNumeric(12)Terminal-assigned invoice number for the completion transaction.
terminalNumberNumeric(5)Identifies the terminal in the PayFacto Network that processed the completion.
timeStampAlphanumeric(17)Date and time the completion was processed. Format: YYYYMMDD-HHMMSSCC. Example: 20240515-17000100
trxCodeAlphanumeric(2)Transaction type code. For a Standalone Completion this is 51.
trxDateNumeric(8)Completion date at the banking acquirer. Format: MMDDYYYY. May differ from timeStamp.
trxMethodAlphanumeric(3)Summarizes the transaction method. Example: D@1
trxTimeNumeric(6)Completion time at the banking acquirer. Format: HHMMSS. May differ from timeStamp.
trxTypeAlphanumeric(1)Card type used. C=Credit, D=Debit, F=Fidelity/Gift.
avsStatusAlphanumeric(1)Only returned when AVS data was present. 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 CVD data was present. 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 captured 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 completion is not approved. Human-readable description of the failure reason.
holderNameAlphanumeric(50)Only returned when the cardholder name was captured on a hosted payment page.
iopIssuerConfirmationNumberAlphanumeric(1–15)Only returned when the original payment was guaranteed via Interac Online. Must be displayed on the merchant's confirmation screen.
iopIssuerNameAlphanumeric(1–30)Only returned when the original payment was guaranteed via Interac Online. Issuer name in the customer's banking language.
secureIDAlphanumeric(35)Only returned for redirect / PayFacto Objects sessions.
surchargeAmountNumeric(11)Only returned when a surcharge was applied. Zero-padded left.
taxAmountNumeric(11)Only returned when a tax amount was present. Zero-padded left.
threeDSStatusAlphanumeric(1)Only returned when 3-D Secure data was present. 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. Token associated with the cardholder's card.
5

   Response β€” Code Example

JSON β€” 200 Completion Approved
{
  "returnCode":                  "00",
  "authorizationNumber":         "APPROV99",
  "transactionNumber":           "000111222777",
  "referenceNumber":             "0000000010",
  "amount":                      "00000010000",
  "accountType":                 "C",
  "cardNumber":                  "411111XXXXXX1111                       ",
  "cardType":                    "V",
  "trxType":                     "C",
  "trxCode":                     "51",
  "trxDate":                     "05152024",
  "trxTime":                     "170001",
  "trxMethod":                   "D@1",
  "timeStamp":                   "20240515-17000100",
  "batchNumber":                 "0001",
  "sequenceNumber":              "000011112225",
  "serverNumber":                "0001",
  "terminalNumber":              "12345",
  "terminalInvoiceNumber":       "000000000043",
  "bankTerminalNumber":          "00000001",
  "companyNumber":               "12345",
  "merchantNumber":              "53400000",
  "invoiceNumber":               "INV000000010",
  "expirationDate":              "1226",
  "languageCode":                "E",
  "operatorId":                  "USER0001",
  "receiptDisp":                 "APPROVED-THANK-YOU      ",
  "terminalDisp":                "APPROVED        "
}
JSON β€” Completion Failed
{
  "returnCode":        "9121",
  "errorDescription":  "PRE-AUTH NOT FOUND OR ALREADY COMPLETED",
  "terminalDisp":      "DECLINED        ",
  "receiptDisp":       "DECLINED                ",
  "transactionNumber": "000111222778",
  "timeStamp":         "20240515-17000200"
}
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
00Completion approvedThe Pre-Authorization was successfully completed and funds were captured.Display the authorizationNumber on the customer receipt. Store the transactionNumber for auditing and potential Void operations.
Non-00Completion failedThe completion could not be applied. Common causes: the pre-auth was not found, already completed, the OriginalTerminalInvoiceNumber or OriginalAuthorizationNumber did not match, or the terminal was unreachable.Check errorDescription and verify that OriginalTerminalInvoiceNumber and OriginalAuthorizationNumber are correct. Confirm the target terminal is online. Refer to the Return Code Index for code-specific guidance.
TimeoutUnknown stateNo response received within the expected window β€” it is unclear whether the completion was applied.Use the Recover endpoint with the InvoiceNumber to retrieve the result. Do not retry the completion until the state is confirmed to avoid double-capture.

    • Related Articles

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

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