Reversals API

The Reversals API allows merchants to initiate transaction reversals and monitor their processing status.

Authentication

All Reversal API endpoints require the x-access-token authentication header as described in the Authentication section of this documentation.

---

Initiate Reversal

Initiates a reversal request for a previously processed payment.

Endpoint

POST /v1/reversals/initiate

Headers

Header	Required	Description
x-access-token	Yes	Authentication token.

Request Body

{
  "reversal_reference": "xxxxxxx",
  "payment_reference": "xxxxxxx",
  "reversal_reason": "Test"
}

Request Parameters

Field	Type	Required	Description
reversal_reference	String	Yes	A unique identifier generated by the merchant for this reversal request. This reference must be unique across all reversal requests.
payment_reference	String	Yes	The merchant payment reference used when the original payment was initiated.
reversal_reason	String	Yes	Reason for requesting the reversal.

---

Success Response

The API accepts the reversal request and begins asynchronous processing.

HTTP Status: 200 OK

{
  "status_code": 176,
  "status_description": "Reversal request accepted",
  "reversal_reference": "e18f2c3e-3ead-4200-b81c-87dde8bbd2b2",
  "reversal_status": "pending",
  "message": "The reversal request has been accepted and is being processed."
}

Response Fields

Field	Description
status_code	Internal response code.
status_description	Description of the response.
reversal_reference	Merchant reversal reference supplied during initiation.
reversal_status	Current status of the reversal. Initially returned as pending.
message	Additional information about the request.

---

Error Response

If the reversal request cannot be accepted, an error response is returned.

{
  "status_code": 172,
  "status_description": "Validation Failed",
  "message": "Transaction Already Reversed",
  "reference": "e4c26428-3682-4535-8105-fee6fca4eadd"
}

Common Validation Errors

Message	Description
Transaction Already Reversed	The payment has already been successfully reversed.
Invalid Payment Reference	The supplied payment reference could not be found.
Duplicate Reversal Reference	The supplied reversal reference has already been used.
Transaction Not Eligible for Reversal	The payment cannot be reversed based on its current status or business rules.

---

Query Reversal Status

Retrieves the latest processing status of a reversal request.

Endpoint

GET /v1/reversals/{reversal_reference}/status

Headers

Header	Required	Description
x-access-token	Yes	Authentication token.

Path Parameters

Parameter	Description
reversal_reference	The unique reversal reference supplied during reversal initiation.

---

Successful Response

{
  "reversal_reference": "e18f2c3e-3ead-4200-b81c-87dde8bbd2b2",
  "reversal_status": "successful",
  "reversal_amount": "1000.00",
  "currency_code": "KES",
  "reversal_date": "2026-06-30T20:36:48.496Z",
  "receiver_narration": "successful"
}

Response Fields

Field	Description
reversal_reference	Merchant reversal reference.
reversal_status	Current reversal status.
reversal_amount	Amount successfully reversed.
currency_code	Currency of the reversal.
reversal_date	Date and time when the reversal was completed.
receiver_narration	Processing result or narration associated with the reversal.

---

Reversal Callback

If a callback URL has been configured for your merchant account, the platform will send an asynchronous notification once the reversal processing has completed.

The callback payload is identical to the response returned by the Status Query endpoint.

Callback Payload

{
  "reversal_reference": "e18f2c3e-3ead-4200-b81c-87dde8bbd2b2",
  "reversal_status": "successful",
  "reversal_amount": "1000.00",
  "currency_code": "KES",
  "reversal_date": "2026-06-30T20:36:48.496Z",
  "receiver_narration": "successful"
}

---

Reversal Status Values

Status	Description
pending	The reversal request has been accepted and is awaiting processing.
processing	The reversal is currently being processed.
successful	The reversal completed successfully.
failed	The reversal could not be completed.

---

Reversal Flow

Merchant
    │
    │ POST /v1/reversals/initiate
    ▼
API
    │
    │ Request Accepted
    ▼
Status = pending
    │
    │ Background Processing
    ▼
Status = successful / failed
    │
    ├── Callback (if configured)
    │
    └── Available via
        GET /v1/reversals/{reversal_reference}/status