Deposits
Accept mobile money or crypto deposits into a customer’s Deriv Wallet.
Use POST /api/mpesa/deposit for mobile money or POST /api/crypto/deposit for crypto. The mobile money endpoint supports the countries and networks returned by /api/corridors.
Save a unique idempotency key before sending the request. Supply it in the Idempotency-Key header or the idempotency_key body field. A nonempty header takes precedence.
Both endpoints return a transaction. Save its id, connection_id, idempotency_key, amounts and status. Retrying the same request can return an existing transaction. Wait for completed before treating the deposit as funded.
Customer actions
Follow the returned next_action:
| Type | What to do |
|---|---|
one_time_code | Ask for the code sent by the mobile network and submit it as a string. |
redirect | Open next_action.url, then check the transaction when the customer returns. |
ussd | Show next_action.code for the customer to dial, then monitor the transaction. |
contact_support | Stop submitting requests and contact support with the transaction ID. |
Submit a deposit code to POST /api/mpesa/transactions/{transaction_id}/otp with connection_id, type: "one_time_code" and code. The existing otp field is also accepted instead of code. Preserve leading zeros. Submit only while next_action.type is one_time_code; if another action is returned, follow that action. On 429, stop submitting codes and check the transaction status. Never ask for a mobile money PIN.
For crypto, open the checkout URL exactly as returned. The customer chooses an asset and network there. Check the transaction after checkout; a redirect or email alone does not confirm payment.
Confirm the deposit
Poll GET /api/mpesa/transactions/{transaction_id}?connection_id=… or use SSE monitoring. A status of completed confirms that the deposit reached the customer's Wallet.
If the status is reconciliation_required, keep checking the same transaction and contact support if needed. Do not charge the customer again. After a timeout or lost response, retry the original request with the same idempotency key.
A deposit funds the Wallet. To fund Options afterward, ask for customer consent and make a Wallet–Options transfer.