Reversal

Debits the subscriber and reduces what you owe SmartPay by the same amount. There is no float to return value to — undoing a credit simply means you no longer owe for it. Requires inbound:write and an X-Idempotency-Key.

Idempotent on its own reference, which must be new and distinct from the credit being reversed.

referencestringbodyrequired

A new reference for the reversal itself.

original_referencestringbodyrequired

The reference of the credit being undone.

reasonstringbody

Free text, for example customer_dispute. Stored on the audit trail.

Request

cURL
curl -X POST https://api.smartpay.sl/api/v1/inbound/reversal \
  -H "Content-Type: application/json" \
  -H "X-API-Key-ID: $SMARTPAY_API_KEY_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Nonce: $NONCE" \
  -H "X-Idempotency-Key: $IDEM" \
  -H "X-Signature: $SIG" \
  -d '{
    "reference": "UBA-REV-20260819-0001",
    "original_reference": "UBA-20260819-0001",
    "reason": "customer_dispute"
  }'

Response

200 Reversed
{
  "success": true,
  "code": "COMPLETED",
  "message": "Reversal posted",
  "data": {
    "inbound_id": "INB_2QW8XM4KP7RT",
    "reference": "UBA-REV-20260819-0001",
    "original_reference": "UBA-20260819-0001",
    "transaction_id": "TXN_9NL3XV6MQ2PK",
    "status": "COMPLETED",
    "operation": "reversal",
    "amount": 50000,
    "currency": "SLE",
    "partner_outstanding": 1250000,
    "completed_at": "2026-08-19T15:04:22Z"
  }
}

422 Already spent
{
  "success": false,
  "code": "INSUFFICIENT_SUBSCRIBER_BALANCE",
  "message": "Subscriber balance is lower than the amount to reverse; recover this manually"
}

Conditions

A credit is reversible when all of these hold:

Its status is COMPLETED — not already reversed, rejected or failed
It is inside your reversal window, seven days by default
The subscriber still holds at least the credited amount

Warning

If the customer has already spent the funds you get INSUFFICIENT_SUBSCRIBER_BALANCE and nothing moves. A reversal never overdraws a consumer wallet. That becomes a recovery conversation with our operations team, not an API retry.

Reversing an already-reversed credit returns 409 ALREADY_REVERSED. Two reversals racing on the same credit will only ever return the value once.

Conditions​

Conditions