Refund an eCheck Payment with the API

You can issue refunds for captured or settled eCheck transactions using the /txns endpoint. Refunds are set by using a specific type parameter value in the request.

After confirming an eCheck transaction's status is Captured (3) or Settled (4), indicating a payment cannot be reversed, you can process a full or partial refund transaction.

Check the Transaction Status

The refund process described in the following sections requires the existing transaction to have a Captured (3) or Settled (4) status. A transaction that has not been captured or settled cannot be refunded.

Follow these steps to get the status before performing a reversal:

Create a GET /txns/{id} request and set the {id} path parameter to the ID of the transaction you’d like to refund:

CODE

GET /txns/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}

Use GET /txns with search parameters if you need to locate the transaction:

BASH

GET /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}
SEARCH: type[equals]=7&status[equals]=3,4

Submit the request. A successful 200 OK response looks similar to the following example, where the status field contains the Transaction's status:

JSON

{
     "response": {
         "data": [
            {
                "id": "t1_txn_123abc4d567890efg1h2i34",
                "created": "2025-04-25 17:07:12.7314",
                "modified": "2025-04-25 17:07:14.9495",
                "creator": "t1_log_123abc4d567890efg1h2i34",
                "modifier": "000000000000001",
                "ipCreated": "0.0.0.0",
                "ipModified": "0.0.0.0",
                "merchant": "t1_mer_123abc4d567890efg1h2i34",
                "token": "b7b0214116eaaa70b8d64850b6c57859",
                "payment": "t1_pmt_123abc4d567890efg1h2i34",
                "fortxn": null,
                "fromtxn": null,
                "batch": t1_bth_123abc4d567890efg1h2i34,
                "subscription": null,
                "type": 7,
                "expiration": null,
                "currency": "USD",
                "platform": "VANTIV",
                "authDate": null,
                "authCode": null,
                "captured": null,
                "settled": null,
                "settledCurrency": null,
                "settledTotal": null,
                "allowPartial": 0,
                "order": null,
                "description": null,
                "descriptor": "Test",
                "terminal": null,
                "terminalCapability": null,
                "entryMode": null,
                "origin": 8,
                "tax": null,
                "total": 0,
                "cashback": null,
                "authorization": null,
                "approved": 0,
                "cvv": 0,
                "swiped": 0,
                "emv": 0,
                "signature": 0,
                "unattended": null,
                "clientIp": "0.0.0.0",
                "first": "Bobby",
                "middle": null,
                "last": "Hill",
                "company": null,
                "email": null,
                "address1": "123 Main Street",
                "address2": Suite 456,
                "city": "New York",
                "state": "NY",
                "zip": "12345",
                "country": "USA",
                "phone": null,
                "mid": "01234567",
                "status": 1,
                "refunded": 0,
                "reserved": 0,
                "misused": null,
                "checkStage": "capture",
                "imported": 0,
                "inactive": 0,
                "frozen": 0,
                "discount": 0,
                "shipping": 0,
                "duty": 0,
                "pin": 0,
                "traceNumber": null,
                "cvvStatus": null,
                "unauthReason": null,
                "fee": null,
                "fundingCurrency": "USD",
                "authentication": null,
                "authenticationId": null,
                "cofType": null,
                "copyReason": null,
                "originalApproved": 0,
                "currencyConversion": null,
                "serviceCode": null,
                "authTokenCustomer": null,
                "debtRepayment": 0,
                "statement": null,
                "convenienceFee": 0,
                "surcharge": null,
                "channel": null,
                "funded": null,
                "fundingEnabled": 1,
                "requestSequence": 0,
                "processedSequence": 0,
                "mobile": null,
                "pinEntryCapability": null,
                "fbo": "WORLDPAY_FBO1",
                "returned": null,
                "txnsession": null,
                "networkTokenIndicator": 0,
                "softPosDeviceTypeIndicator": null,
                "softPosId": null,
                "tip": null
            },
         ],
        "details": {
            "requestId": 1,
            "totals": [],
            "page": {
                "current": 1,
                "last": 1,
                "hasMore": false
            }
        },
        "errors": []
    }
}

Check the status field against the following table to determine if a reversal action can be performed:

Value	Status	Notes
`0`	Pending	None
`1`	Approved	The payment can be reversed.
`2`	Failed	The payment failed. A reversal or refund cannot be issued.
`3`	Captured	Payment must be refunded.
`4`	Settled	Payment must be refunded.
`5`	Returned	The payment was reversed.

Result: Confirming a status value of 3 or 4 determines that the relevant transaction cannot be reversed and must be refunded.

Refund a Captured or Settled Transaction

After confirming that the transaction status is Captured or Settled, you can initiate a refund transaction.

To create an eCheck refund transaction:

