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

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 endpoint when the TUID from the original transaction is available and card data is not.

Version: v1.0   |   Last updated: 2026-05-15   |   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 Refund with TUID 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}.

πŸ“„

TUID from Original Transaction

You must have stored the TUID returned in the original transaction response. This 24-digit PayFacto switch identifier is the sole reference used to locate the original transaction and retrieve card details for the refund.

2

Request

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

All parameters are passed inside the Base64-encoded payload form field. Raw body format: auth-api-key=<key>&payload=<base64>. The TUID replaces CardNumber, CardType, and ExpirationDate β€” those fields are not required for this endpoint. The gateway resolves card data from the original transaction via the TUID.

Required fields

Field Type Description
CompanyNumber Numeric(5) Identifies the merchant on PayFacto's network. Provided by PayFacto. 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 refund. Example: CLIENT12
Amount Numeric(11) Refund amount in the smallest currency unit, zero-padded left. Example: 00000010000 = $100.00
InvoiceNumber Alphanumeric(12) Merchant-generated invoice number for this refund transaction. Example: INV000000030
InputType Alphanumeric(1) How the transaction is initiated. N=terminal/pinpad (Semi-Integrated), I=Internet/E-Commerce, M=MOTO, U=Unattended.
TUID Numeric(24) PayFacto switch (EPOS) unique transaction identifier of the original transaction. Obtained from the TUID field in the original transaction response. Used in place of card data to identify the transaction to refund. Example: 212400667337208477009882
MerchantTerminalNumber Numeric(5) Identifies the terminal on PayFacto's network. For E-Commerce, send 5 blank spaces. Example: 12345
LanguageCode Alphanumeric(1) Language for PayFacto responses. 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 refund. 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 
# Refund with TUID β€” POST /v1/refundWithTuid
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345\
&MerchantNumber=53400000\
&CustomerNumber=CLIENT12\
&Amount=00000010000\
&InvoiceNumber=INV000000030\
&InputType=I\
&TUID=212400667337208477009882\
&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/refundWithTuid" \
  -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 below may be returned depending on the original transaction's card type, input method, and refund outcome. Always check returnCode first to determine whether the refund succeeded.

Response fields

