Issue a Refund via API (Referrers)

How To - Use this guide provides step-by-step instructions on how to use the API to submit a refund or void transaction using the Payrix API as a Payrix Partner.

Cancel vs Refund vs Void

A refund, cancel or void transaction request can be submitted via the API using the /txns endpoint. You can see more information in the API Reference guide.

Cancel	Void	Refund
Removes the approved payment from the Merchant’s daily batch, but does not reverse the authorization.	Removes the approved payment from the Merchant’s daily batch AND reverses the authorization.	Refunds a prior Capture or Sale Transaction, total may be specified for a partial refund.
Transaction Type: `4`	Transaction Type: `4`	Transaction Type: `5` or `8`
Transaction Status Code: `1`	Transaction Status Code: `1`	Transaction Status Code: `3` or `4`
Must be done before batching.	Must be done before batching.	May be done anytime.

About Refund Timeframes

All transactions may be voided before they are batched. If the transaction has already been batched (frequency dependent on Referrer configuration), it will required a refund.

Note that there is no technical time limit on when a refund can be issued after a transaction has already been batched. The only limit is the refund policy of individual merchants.

For more info on Transaction Type see the expandable content below:

Transaction Types

Transaction Types Description

Transaction Type

Transaction Code

Note

Reverse Authorization

4

Credit Card Only.

Reverses a prior Auth or Sale Transaction and releases the credit hold.

Refund Transaction

5

Credit Card Only.

Refunds a prior Capture or Sale Transaction (total may be specified for a partial refund).

eCheck Refund Transaction

8

Echeck Only:

Refund Transaction for prior ECheck Sale Transaction.

Transaction Statuses

Transaction Statuses Description

Transaction Status	Status Code	Note
Pending	`0`
Approved	`1`	Payments can be voided or cancelled.
Failed	`2`
Captured	`3`	Payments can be refunded.
Settled	`4`	Payments can be refunded.
Returned	`5`	Payment has been successfully refunded.

Refund Payments via the API

Getting Started

Step 1: Check the desired refund payment’s transaction status - 3 for Captured or 4 for Settled.

Step 2: Enter required parameters to the request body

fortxn - The Payrix Transaction ID (TXN ID) of the original payment to refunded
type - 5 = Card Payments or 8 = eChecks (ACH).

When finished, send the request body in a POST request to the /txns endpoint.

See examples below of different payment refund use cases after setup:

Refund a Full Card Payment

Unless specified, refunds without amounts listed will be treated as a refund of the entire transaction amount.

Note: Full refunds exclude any funds that have been previously partially refunded).

CODE

{
    "fortxn": "t1_txn_5f6276c12269b0cc77adb44",
    "type": "5"
}

Refund a Partial Card Payment

You can specify a partial amount to be refunded by using the optionaltotal parameter.

Values are in cents USD.

Example: $1.00 = 100, $100 = 10000, etc.

CODE

{
    "fortxn": "t1_txn_5f6276c12269b0cc77adb44",
    "type": "5",
    "total": "100"
}

Refund an eCheck Payment

For eCheck refunds, you must submit the first name of the receiving/refunded customer under a first parameter.

CODE

{
    "fortxn": "t1_txn_5f6276c12269b0cc77adb44",
    "type": "8",
    "first": "John"
    "total": "100"
}

Void Payments via the API

Getting Started

Step 1: Check the desired payment’s transaction status is:1 for Captured

Step 2: Enter required parameters to the request body:

fortxn - The Payrix Transaction ID (TXN ID) of the original payment to voided.
type - 4 = Card Payments.

When finished, send the request body in a POST request to the /txns endpoint.

Void a Payment

CODE

{
    "fortxn": "t1_txn_5f1841b4b1200ea4d1af843",
    "type": "4"
}

Cancel an approved payment via the API

Getting Started

Step 1: Check the desired payment’s transaction status is:1 for Captured

Step 2: Enter required parameters to the request body:

batch - null

Step 3: Add the following path parameter:

{txn_ID} - The Payrix Transaction ID (TXN ID) of the original payment to cancelled.

When finished, send the request body in a PUT request to the /txns/{txn_ID} endpoint.

Cancel a Payment

CODE

{
    "batch": null
}