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

Returns funds to a cardholder after a settled transaction, using a previously stored card token instead of raw card data. Optionally links back to the original purchase via its invoice and transaction numbers.

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 Token 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}.

🪙

Card Token

A Token is a security token linked to a client's credit card, used in place of raw card data. Tokens are returned by the PayFacto platform when tokenization is enabled on a prior transaction. The token must be active and have a valid card on file.

↩️

Refund vs. Void

Use this endpoint to return funds on a transaction that has already been settled (batch closed). To cancel a transaction that has been approved but not yet settled, use Void (/v1/void) instead. You may only refund original purchase transactions — refunding a refund or a cancelled transaction is not permitted.

Request

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

ℹ️

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 MerchantTerminalNumber as the assigned terminal number; for E-Commerce, send 5 blank spaces.

Required fields

Field	Type	Description
CompanyNumber	Numeric(5)	Identifies the merchant on PayFacto's network. Provided by PayFacto during onboarding. Must match the company number of the original transaction. Example: `12345`
MerchantNumber	Numeric(8)	Identifies the merchant to PayFacto's network. Provided by the integration team. Must match the merchant number of the original transaction. Example: `53400000`
CustomerNumber	Alphanumeric(8)	Merchant-assigned customer identifier. Associates a client record with the transaction. Example: `CLIENT12`
Amount	Numeric(11)	Amount to refund including the decimal portion, left (0) padded. May be a partial or full refund of the original transaction amount. Example: `00000010000` = $100.00
InvoiceNumber	Alphanumeric(12)	Merchant-generated invoice number for this refund transaction. May be unique or reused per merchant needs. Example: `REF000000001`
InputType	Alphanumeric(1)	How the transaction is initiated. `N` = terminal/pinpad (Semi-Integrated), `I` = Internet/E-Commerce, `M` = MOTO, `U` = Unattended.
Token	Alphanumeric(35)	Security token linked to the client's credit card, used in place of raw card data. Returned by PayFacto when tokenization is enabled on a prior transaction. Example: `2079wo00wbwp916d3l2mutd8t7965o99mp9`
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`

Optional fields

Field	Type	Description
OriginalInvoiceNumber	Alphanumeric(12)	The merchant's invoice number from the original purchase transaction, as generated in the initial request and returned in its response. Used to link this refund to its original transaction. Must match the invoice number recorded on the original transaction. Example: `INV000000001`
OriginalTransactionNumber	Numeric(12)	The transaction number obtained in the response of the original purchase transaction. Used to link this refund to its original transaction. Example: `000111222333`
taxAmount	Numeric(11)	Total tax amount included in `Amount`, left (0) padded. Example: `00000000374` = $3.74
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. Replace credentials and base URL before going live.

cURL

# Refund with Token — POST /v1/refundWithToken
# Step 1: Build the cleartext payload
PAYLOAD="CompanyNumber=12345&MerchantNumber=53400000&CustomerNumber=CLIENT12&Amount=00000010000&InvoiceNumber=REF000000001&InputType=I&Token=2079wo00wbwp916d3l2mutd8t7965o99mp9&MerchantTerminalNumber=     &LanguageCode=E&CurrencyCode=CAD&OperatorID=USER0001&OriginalInvoiceNumber=INV000000001&OriginalTransactionNumber=000111222333"

# 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/refundWithToken" \
  -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 refund. Mandatory to display on all customer receipts. Example: `APPROV99`
transactionNumber	Numeric(12)	Unique PayFacto gateway transaction identifier for this refund. Example: `000111222444`
amount	Numeric(11)	Echo of the requested refund 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)	Masked card number resolved from the token.
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)	Expiration date of the card resolved from the token, 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 refund.
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 Refund with Token this is always `53`.
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.
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.
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.
token	Alphanumeric(35)	Only returned when tokenization is enabled. Echo or updated token linked to the cardholder.

Response — Code Example

JSON — 200 Approved

{
  "returnCode":          "00",
  "authorizationNumber": "APPROV99",
  "transactionNumber":   "000111222444",
  "referenceNumber":     "0000000002",
  "amount":              "00000010000",
  "accountType":         "C",
  "cardNumber":          "411111XXXXXX1111                       ",
  "cardType":            "V",
  "trxType":             "C",
  "trxCode":             "53",
  "trxDate":             "05152024",
  "trxTime":             "153001",
  "trxMethod":           "T@1",
  "timeStamp":           "20240515-15300100",
  "batchNumber":         "0001",
  "sequenceNumber":      "000011112223",
  "serverNumber":        "0001",
  "terminalNumber":      "00001",
  "bankTerminalNumber":  "00000001",
  "companyNumber":       "12345",
  "merchantNumber":      "53400000",
  "invoiceNumber":       "REF000000001",
  "expirationDate":      "1226",
  "languageCode":        "E",
  "operatorId":          "USER0001",
  "receiptDisp":         "APPROVED-THANK-YOU      ",
  "terminalDisp":        "APPROVED        "
}

JSON — Declined / Error

{
  "returnCode":        "9065",
  "errorDescription":  "ORIGINAL TRANSACTION IS NOT A PURCHASE",
  "terminalDisp":      "DECLINED        ",
  "receiptDisp":       "DECLINED                ",
  "transactionNumber": "000111222445",
  "timeStamp":         "20240515-15300200"
}

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 refund was authorized successfully and funds will be returned to the cardholder.	Display the `authorizationNumber` on the customer receipt.
05	Transaction declined	The refund 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, or 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.
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.	Check your application. Make sure you are sending the invoice number exactly as it appeared on the original transaction.
9062	Company number mismatch	The original transaction number exists but is not associated with your company number. You may only refund transactions processed under your own company.	Check your application. Make sure you have the correct original transaction number and company number.
9063	Merchant number mismatch	The original transaction number exists but is not associated with your merchant number. You may only refund transactions processed under your own merchant number.	Check your application. Make sure you have the correct original transaction number and merchant number.
9064	Original invoice number mismatch	The `OriginalInvoiceNumber` sent does not match the invoice number recorded on the original transaction.	The original invoice number must be identical to the one used in the original transaction.
9065	Original transaction is not a purchase	The original transaction referenced is not a purchase. Refunds may only be applied to original purchase transactions.	Make sure you have the correct original transaction number and that the transaction is a purchase.
9066	Invalid original transaction status	The original transaction's status does not allow a refund — it was most likely declined or cancelled.	Make sure the original transaction was approved and settled. If the problem persists, contact PayFacto customer service.
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 purchase response.
9126	Invalid token	The received token does not follow the length described in the documentation or is valid but not associated with the merchant or client.	Verify your data. The field must match the specification. If it does, contact PayFacto customer service.
9127	Inactive client	The received token matches a client who has been removed from the recurrence system.	Verify your data. Reactivate the client or use a different token.
9133	Token with expired credit card	The received token matches a customer whose credit card on file is expired.	Obtain the customer's updated card information, update their profile, and re-tokenize before processing the refund.
9134	Token with no credit card	The received token corresponds to a customer who has no credit card in their profile.	Obtain the customer's credit card information, update their profile, and obtain a new token before processing the refund.
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.