Reversal Authorization

Overview

📘
Refunds vs Reversals

A reversal is applied to an authorization (it cancels or voids the authorization before settlement).

A refund is applied to a sale (a completed, settled transaction).

A REVERSAL transaction allows a developer to reverse a previous authorization. This is helpful in cases where a merchant would not want to be holding customer funds that they do not intend to capture - they can apply either full or partial reversal in such cases.

Before reading the usage of a reversal transaction, make sure you are up to speed with Processing an Authorization and Capturing an Authorization.

📘
Note
This transaction does not fall specifically under Card Present or Card Not Present categories. It allows for all POS profiles. Reversals can be issued for both CP and CNP authorization transactions using their respective transaction IDs. In the case of the deviceProfile parameter, check out API References for all the available body parameters and enumerations.
A reversal must typically be performed within a short time window after the original authorization (often within 24–72 hours, depending on the card network and processor rules). After this period, a Void or Refund may be required instead.

Sample Request

POST /api/v4/accounts/{accountId}/payments/{transactionId}/reversal

{accountId} value in the path is the PayConex™ account ID number.
{transactionId} value in the path is the authorization transactionId to capture.

{
  "posProfile": "ECOMMERCE"
}

*Required Scopes: pcx:payments:*, pcx:payments:device:*, pcx:payments:card_not_present:*, pcx:payments:reversal

In the response to the reversal POST request, we get the standalone reversal transaction with its own unique transactionId and full set of metadata. This allows you to track, audit, and reconcile the reversal independently while still maintaining a reference to the original transaction it is associated with.

📘
Refund Ids of the new transaction
The refundObject.refundIds of an individual reversal always points to the initial authorization with the single refundId.
For example,
{
  ...
  "refundObject": {
    "refundBalance": "0.00",
    "refundIds": [
      "000000094726"
    ]
  }
}
For more, see refundObject.

When the previous transaction gets (fully) reversed, it assigns the transactionType to REVERSAL and populates the refundObject, appending a refundId to the refundObject.refundIds of the original transaction to keep track of refunds. We can see this in the Response Example below.

🚧
API Reference
For the rest of the parameters optional for this request such as amounts, deviceProfile (for reversing CP authorizations), trace , check out API Reference | Reversal Transaction.

Understanding Reversals in PayConex

Reversal is identical to PayConex Refund Transaction in this regard:

Reversals are standalone transactions: Every reversal receives its own unique transactionId and full set of metadata, independent of the original authorization.
Impact on the original transaction: A reversal modifies the balance of the initial authorization transaction. Once a transaction is fully reversed/refunded, its status is updated to VOIDED and REFUNDED (once settled).
Link between authorization and reversals: The original authorization transaction includes a refundObject that contains:
- A list of all related reversals transaction IDs (child transactions).
- The refundBalance field showing the remaining amount still available for reversal.

If the transaction is fully reversed with refundBalance being 0.00, it is not allowed to be captured.

{
  "message": "This transaction is not allowed to be captured",
  "errorCode": 40001,
  "errorType": "invalid_request",
  "traceId": "ed9c9d07-0dfb-4108-b932-f07b89e32faf"
}

Even though the reversal behaves similarly to the refund in the PayConex V4 API, the two are intended for entirely different use cases.

For example, you can never reverse a CAPTURED/SALE transaction - for that, use the Refund Transaction Endpoint.

{
  "message": "Transaction type SALE is not reversible",
  "errorCode": 40001,
  "errorType": "invalid_request",
  "traceId": "7d5678f8-cd8f-4357-9a47-4245eb4998e3"
}

🚧
Transactions Without Authorized Amounts
A transaction must have an authorized amount in order to be reversed.
For example, a store transaction cannot be reversed because it does not carry any monetary amount.
{
 "message": "Transaction type STORE is not reversible",
 "errorCode": 40001,
 "errorType": "invalid_request",
 "traceId": "3306f0ae-a8ca-4544-be76-6ef73420cb67"
}
The same goes for the zero amount authorization.
{
 "message": "Zero dollar authorizations cannot be reversed",
 "errorCode": 40001,
 "errorType": "invalid_request",
 "traceId": "ff52fa8a-39ce-4fc0-b1e0-6d88dc6f5a75"
}

