Transaction status and events
Check payment progress and receive status updates.
Payment responses contain the same Transaction fields: payment method, amounts, status and any action the customer needs to take.
| Status | What it means |
|---|---|
pending | Deripay accepted the request or is waiting for payment confirmation. Keep checking. |
action_required | Follow next_action, then check again. |
processing | Collection, Wallet funding or payout is in progress. Keep checking. |
completed | The deposit reached the Wallet or the withdrawal payout completed. |
failed | The payment failed. Review its failure details before starting another payment. |
reconciliation_required | The outcome is unresolved. Keep the existing transaction; do not submit a replacement or assume a refund. |
local holds the collection or payout amount and currency. settlement holds the USD Wallet amount. Both amounts are decimal strings. network may be omitted. next_action, failure and completed_at are always present and can be null. Check status to determine completion.
GET /api/mpesa/transactions?connection_id=… returns up to 20 of the connection's newest transactions. This endpoint has no pagination parameters. For one transaction, call GET /api/mpesa/transactions/{transaction_id}?connection_id=…. Checking a pending transaction can also refresh its payment outcome.
Server-sent events
Connect from your server to GET /api/mpesa/transactions/{transaction_id}/monitor?connection_id=… with X-API-Key, X-Deripay-API-Version: 2 and Accept: text/event-stream. You can forward status updates to your frontend while keeping the API key on your server.
| Event | Body | What to do |
|---|---|---|
status | Transaction object, without a success wrapper. | Update the payment screen. |
complete | Final transaction object. | Check whether its status is completed or failed. |
heartbeat | {"ts":1791795600} | Keep listening. |
timeout | {"message":"reconnect"} | Reconnect to the same URL. |
error | JSON error with success: false and error. | Address the error before reconnecting. |
Errors before the stream opens use HTTP error responses. Once open, the HTTP status remains 200; an error event reports a failure that ends the stream. Deripay retries temporary lookup failures within the stream.
Reconnecting returns the current transaction state without replaying past events. Use polling if the stream is unavailable. Webhook subscriptions are not currently available.