API Playground Dashboard

Reversals

Reverse a previously completed SwiftWallet-initiated outgoing payment (B2C, B2Pochi, or B2B). Uses Safaricom's TransactionReversal API. On success, funds are credited back to the original merchant's payment wallet.

/v3/reversals/
POST /v3/reversals/ Auth Required Service: b2c_payments | b2pochi_payments | b2b_payments (scope is inherited from the original transaction)

Initiate Reversal

Request a reversal of a completed outgoing transaction. Provide either the SwiftWallet transaction_id or the M-Pesa receipt. The original transaction must be completed and owned by the authenticated user.

Headers

Header Value
Authorization Bearer YOUR_API_KEY
Content-Type application/json

Request Body

Field Type Required Description
transaction_id integer one of two SwiftWallet transaction ID of the original payment
mpesa_receipt string one of two M-Pesa receipt number (TransactionID) of the original payment
amount number Yes Amount to reverse. Must match the original transaction amount.
remarks string No Reversal remarks (default: "Reversal")
occasion string No Occasion/reason (max 100 chars)
callback_url string No URL to receive the reversal result callback

Example Response

JSON 
{
    "success": true,
    "status": "INITIATED",
    "message": "Reversal request accepted for processing",
    "reference": "REV-abc123",
    "reversal_transaction_id": 801,
    "original_transaction_id": 790,
    "identifiers": {
        "originatorConversationID": "34567-12345-1",
        "conversationID": "AG_20241231_...",
        "responseCode": "0",
        "responseDescription": "Accept the service request successfully."
    },
    "reversal_details": {
        "amount": 1000,
        "original_product": "b2c",
        "original_mpesa_receipt": "NLJ41HAY6Q",
        "remarks": "Reversal"
    }
}

cURL Example

bash 
curl -X POST 'https://swiftwallet.co.ke/v3/reversals/' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_id": 790,
    "amount": 1000,
    "remarks": "Customer refund",
    "callback_url": "https://yoursite.com/reversal-callback"
  }'

Callback Payload

After M-Pesa processes the reversal, SwiftWallet sends a POST request to your callback_url with the result. On success, the original transaction is marked as reversed and funds are credited back to your payments wallet.

POST to your callback_url 
{
    "success": true,
    "reversal_transaction_id": 801,
    "original_transaction_id": 790,
    "external_reference": "SALARY-DEC-001",
    "originatorConversationID": "34567-12345-1",
    "conversationID": "AG_20241231_...",
    "transactionID": "RL78HG3X9P",
    "status": "reversed",
    "timestamp": "2024-12-31T13:05:00+03:00",
    "result": {
        "ResultCode": 0,
        "ResultDesc": "The service request is processed successfully.",
        "TransactionAmount": 1000,
        "TransactionReceipt": "RL78HG3X9P",
        "TransactionCompletedDateTime": "31.12.2024 13:05:00"
    },
    "reversal_info": {
        "amount": 1000,
        "currency": "KES",
        "original_product": "b2c",
        "transaction_type": "reversal"
    }
}

Verify callbacks by checking the reversal_transaction_id and original_transaction_id against your records via the Transactions API.

Notes

  • Only completed outgoing transactions (B2C, B2Pochi, B2B) owned by the authenticated user can be reversed
  • The reversal amount must match the original transaction amount exactly
  • On successful reversal, the original transaction status changes from "completed" to "reversed"
  • Funds are credited back to your payments_wallet_balance; service fees are NOT refunded by default
  • Reversals are subject to M-Pesa timing rules: some transactions may be too old to reverse
  • The scope is inherited: you need at least the same service scope used to create the original transaction