Skip to main content
Skip table of contents

Reverse a Credit Card Payment with the API

You can reverse an approved credit card payment using the /txns endpoint. Confirm that a credit card transaction's status is Approved (1) to indicate the payment can be reversed. You can use two methods to reverse a payment:

  1. Cancel: Temporarily delay the capture of funds from the customer.

  2. Void: Issue a new reverse transaction to permanently remove payment authorization and pending charges.

Important!

Canceled transactions can be restored within the timeframe set by each card brand for credit card payments before authorization expires. Restore canceled credit card 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 and void processes described in subsequent sections require 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:

  1. 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]=1&status[equals]=1

  2. 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-03-12 11:01:50.2123",
                "modified": "2025-03-12 11:01:52.2628",
                "creator": "t1_log_123abc4d567890efg1h2i34",
                "modifier": "t1_log_123abc4d567890efg1h2i34",
                "ipCreated": "3.239.14.143",
                "ipModified": "3.239.14.143",
                "merchant": "t1_mer_123abc4d567890efg1h2i34",
                "token": "null",
                "payment": "g123a456bc56789",
                "fortxn": null,
                "fromtxn": null,
                "batch": "t1_bth_123abc4d567890efg1h2i34",
                "subscription": null,
                "type": 1,
                "expiration": "1229",
                "currency": "USD",
                "platform": "VANTIV",
                "authDate": null,
                "authCode": null,
                "captured": null,
                "settled": null,
                "settledCurrency": null,
                "settledTotal": null,
                "allowPartial": 0,
                "order": null,
                "description": null,
                "descriptor": "Ray Adrian",
                "terminal": null,
                "terminalCapability": null,
                "entryMode": null,
                "origin": 2,
                "tax": null,
                "total": 1000,
                "cashback": null,
                "authorization": "12345",
                "approved": 100,
                "cvv": 123,
                "swiped": 0,
                "emv": 0,
                "signature": 0,
                "unattended": null,
                "clientIp": null,
                "first": null,
                "middle": null,
                "last": null,
                "company": null,
                "email": null,
                "address1": null,
                "address2": null,
                "city": null,
                "state": null,
                "zip": "12345",
                "country": null,
                "phone": null,
                "mid": "12345678",
                "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": "single",
                "copyReason": null,
                "originalApproved": 1000,
                "currencyConversion": null,
                "serviceCode": null,
                "authTokenCustomer": null,
                "debtRepayment": 0,
                "statement": null,
                "convenienceFee": 0,
                "surcharge": null,
                "channel": null,
                "funded": null,
                "fundingEnabled": 1,
                "requestSequence": 1,
                "processedSequence": 1,
                "mobile": null,
                "pinEntryCapability": null,
                "fbo": "WORLDPAY_FBO1",
                "returned": null,
                "txnsession": null,
                "networkTokenIndicator": 0,
                "softPosDeviceTypeIndicator": null,
                "softPosId": null,
                "tip": null,
                "fundingHoldReleaseDate": null
            },
         ],
        "details": {
            "requestId": 1,
            "totals": [],
            "page": {
                "current": 1,
                "last": 1,
                "hasMore": false
            }
        },
        "errors": []
    }
}

  3. 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

After confirming the transaction status is Approved, you can reverse it by canceling, which removes it from the settlement batch.