Field Type Description
returnCode Alphanumeric(4) 00=refund was applied successfully. Any other value indicates a failure. Refer to the Return Code reference for the complete list.
authorizationNumber Alphanumeric(8) Authorization code issued on successful refund. Mandatory to display on all customer receipts. Example: REFND902
transactionNumber Numeric(12) Unique PayFacto gateway identifier for this refund transaction. Store for auditing purposes. Example: 000111222999
amount Numeric(11) Echo of the refund amount. Zero-padded left.
accountType Alphanumeric(1) Account type of the original transaction. C=Chequing, S=Savings.
bankTerminalNumber Alphanumeric(8) Terminal identifier at the banking acquirer.
batchNumber Numeric(4) Batch number in which the refund was processed.
cardNumber Alphanumeric(40) Masked card number retrieved via the TUID from the original transaction.
cardType Alphanumeric(1) Card brand. A=Amex, D=Debit, M=Mastercard, V=Visa, O=Discover, I=Diners, J=JCB, F=Datacandy.
companyNumber Numeric(5) Echo of the request CompanyNumber.
customerNumber Alphanumeric(8) Only returned when provided in the request. Echo of the request CustomerNumber.
expirationDate Numeric(4) Expiration date retrieved via the TUID from the original transaction.
invoiceNumber Alphanumeric(12) Echo of the request InvoiceNumber for this refund transaction.
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 issued on successful refund.
sequenceNumber Alphanumeric(12) Sequence number generated by the banking acquirer.
serverNumber Alphanumeric(4) Identifies the PayFacto Network server that processed the refund.
terminalDisp Alphanumeric(24) Transaction message for the terminal or payment page. Example: APPROVED
terminalNumber Numeric(5) Identifies the terminal in the PayFacto Network used to process the refund.
timeStamp Alphanumeric(17) Date and time the refund was processed. Format: YYYYMMDD-HHMMSSCC. Example: 20240515-19000100
trxCode Alphanumeric(2) Transaction type code. For a standard Refund this is 03.
trxDate Numeric(8) Refund date at the banking acquirer. Format: MMDDYYYY. May differ from timeStamp.
trxMethod Alphanumeric(3) Summarizes the transaction method. Example: T@1
trxTime Numeric(6) Refund time at the banking acquirer. Format: HHMMSS. May differ from timeStamp.
trxType Alphanumeric(1) Card type used in the original transaction. C=Credit, D=Debit, F=Fidelity/Gift.
avsStatus Alphanumeric(1) Only returned when AVS data was present on the original transaction. M=Both match, N=Neither match, Z=Postal only, A=Address only, U=Unavailable.
cashbackAmount Numeric(11) Only returned when a cash-back amount was applied. Zero-padded left.
cvmResults Alphanumeric(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.
cvv2Cvc2Status Alphanumeric(1) Only returned when CVD data was present. M=Matches, N=Does not match, blank=Unknown.
demoMode Alphanumeric(4) Only returned when the terminal is in demo mode. Value will be true.
email Alphanumeric(250) Only returned when an email was captured on a hosted payment page.
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 refund is not approved. Human-readable description of the failure reason.
holderName Alphanumeric(50) Only returned when the cardholder name was captured on a hosted payment page.
iopIssuerConfirmationNumber Alphanumeric(1–15) Only returned when the original payment was guaranteed via Interac Online. Must be displayed on the merchant's confirmation screen.
iopIssuerName Alphanumeric(1–30) Only returned when the original payment was guaranteed via Interac Online. Issuer name in the customer's banking language.
secureID Alphanumeric(35) Only returned for redirect / PayFacto Objects sessions.
surchargeAmount Numeric(11) Only returned when a surcharge was applied. Zero-padded left.
taxAmount Numeric(11) Only returned when a tax amount was present. Zero-padded left.
terminalInvoiceNumber Numeric(12) Only returned for terminal transactions. Terminal-assigned invoice number.
threeDSStatus Alphanumeric(1) Only returned when 3-D Secure data was present on the original transaction. P=Passed, F=Failed, N=Not validated.
tipAmount Numeric(11) Only returned when a tip was present on the original transaction. Zero-padded left.
token Alphanumeric(35) Only returned when tokenization is enabled. Token associated with the cardholder's card.
5

Response β€” Code Example

JSON β€” 200 Refund Approved 
{
  "returnCode":          "00",
  "authorizationNumber": "REFND902",
  "transactionNumber":   "000111222999",
  "referenceNumber":     "0000000030",
  "amount":              "00000010000",
  "accountType":         "C",
  "cardNumber":          "411111XXXXXX1111                       ",
  "cardType":            "V",
  "trxType":             "C",
  "trxCode":             "03",
  "trxDate":             "05152024",
  "trxTime":             "190001",
  "trxMethod":           "T@1",
  "timeStamp":           "20240515-19000100",
  "batchNumber":         "0001",
  "sequenceNumber":      "000011112227",
  "serverNumber":        "0001",
  "terminalNumber":      "00001",
  "bankTerminalNumber":  "00000001",
  "companyNumber":       "12345",
  "merchantNumber":      "53400000",
  "invoiceNumber":       "INV000000030",
  "expirationDate":      "1226",
  "languageCode":        "E",
  "operatorId":          "USER0001",
  "receiptDisp":         "APPROVED-THANK-YOU      ",
  "terminalDisp":        "APPROVED        "
}
JSON β€” Refund Failed 
{
  "returnCode":        "9121",
  "errorDescription":  "TUID NOT FOUND",
  "terminalDisp":      "DECLINED        ",
  "receiptDisp":       "DECLINED                ",
  "transactionNumber": "000111223000",
  "timeStamp":         "20240515-19000200"
}
6

Error / Return Codes

The following codes are specific to this endpoint. For the complete catalogue see the Return Code Index.

Return Code Meaning When it occurs Recommended Action
00 Refund approved The refund was successfully processed using card data retrieved via the TUID. Display the authorizationNumber on the customer receipt. Store the transactionNumber for auditing.
Non-00 Refund failed The refund could not be processed. Common causes: the TUID was not found on the PayFacto switch, the TUID does not correspond to a refundable transaction, or the transaction belongs to a different merchant. Check errorDescription and verify the TUID was copied exactly from the original transaction response (24 digits, no spaces). Refer to the Return Code Index for code-specific guidance.
Timeout Unknown state No response received within the expected window β€” it is unclear whether the refund was applied. Use the Recover endpoint with the InvoiceNumber of the refund to retrieve the result before retrying.

    • Related Articles

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