Skip to main content
Skip table of contents

Refund a Credit Card Payment with the API

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

After confirming a credit card 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 a 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.

To get the transaction status before performing a refund:

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

    BASH
    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]=3,4
  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": 3,
                    "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 refund can be performed:

Value

Status

Notes

0

Pending

None

1

Approved

The payment must 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 a credit card refund transaction:

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

  2. Build the request payload with the following required fields:

    JSON
    {
    	"merchant": "t1_mer_123abc4d567890efg1h2i34",
    	"fortxn": "t1_txn_123abc4d567890efg1h2i34",
    	"total": 1000,
    	"type": 5, 
    	"origin": 2
    }

Parameter

Description

Notes

merchant

The ID of the Merchant that processed the original payment transaction.

This should be the same Merchant ID from the original payment transaction.

fortxn

The ID of the original transaction being refunded.

None

type

The type of transaction.

Required:

  • 5: Credit Card Refund

origin

The payment acceptance method used to capture the original payment.

Valid Values:

  • 1: Credit card terminal

  • 2: E-commerce System

total

The dollar amount of the transaction.

(Optional) Total amount to refund.

Note: Can be less than the original transaction amount. If omitted, the amount defaults to a full refund of the original transaction (excluding any previously refunded amounts).

  1. 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": "refund",
                    "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 refund transaction:

Parameter

Notes

id

The ID of the new credit card 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 credit card transaction type:

  • 5: Credit Card 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 cardholder’s account within three to eight business days, depending on the policies of the cardholder’s bank.

JavaScript errors detected

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

If this problem persists, please contact our support.