Daraja Agent KitReversal
By the end of this track you can find out what happened and undo it.
0/3 finished
Step 1
The idea
A reversal pulls a whole customer payment back. There are no partial amounts; for those, refund with B2C.
Step 2
How it works
What a reversal does
It pulls back a whole C2B or STK payment made to your shortcode, by its receipt number. The amount must be the full amount. It suits payments made in error, not refunds for part of an order. The initiator needs the reversal role, and Safaricom must approve the API for your shortcode.
The request
POST to /mpesa/reversal/v1/request. Here the receiver identifier type must be 11, the spelling is again RecieverIdentifierType, and Remarks takes 2–100 characters. Failure codes are letters and numbers, such as R000002 for an invalid original transaction.
{ "Initiator": "testapi", "SecurityCredential": "<encrypted password>", "CommandID": "TransactionReversal", "TransactionID": "TJT4XXXXXX", "Amount": 10, "ReceiverParty": "600996", "RecieverIdentifierType": "11", "ResultURL": "https://your-domain.example/reversal/result", "QueueTimeOutURL": "https://your-domain.example/reversal/timeout", "Remarks": "Paid in error"}Reversal or refund?
- The whole payment was a mistake: reversal.
- The customer wants part of it back: a B2C payout for that part.
Step 3
Try it
$ mpesa pay reverse <receipt> 10
With the MCP server, ask your agent to use mpesa_reverse_transaction
Step 4
Common mistakes
- Trying to reverse part of a payment.
- Letting reversals run without a person approving them. Treat them as privileged and log the reason.
- Reversing without recording it as a new ledger entry that points at the original.
Go deeper
A customer paid KES 1,000 and wants KES 300 back. Reversal or B2C?
Answer in your own words first.
Show the answerHide the answer
B2C.