Withdrawals

Withdrawals convert USD from the customer's Deriv Wallet into mobile money in the selected country. Fetch current rates and limits, ask the customer to confirm the phone number and network, and save an idempotency key.

1. Send connection_id, phone_number, amount_usd and the idempotency key to POST /api/mpesa/withdrawal-verification. Include country, operator and account_login_id when needed.
2. Save the returned transaction ID. While the verification email is being prepared, the status can be pending. Ask the customer for the email code when next_action.type is email_code.
3. Send connection_id, transaction_id and verification_code to POST /api/mpesa/withdraw.
4. Monitor the transaction. A successful request can return processing; wait for completed to confirm payout.

To resend the email, call POST /api/mpesa/withdrawal-verification/resend with the same connection and transaction IDs. Keep using that withdrawal. Submit withdrawal email codes to the withdrawal endpoint and deposit codes to the deposit verification endpoint.

If a code is rejected, check the transaction before submitting another. Wait for the delay in Retry-After when present. If an active withdrawal blocks the request, resolve that withdrawal before starting another.

A payout may need reconciliation after funds leave the Wallet. If you receive reconciliation_required, 502 PAYMENT_UNCONFIRMED or 504 OUTCOME_UNKNOWN, keep checking the same transaction. Contact support with its ID if the outcome remains unclear. These responses do not confirm a refund.