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

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 captured on a settlement file.

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 Void 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 Transaction Details

You must have stored the transactionNumber and invoiceNumber from the original transaction response. Both are required to identify the transaction to void. The batch containing the original transaction must not yet have been settled.

2

   Request

ℹ️

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. Note that CardNumber, CardType, ExpirationDate, Amount, and CurrencyCode are not required for a Void β€” the gateway resolves these from the original transaction.

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
OriginalInvoiceNumberAlphanumeric(12)The invoice number of the transaction being voided. Must match the InvoiceNumber returned in the original transaction response. Example: INV000000001
OriginalTransactionNumberNumeric(12)The unique PayFacto transaction identifier of the transaction being voided. Obtained from the transactionNumber field in the original transaction response. Example: 000111222333
InputTypeAlphanumeric(1)How the transaction is initiated. N=terminal/pinpad (Semi-Integrated), I=Internet/E-Commerce, M=MOTO, U=Unattended.
LanguageCodeAlphanumeric(1)Language for PayFacto responses. F=French, E=English.
OperatorIDAlphanumeric(8)Identifies the cashier, agent, or system that initiated the void. 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
# Void β€” POST /v1/void
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345\
&MerchantNumber=53400000\
&CustomerNumber=CLIENT12\
&OriginalInvoiceNumber=INV000000001\
&OriginalTransactionNumber=000111222333\
&InputType=I\
&LanguageCode=E\
&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/void" \
  -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=void was applied successfully. Any other value indicates a failure. Refer to the Return Code reference for the complete list.
authorizationNumberAlphanumeric(8)Authorization code confirming the void. Example: VOID9901
transactionNumberNumeric(12)Unique PayFacto gateway identifier for the void transaction itself. Example: 000111222555
amountNumeric(11)Echo of the original transaction amount that was voided. Zero-padded left.
accountTypeAlphanumeric(1)Account type of the original transaction. C=Chequing, S=Savings.
bankTerminalNumberAlphanumeric(8)Terminal identifier at the banking acquirer.
batchNumberNumeric(4)Batch number in which the void was processed.
cardNumberAlphanumeric(40)Masked card number from the original transaction.
cardTypeAlphanumeric(1)Card brand. 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)Expiration date from the original transaction.
invoiceNumberAlphanumeric(12)Invoice number associated with the void transaction.
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 for the void transaction.
sequenceNumberAlphanumeric(12)Sequence number generated by the banking acquirer.
serverNumberAlphanumeric(4)Identifies the PayFacto Network server that processed the void.
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 void.
timeStampAlphanumeric(17)Date and time the void was processed. Format: YYYYMMDD-HHMMSSCC. Example: 20240515-16000100
trxCodeAlphanumeric(2)Transaction type code for the void. 04=Void Purchase, 05=Void Refund, 06=Void Completion.
trxDateNumeric(8)Void date at the banking acquirer. Format: MMDDYYYY. May differ from timeStamp.
trxMethodAlphanumeric(3)Summarizes the transaction method. Example: T@1
trxTimeNumeric(6)Void time at the banking acquirer. Format: HHMMSS. May differ from timeStamp.
trxTypeAlphanumeric(1)Card type used in the original transaction. 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 the original transaction included AVS data. 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 on the original transaction. 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 the original transaction included CVD data. 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 void 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.
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 on the original transaction. Zero-padded left.
taxAmountNumeric(11)Only returned when a tax amount was present on the original transaction. Zero-padded left.
terminalInvoiceNumberNumeric(12)Only returned for terminal transactions. Terminal-assigned invoice number.
threeDSStatusAlphanumeric(1)Only returned when 3-D Secure data was present on the original transaction. P=Passed, F=Failed, N=Not validated.
tipAmountNumeric(11)Only returned when a tip was present on the original transaction. Zero-padded left.
tokenAlphanumeric(35)Only returned when tokenization is enabled. Token associated with the cardholder's card.
5

   Response β€” Code Example

JSON β€” 200 Void Approved
{
  "returnCode":          "00",
  "authorizationNumber": "VOID9901",
  "transactionNumber":   "000111222555",
  "referenceNumber":     "0000000003",
  "amount":              "00000010000",
  "accountType":         "C",
  "cardNumber":          "411111XXXXXX1111                       ",
  "cardType":            "V",
  "trxType":             "C",
  "trxCode":             "04",
  "trxDate":             "05152024",
  "trxTime":             "160001",
  "trxMethod":           "T@1",
  "timeStamp":           "20240515-16000100",
  "batchNumber":         "0001",
  "sequenceNumber":      "000011112224",
  "serverNumber":        "0001",
  "terminalNumber":      "00001",
  "bankTerminalNumber":  "00000001",
  "companyNumber":       "12345",
  "merchantNumber":      "53400000",
  "invoiceNumber":       "INV000000001",
  "expirationDate":      "1226",
  "languageCode":        "E",
  "operatorId":          "USER0001",
  "receiptDisp":         "APPROVED-THANK-YOU      ",
  "terminalDisp":        "APPROVED        "
}
JSON β€” Void Failed
{
  "returnCode":        "9121",
  "errorDescription":  "TRANSACTION NOT FOUND OR ALREADY SETTLED",
  "terminalDisp":      "DECLINED        ",
  "receiptDisp":       "DECLINED                ",
  "transactionNumber": "000111222556",
  "timeStamp":         "20240515-16000200"
}
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
00Void approvedThe original transaction was successfully cancelled before settlement.Notify the customer that the transaction has been cancelled. No further action is required β€” the original transaction will not appear on the settlement file.
Non-00Void failedThe void could not be applied. Common causes: the batch has already been settled, or the OriginalTransactionNumber / OriginalInvoiceNumber could not be matched.Check errorDescription. If the batch has already settled, use the Refund endpoint instead. Refer to the Return Code Index for code-specific guidance.
TimeoutUnknown stateNo response received within the expected window β€” it is unclear whether the void was applied.Use the Recover endpoint with the original InvoiceNumber to retrieve the result. Do not retry the void until the state is confirmed.

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