Initial Authorization

Let's say the following is our initial authorization transaction that is to be reversed.

For more examples, refer to Processing an Authorization.

GET /api/v4/accounts/{accountId}/payments/000000094686

*Required Scopes: pcx:payments:*, pcx:payments:read

{
  "transactionId": "000000094686",
  "status": "AUTHORIZED",
  "timestamp": "2026-04-22T12:35:38.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "My City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "My City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "trace": {
    "sourceIp": "10.18.5.133",
    "history": [
      {
        "action": "authorization",
        "requestId": "a653ab63-c69c-4541-bd85-9667ad828453",
        "correlationId": "77a977d7-aba6-4d20-bfe6-e57c3275855a",
        "timestamp": "2026-04-22T07:35:36-05:00"
      }
    ],
    "networkTransactionId": "016112724681623G052"
  },
  "amounts": {
    "currency": "USD",
    "approved": "15.00",
    "requested": "15.00",
    "balance": "15.00"
  },
  "auth": {
    "code": "OK8671",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "AUTHORIZATION",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "15.00"
  }
}

Full Reversal Transaction Metadata

If we retrieve the transaction metadata of the reversed "000000094686" transaction, we see that the status of the transaction is now "VOIDED", with the transactionType of "REVERSAL", and the refund action is appended to trace.history. Particularly, the refundIds contains the ids that point to the individual reversal transactions.

GET /api/v4/accounts/{accountId}/payments/000000094686

*Required Scopes: pcx:payments:*, pcx:payments:read

{
  "transactionId": "000000094686",
  "status": "VOIDED",
  "timestamp": "2026-04-22T12:35:38.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "My City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "My City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "trace": {
    "sourceIp": "10.18.5.133",
    "history": [
      {
        "action": "authorization",
        "requestId": "a653ab63-c69c-4541-bd85-9667ad828453",
        "correlationId": "77a977d7-aba6-4d20-bfe6-e57c3275855a",
        "timestamp": "2026-04-22T07:35:36-05:00"
      },
      {
        "action": "refund",
        "requestId": "e0a783bd-84eb-417b-871d-4c39abf2f067",
        "correlationId": "47f98884-7847-45a9-ba89-c64be0afa367",
        "timestamp": "2026-04-22T07:58:34-05:00"
      }
    ],
    "networkTransactionId": "016112724681623G052"
  },
  "amounts": {
    "currency": "USD",
    "approved": "15.00",
    "requested": "15.00"
  },
  "auth": {
    "code": "OK8671",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "REVERSAL",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "0.00",
    "refundIds": [
      "000000094706"
    ]
  }
}

🚧
Note
Fully reversed transactions, as the context implies cannot be additionally reversed.
{
  "message": "Transaction type REVERSAL is not reversible",
  "errorCode": 40001,
  "errorType": "invalid_request",
  "traceId": "98f86955-965d-4c5d-ab42-441d9fbeeba0"
}

Partial Reversal

A transaction can be reversed multiple times as long as there is a remaining amount in the refundBalance.

This allows for multiple partial refunds if you don't want to reverse the entire amount in case the customer has made a mistake of inputting the wrong amount to be charged with or similar.

POST /api/v4/accounts/{accountId}/payments/{transactionId}/reversal

{accountId} value in the path is the PayConex™ account ID number.
{transactionId} value in the path is the authorization transactionId to capture.

{
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "10.00",
    "currency": "USD"
  }
}

*Required Scopes: pcx:payments:*, pcx:payments:device:*, pcx:payments:card_not_present:*, pcx:payments:reversal

📘
Full Refund by default
We can conclude that without the amounts parameter specified, a Full Reversal is applied by default.

