Payment and Item Reversals

Overview

Reversals are used to cancel or refund payments that have already been recorded, such as a canceled order or a payment tied to an incorrect account or item.

PaymentExpress supports two levels of reversals:

1. Payment-Level Reversals: Reverse the entire payment and all associated items.
2. Item-Level Reversals: Reverse one or more individual items within a completed payment while leaving the remaining items intact.

Each reversal transaction is tracked independently with its own unique identifier and timestamp, ensuring a clear audit trail and transparency in downstream reconciliation.

Payment-Level Reversals

A Payment Reversal reverses the entire payment transaction, regardless of the number of items included. This type of action reverses the full payment and restores all associated funds to the customer.

Note: payment-level reversals must equal the amount of the transaction; partial payment-level reversals are not allowed.

Key points:

• The payment’s status changes to 'Refunded' or 'Voided', depending on when the payment is reversed.
• All items within the payment are marked as ‘Refunded’ or ‘Voided’.
• The paymentId from the original transaction remains linked to the new reversal record.
• The reversal is time-stamped and included in reconciliation reporting and Payment Activity Files.
• The reversal amount should equal the primary amount and not include service fees.

Example Request

HTTP
POST /api/v1/pay/payments/{paymentId}/reversal

{ 
"amount": "25.34"
}

Example Response

{
  "status": "success",
  "revision": 2,
  "amounts": {
    "primary": "-46.43",
    "fees": "-1.07",
    "total": "-47.50"
  }
}

Payment reversals can be initiated through authorized PaymentExpress system tools or via API endpoints available to specific clients under approved configurations.

Item-Level Reversals

An Item Reversal allows you to reverse one or more individual items within a payment without reversing the entire transaction. This approach is used when only certain portions of a payment require correction, for example, in the case where a customer incorrectly added an unnecessary item to their cart and checked out.

Key points:

• The reversal applies only to selected items within the original payment.
• The payment’s status changes to 'Refunded', depending on when the payment is reversed.
• The affected item amounts are adjusted according to the amount reversed, and PaymentExpress will update the transaction total.
• The original payment record remains active but reflects partial reversal activity.
• Each reversed item is recorded with a distinct reversal reference for traceability.
• The reversal amount should equal the primary amount and not include service fees.

As with full payment reversals, item reversals appear in reconciliation reporting and Payment Activity Files, providing clear tracking for both financial and audit purposes.

Example Request

HTTP
POST /api/v1/pay/payments/{paymentId}/items/{clientItemId}/reversal

{ 
"amount": "25.34"
 }

Example Response

{
  "status": "success",
  "revision": 2,
  "amounts": {
    "primary": "-46.43",
    "fees": "-1.07",
    "total": "-47.50"
  }
}

Further documentation on the Item-Level Reversals API, including expected responses, is available in our API Reference.