Start withdrawal verification
Start withdrawal email verification after the customer confirms the destination number and network. Save an idempotency key before calling. The status can be pending while the email is prepared. Submit the email code to /api/mpesa/withdraw.
Start withdrawal email verification after the customer confirms the destination number and network. Save an idempotency key before calling. The status can be pending while the email is prepared. Submit the email code to /api/mpesa/withdraw.
Required API key scope: withdraw.
Request example
POST /api/mpesa/withdrawal-verification HTTP/1.1Host: api.edgepro.siteX-API-Key: <your-api-key>X-Deripay-API-Version: 2Accept: application/jsonContent-Type: application/jsonIdempotency-Key: withdrawal-order-1002{ "connection_id": "conn_example_01", "phone_number": "254712345678", "country": "KE", "amount_usd": 5, "account_login_id": "CR123456"}partnerAPIKeyX-API-Key<token>X-API-Key*stringYour API key. Send requests from your server.
X-Deripay-API-Version*stringSelects the response and error format documented here. Without it, the same URL returns the original format.
Accept?stringIdempotency-Key?stringRequired unless idempotency_key is supplied in the JSON body. Header takes precedence.
1 <= lengthapplication/json- body
Idempotency-Key header or idempotency_key body value is required. Header takes precedence. Unknown fields are ignored. Send only the documented fields.
account_login_id?stringAn eligible USD account linked to the customer. Omit to use their selected account.
amount_usd*number0 < valueconnection_id*stringcountry?stringCountry code. Defaults to your workspace country, or KE if none is assigned. The country must be permitted for your workspace.
idempotency_key?stringRequired here or in Idempotency-Key. The nonempty header takes precedence. Reuse the same key and exact payload across retries.
operator?stringNetwork code returned by GET /corridors. Required when the selected market has multiple networks; otherwise optional.
phone_number*string[key: string]?anyRequest accepted. Check the transaction status to confirm payment completion.
application/json- response
success*booleanmessage*stringdata*curl -X POST 'https://api.edgepro.site/api/mpesa/withdrawal-verification' \ -H 'X-API-Key: <your-api-key>' \ -H 'X-Deripay-API-Version: 2' \ -H 'Accept: application/json' \ -H 'Idempotency-Key: withdrawal-order-1002' \ -H 'Content-Type: application/json' \ -d '{ "connection_id": "conn_example_01", "phone_number": "254712345678", "country": "KE", "amount_usd": 5, "account_login_id": "CR123456"}'{ "success": true, "message": "Withdrawal verification email sent successfully", "data": { "id": "507f1f77bcf86cd799439011", "connection_id": "conn_example_01", "type": "withdrawal", "payment_method": "mobile_money", "status": "action_required", "country": "KE", "network": "mpesa", "local": { "amount": "650", "currency": "KES" }, "settlement": { "amount": "5.00", "currency": "USD" }, "idempotency_key": "withdrawal-order-1002", "account_login_id": "CR123456", "next_action": { "type": "email_code" }, "failure": null, "created_at": "2026-10-12T09:00:00Z", "updated_at": "2026-10-12T09:00:00Z", "completed_at": null }}Submit deposit verification POST
Submit the mobile network’s verification code while next_action.type is one_time_code. Keep the code as a string to preserve leading zeros. The existing otp field is also accepted instead of code. Follow any next_action returned. On 429, stop submitting codes and check the transaction.
Resend withdrawal verification POST
Resend the email code for the same withdrawal. Supply its connection and transaction IDs. If throttled, wait before retrying; keep using the existing withdrawal.