🚧
Reverse Amount Limit
The merchant is not allowed to reverse an amount greater than the remaining balance.
This is also the case when refunding the transaction.
{
 "message": "Reverse amount is greater than the remaining reversible amount",
 "errorCode": 40001,
 "errorType": "invalid_request",
 "traceId": "13d61322-07b3-4258-832f-7111e923c292"
}

If we retrieve the transaction metadata of the partially reversed "000000094726" transaction, we see that the status of the transaction stays "AUTHORIZED", with the transactionType of "AUTHORIZATION", and the refund action is appended to trace.history. Particularly, the refundIds contains the ids that point to the individual reversal transactions.

GET /api/v4/accounts/{accountId}/payments/{transactionId}

*Required Scopes: pcx:payments:*, pcx:payments:read

{
  "transactionId": "000000094726",
  "status": "AUTHORIZED",
  "timestamp": "2026-04-22T13:06:25.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "My City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "My City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "trace": {
    "sourceIp": "10.18.5.131",
    "history": [
      {
        "action": "authorization",
        "requestId": "8310f7c1-bbc9-454a-b9db-e20461e72ac9",
        "correlationId": "21eaa6b5-cbfe-4024-bd34-1a97ed5eb634",
        "timestamp": "2026-04-22T08:06:23-05:00"
      },
      {
        "action": "refund",
        "requestId": "c254ec93-a9bd-4177-b9cc-4ed41f27160d",
        "correlationId": "8bd481c3-a5e6-4994-b055-5f1f635a7c48",
        "timestamp": "2026-04-22T08:13:36-05:00"
      }
    ],
    "networkTransactionId": "016112303867935G451"
  },
  "amounts": {
    "currency": "USD",
    "approved": "15.00",
    "requested": "15.00",
    "balance": "5.00"
  },
  "auth": {
    "code": "OK5911",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "AUTHORIZATION",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "5.00",
    "refundIds": [
      "000000094746"
    ]
  }
}

Capturing Authorization

With partial reversals, if a remaining amount is still reserved for capture under the authorization, the merchant can capture that transaction once ready.

🚧
Partial Reversal Transaction
As demonstrated above, the transaction status remains "AUTHORIZED" as well as the original transaction type, for example, "transactionType": "AUTHORIZATION".
This can also determine if you are able to capture the transaction.

POST /api/v4/accounts/{accountId}/payments/{transactionId}/capture

{
  "posProfile": "ECOMMERCE"
}

*Required Scopes: pcx:payments:*, pcx:payments:device:*, pcx:payments:card_not_present:*, pcx:payments:capture

{
  "transactionId": "000000094726",
  "status": "CAPTURED",
  "timestamp": "2026-04-22T13:21:15.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "My City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "My City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "trace": {
    "sourceIp": "10.18.5.131",
    "history": [
      {
        "action": "authorization",
        "requestId": "8310f7c1-bbc9-454a-b9db-e20461e72ac9",
        "correlationId": "21eaa6b5-cbfe-4024-bd34-1a97ed5eb634",
        "timestamp": "2026-04-22T08:06:23-05:00"
      },
      {
        "action": "refund",
        "requestId": "c254ec93-a9bd-4177-b9cc-4ed41f27160d",
        "correlationId": "8bd481c3-a5e6-4994-b055-5f1f635a7c48",
        "timestamp": "2026-04-22T08:13:36-05:00"
      },
      {
        "action": "capture",
        "requestId": "0fd9e2a9-e022-4a70-a043-61c6c3fb531e",
        "correlationId": "e3668de7-04b1-4597-b6e6-8ee80c370375",
        "timestamp": "2026-04-22T08:21:14-05:00"
      }
    ],
    "networkTransactionId": "016112303867935G451"
  },
  "amounts": {
    "currency": "USD",
    "approved": "15.00",
    "requested": "15.00",
    "balance": "5.00"
  },
  "auth": {
    "code": "OK5911",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "5.00",
    "refundIds": [
      "000000094746"
    ]
  }
}

For more information, refer to the Capturing an Authorization page.