Create a POST /txns request.
BASH
```
POST /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}
REQUEST-TOKEN: {yourRequestToken}
```
Important: Include the REQUEST-TOKEN header with a unique value between 1 and 100 characters to apply idempotency to the API request and ensure the refund is issued only once.
For more information on how to use Request Tokens, see Ensure Idempotency with Request Tokens.

Build the request payload with the following required fields:

JSON

{
	"merchant": "t1_mer_123abc4d567890efg1h2i34",
	"fortxn": "t1_txn_123abc4d567890efg1h2i34",
	"first": "Bobby", 
	"type": 8, 
	"total": 1000
}

Parameter	Description	Notes
`merchant`	The ID of the Merchant that is processing the transaction.	This should be the same Merchant ID from the original payment transaction.
`fortxn`	The ID of the original transaction being refunded.	None
`first`	The first name of the account holder submitted with the original payment.	None
`type`	The type of transaction.	Required: `8`: eCheck Refund Transaction
`total`	The dollar amount of the transaction.	(Optional) The total amount to refund. Note: This amount can be less than the original transaction total. If omitted, it defaults to a full refund of the original transaction (excluding any previously refunded amounts).

Submit the request. A successful 200 OK response looks like the following example:

JSON

{
    "response": {
        "data": [
            {
                "id": "t1_txn_456def7g890123hij4k5l67",
                "created": "2025-04-25 17:46:32.0661",
                "modified": "2025-04-25 17:46:33.9409",
                "creator": "t1_log_123abc4d567890efg1h2i34",
                "modifier": "t1_log_123abc4d567890efg1h2i34",
                "ipCreated": "54.86.50.139",
                "ipModified": "54.86.50.139",
                "merchant": "t1_mer_123abc4d567890efg1h2i34",
                "token": null,
                "payment": "t1_pmt_123abc4d567890efg1h2i34",
                "fortxn": "t1_txn_123abc4d567890efg1h2i34",
                "fromtxn": null,
                "batch": null,
                "subscription": null,
                "type": "8",
                "expiration": null,
                "currency": "USD",
                "platform": "VANTIV",
                "authDate": null,
                "authCode": null,
                "captured": "2025-04-25 17:46:33",
                "settled": null,
                "settledCurrency": null,
                "settledTotal": null,
                "allowPartial": 0,
                "order": null,
                "description": null,
                "descriptor": "Test",
                "terminal": null,
                "terminalCapability": null,
                "entryMode": null,
                "origin": 2,
                "tax": 0,
                "total": 100,
                "cashback": null,
                "authorization": null,
                "approved": 100,
                "cvv": 0,
                "swiped": 0,
                "emv": 0,
                "signature": 0,
                "unattended": null,
                "clientIp": null,
                "first": "AUTOMATED",
                "middle": null,
                "last": null,
                "company": null,
                "email": null,
                "address1": null,
                "address2": null,
                "city": null,
                "state": null,
                "zip": null,
                "country": null,
                "phone": null,
                "mid": "02766850",
                "status": "3",
                "refunded": 0,
                "reserved": 0,
                "misused": null,
                "checkStage": "refund",
                "imported": 0,
                "inactive": 0,
                "frozen": 0,
                "discount": null,
                "shipping": null,
                "duty": null,
                "pin": 0,
                "traceNumber": null,
                "cvvStatus": null,
                "unauthReason": null,
                "fee": null,
                "fundingCurrency": "USD",
                "authentication": null,
                "authenticationId": null,
                "cofType": null,
                "copyReason": null,
                "originalApproved": 100,
                "currencyConversion": null,
                "serviceCode": null,
                "authTokenCustomer": null,
                "debtRepayment": "0",
                "statement": null,
                "convenienceFee": 0,
                "surcharge": null,
                "channel": null,
                "funded": null,
                "fundingEnabled": "1",
                "requestSequence": 1,
                "processedSequence": 0,
                "mobile": null,
                "pinEntryCapability": null,
                "fbo": "WORLDPAY_FBO1",
                "returned": null,
                "txnsession": null,
                "networkTokenIndicator": null,
                "softPosDeviceTypeIndicator": null,
                "softPosId": null,
                "tip": null
            }
        ],
        "details": {
            "requestId": 1
        },
        "errors": []
    }
}

Notable Response Parameters
The following table provides a list of key parameters that help indicate core details about the refund transaction:

Parameter	Notes
`id`	The ID of the new eCheck refund Transaction.
`fortxn`	The ID of the original transaction that was refunded.
`status`	Whether the refund was approved or failed: `1`: Approved `2`: Failed
`type`	Confirm the eCheck transaction type: `8`: eCheck Refund
`total`	The total amount that was refunded in the transaction.

Result: A new idempotent refund transaction is processed to issue funds back to the customer for the original transaction. These funds are re-deposited into the account holder’s account within four to eight business days, depending on the policies of the account holder’s bank.