Refund or Void a Transaction in the API
- Yehudah Rodman (Unlicensed)
- Paul Clifton
Use the Payrix API to submit a refund or void transaction.
A refund or void can be submitted via the API using the /txns endpoint. You can look up additional information about the /txns endpoint in the API Reference.
This page provides step-by-step details about using the API to submit a refund or void transaction:
Submitting a Refund or Void a Payment via the API
The process of submitting a card payment (sale) refund, an eCheck refund, or voiding an approved transaction is virtually the same. The only difference between these three options is the type value included in the request.
A refund can be issued when the transaction status is “3” (captured) or “4” (settled), but payments with these statuses cannot be voided or cancelled. A payment can only be voided or cancelled if the transaction status is “1” (approved).
API transaction statuses:
How to Refund a Card Payment via the API
A partial or full refund/void is submitted in the API by sending a POST request to the /txns endpoint and including the Transaction ID of the payment that is being refunded/voided. By default, if no amount is set when submitting a refund/void via the API it will be a full refund for the entire amount of the original transaction (excluding any funds that have been previously partially refunded).
{
"fortxn": "t1_txn_5f6276c12269b0cc77adb44",
"type": "5"
}You can enter a partial amount to be refunded (amount values are in cents USD - in the code snippet below a $1.00 refund is shown).
{
"fortxn": "t1_txn_5f6276c12269b0cc77adb44",
"type": "5",
"total": "100"
}At a minimum, the only fields required to submit a refund/void are:
fortxn - enter the Payrix Transaction ID (TXN ID) of the original payment you wish to refund/void.
type - In the case of a card payment refund this field should be set with the value “5”.
How to Refund an eCheck Payment via the API
For eCheck refunds, the type field should be set to “8”. Additionally, you must submit the customer’s (whom you are sending the eCheck refund to) first name.
{
"fortxn": "t1_txn_5f6276c12269b0cc77adb44",
"type": "5",
"first": "John"
"total": "100"
}
How to Void a Payment via the API
To void an approved (but not captured/settled) payment, the type should be set to “4”.
How to cancel an approved payment via the API
As covered elsewhere, the fundamental difference between voiding and canceling a payment is that canceling a transaction simply removes the approved payment from the Merchant’s daily batch, but does not actually reverse the authorization (as voiding does).
Therefore, in API terms, voiding a payment more closely resembles a standard refund, but canceling a transaction fundamentally differs. To cancel an approved payment in the API, send a PUT request to the /txns endpoint and include the relevant Payrix Transaction ID (TXN ID) in the request string (i.e. PUT/txns/txn_ID). In the code body, simply send a request to nullify the batch associated with the approved payment.