Reverse an eCheck Payment with the API

You can temporarily stop funding of an approved eCheck payment using the /txns endpoint to update the transaction’s batching status. This process is also called canceling, a form of reversal. Confirm that an eCheck transaction's status is Approved (1) to indicate the payment can be canceled. Once an eCheck transaction reaches Captured or Settled status, it must be refunded.

Important!

Canceled transactions can be restored within three to five days for eCheck payments before authorization expires. Restore canceled eCheck transactions within this timeframe to ensure valid authorization.

See Transaction Capture Timeframe for more details on the time limitations of transaction authorizations.

Check the Transaction Status

The cancel process described in the following sections requires the existing transaction to have an Approved (1) status. A transaction that has been captured or settled cannot be reversed.

To get the transaction 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 reverse:

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]=1

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": "Test",
                "middle": null,
                "last": "TEST",
                "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 1 determines that the relevant transaction cannot be refunded and must be reversed.

Cancel an Approved Transaction

When canceling a transaction, this means you're removing it from the settlement batch.

To restore a canceled transaction:

Create a PUT /txns/{id} request using the ID for the transaction to be canceled, including the request payload to update the batch parameter value to null:
BASH
```
PUT /txns/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}
```
JSON
```
{
  "batch": null
}
```

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

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": null,
                "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": "Test",
                "middle": null,
                "last": "TEST",
                "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": []
    }
}

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

Parameter	Note
`batch`	When a transaction response shows `“batch”: null`, it indicates it will not be included in a daily settlement batch until re-added using the Restore a Canceled Transaction process.

Result: Once successful, the approved transaction is no longer part of the batch, and the funds will not be taken from the cardholder.

Restore a Canceled Transaction

When restoring a transaction, you're re-adding a transaction that was removed from settlement batching (canceled).

Note: You have a limited time to restore the transaction before a new authorization is required. See Transaction Capture Time Frame for specific limits by card brand.

Create a GET /batches request to find the current open settlement batch ID:

BASH

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

Submit the request. A successful 200 OK response looks like the following example:
Note: Copy the id value in the response for the next step.

JSON

{
  "response": {
    "data": [
      {
        "id": "t1_bth_123abc4d567890efg1h2i34",
        "created": "2025-03-12T08:59:13Z",
        "modified": "2025-03-12T09:00:00Z",
        "creator": "t1_log_123abc4d567890efg1h2i34",
        "modifier": "t1_log_123abc4d567890efg1h2i34",
        "merchant": "t1_mer_123abc4d567890efg1h2i34",
        "date": null,
        "platform": "VANTIV",
        "status": "open",
        "ref": "1234567890",
        "clientRef": "1234567890",
        "inactive": false,
        "frozen": false,
        "processingDate": null,
        "processingId": null,
        "closeTime": "2025-03-12T17:00:00Z"
      }
    ],
    "details": {
      "requestId": 1,
      "totals": [],
      "page": {
        "current": 1,
        "last": 1,
        "hasMore": false
      }
    },
    "errors": []
  }
}

Create a PUT /txns/{id} request using the ID of the canceled transaction:
CODE
```
PUT /txns/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}
```
Update the batch value from null to the current open batch’s id you gathered in the previous step:
JSON
```
{
  "batch": "t1_bth_456def7g890123hij4k5l67"
}
```

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

JSON

{
     "response": {
         "data": [
            {
                "id": "t1_txn_123abc4d567890efg1h2i34", 
                ...
                "fortxn": null,
                ...
                "batch": "t1_bth_456def7g890123hij4k5l67",
                ...
                "type": 7,
                ...
            },
         ],
        "details": {
            "requestId": 1,
            "totals": [],
            "page": {
                "current": 1,
                "last": 1,
                "hasMore": false
            }
        },
        "errors": []
    }
}

Parameter	Notes
`id`	The ID of the original Transaction.
`fortxn`	The value is `null` because the original Transaction is canceled. This doesn't affect authorization, so a new Transaction isn't created.
`type`	The value shown will still be the same as the original sale: `7`: eCheck sale.
`batch`	A batch ID present indicates the transaction has been added to a settlement batch for capture and settlement later.

Result: The Approved transaction is re-added to the daily settlement batch, and the funds will be taken from the cardholder account upon capture, if authorization is still active.