To cancel a credit card transaction:

  1. Create a PUT /txns/{id} request using the ID for the transaction to be canceled, and build 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
}

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

    JSON 
    {
     "response": {
         "data": [
            {
                "id": "t1_txn_456def7g890123hij4k5l67", 
                "created": "2025-03-12 12:14:24.5215",
                "modified": "2025-03-12 12:14:25.2131",
                "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": "g157968b6df1534",
                "fortxn": "t1_txn_123abc4d567890efg1h2i34",
                "fromtxn": null,
                "batch": null,
                "subscription": null,
                "type": 5,
                "expiration": "1240",
                "currency": "USD",
                "platform": "VANTIV",
                "authDate": null,
                "authCode": null,
                "captured": "2025-03-12 12:14:25",
                "settled": null,
                "settledCurrency": null,
                "settledTotal": null,
                "allowPartial": 0,
                "order": "",
                "description": null,
                "descriptor": "Sandbox Test",
                "terminal": null,
                "terminalCapability": null,
                "entryMode": null,
                "origin": 2,
                "tax": null,
                "total": 105,
                "cashback": null,
                "authorization": null,
                "approved": 105,
                "cvv": 0,
                "swiped": 0,
                "emv": 0,
                "signature": 0,
                "unattended": null,
                "clientIp": null,
                "first": null,
                "middle": null,
                "last": null,
                "company": null,
                "email": null,
                "address1": null,
                "address2": null,
                "city": null,
                "state": null,
                "zip": null,
                "country": null,
                "phone": null,
                "mid": "04901629",
                "status": "3",
                "refunded": 0,
                "reserved": 0,
                "misused": null,
                "checkStage": "approved",
                "imported": 0,
                "inactive": 0,
                "frozen": 0,
                "discount": null,
                "shipping": null,
                "duty": null,
                "pin": 0,
                "traceNumber": null,
                "cvvStatus": "notProvided",
                "unauthReason": "customerCancelled",
                "fee": null,
                "fundingCurrency": "USD",
                "authentication": null,
                "authenticationId": null,
                "cofType": null,
                "copyReason": null,
                "originalApproved": 105,
                "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,
                "fundingHoldReleaseDate": 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 until the transaction is restored and captured in an active open settlement batch.

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.

To restore a canceled transaction:

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

  2. 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": []
  }
}

  3. 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_123abc4d567890efg1h2i34"
}

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

    JSON 
    {
     "response": {
         "data": [
            {
                "id": "t1_txn_456def7g890123hij4k5l67", 
                ...
                "fortxn": null,
                ...
                "batch": t1_bth_456def7g890123hij4k5l67,
                ...
                "type": 1,
                ...
            },
         ],
        "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

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:

  • 1: Credit card 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.

Void an Approved Transaction

After confirming the transaction status is Approved, you can reverse it by voiding, which creates a separate reverse transaction as a permanent cancellation of the payment authorization.

To void a credit card transaction:

  1. Create a POST /txns request:

    CODE 
    POST /txns
Content-Type: application/json
Host: api-test.payrix.com
APIKEY: {yourAPIKey}
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, ensuring the void is issued only once.
    For more information on how to use Request Tokens, see Ensure Idempotency with Request Tokens.

  2. Build the request payload with the required parameters:

    JSON 
    {
	"merchant": "t1_mer_123abc4d567890efg1h2i34",
	"fortxn": "t1_txn_123abc4d567890efg1h2i34",
	"type": 4, 
	"origin": 2,
	"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 voided.

None

type

The type of transaction.

Required:

  • 4: Credit Card Reverse Transaction.

origin

The method being used to create this transaction.

Required:

  • 1: Credit card terminal.

  • 2: E-commerce System

total

The dollar amount of the transaction.

Enter the amount to be voided.

The entire total amount from the original transaction, or a lesser amount can be entered.

  1. Submit the request. A successful 200 OK response look the following example:

    JSON 
    {
  "response": {
    "data": [
      {
        "id": "t1_txn_456def7g890123hij4k5l67",
        "created": "2025-03-12 10:48:31.7799",
        "modified": "2025-03-12 10:48:32.2075",
        "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": "g123a456bc56789",
        "fortxn": "t1_txn_123abc4d567890efg1h2i34",
        "fromtxn": null,
        "batch": null,
        "subscription": null,
        "type": 4,
        "expiration": "0123",
        "currency": "USD",
        "platform": "VANTIV",
        "authDate": null,
        "authCode": null,
        "captured": null,
        "settled": null,
        "settledCurrency": null,
        "settledTotal": null,
        "allowPartial": 0,
        "order": null,
        "description": null,
        "descriptor": null,
        "terminal": null,
        "terminalCapability": null,
        "entryMode": null,
        "origin": 2,
        "tax": null,
        "total": 1000,
        "cashback": null,
        "authorization": "12345",
        "approved": 100,
        "cvv": 123,
        "swiped": 0,
        "emv": 0,
        "signature": 0,
        "unattended": null,
        "clientIp": null,
        "first": null,
        "middle": null,
        "last": null,
        "company": null,
        "email": null,
        "address1": null,
        "address2": null,
        "city": null,
        "state": null,
        "zip": "12345",
        "country": null,
        "phone": null,
        "mid": "12345678",
        "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": "single",
        "copyReason": null,
        "originalApproved": 1000,
        "currencyConversion": null,
        "serviceCode": null,
        "authTokenCustomer": null,
        "debtRepayment": 0,
        "statement": null,
        "convenienceFee": 0,
        "surcharge": null,
        "channel": null,
        "funded": null,
        "fundingEnabled": 1,
        "requestSequence": 1,
        "processedSequence": 1,
        "mobile": null,
        "pinEntryCapability": null,
        "fbo": "WORLDPAY_FBO1",
        "returned": null,
        "txnsession": null,
        "networkTokenIndicator": 0,
        "softPosDeviceTypeIndicator": null,
        "softPosId": null,
        "tip": null,
        "fundingHoldReleaseDate": 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 voided transaction:

Parameter

Notes

id

The ID of the new reversal Transaction.

fortxn

The original credit card transaction the reversal applies to.

status

Whether the reverse transaction was approved or failed:

  • 1: Approved

  • 2: Failed

type

The type of transaction being processed.

  • 4: Credit Card Reverse Authorization.

total

The total amount that was voided in the transaction.

Result: The initial transaction has been removed from the batch, ensuring that no funds will be captured. A new reverse transaction has been processed to void the original transaction, permanently canceling it and removing the pending charge from the customer’s account.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close