Withdrawals

A withdrawal has two steps. You start it with an amount in USD. Deriv sends the customer a verification code. You submit the code, Deriv releases the money, and Deripay pays it out to the customer's phone in the local currency.

1. Start a withdrawal

POST /api/v2/withdrawals
Idempotency-Key: wd_user_1842_req_0001

Scope: withdrawals. Rate limit: 20 per minute. An idempotency key is required.

curl https://deriapi.site/api/v2/withdrawals \
  -H "Authorization: Bearer $DERIPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wd_user_1842_req_0001" \
  -d '{
    "connection_id": "con_6720f1a2b3c4d5e6f7a8",
    "country": "KE",
    "amount_usd": 10,
    "phone_number": "0712345678"
  }'

Before you call it:

1. Read withdraw_limits_usd from GET /rates?country=….
2. Read the main wallet balance from GET /connections/{id}/balance. The amount must not be more than balance.
3. Read the payout number back to the customer. Most networks cannot check the recipient's name.

Response: 201 with a transaction in state: "awaiting_code". amount is the estimated local payout and amount_usd is what leaves Deriv. Store data.id before you ask for the code.

{
  "success": true,
  "data": {
    "id": "txn_6720f9e8d7c6b5a4f3e2",
    "object": "transaction",
    "type": "withdrawal",
    "state": "awaiting_code",
    "status": "WITHDRAWAL_EMAIL_SENT",
    "status_message": null,
    "connection_id": "con_6720f1a2b3c4d5e6f7a8",
    "country": "KE",
    "currency": "KES",
    "operator": "mpesa",
    "amount": 1250,
    "amount_usd": 10,
    "phone_number": "2547•••678",
    "customer_action": null,
    "terminal": false,
    "created_at": "2026-11-03T09:00:00.000Z",
    "updated_at": "2026-11-03T09:00:02.000Z"
  }
}

2. The customer gets a code

Deriv sends a verification code to the contact registered on the customer's Deriv account, usually by email. Ask the customer to enter it in your form. Keep the code as a string: it can start with zero. Deriv codes are currently six digits.

Resend the code

POST /api/v2/withdrawals/{id}/resend

Scope: withdrawals. Rate limit: 10 per minute. No body.

curl -X POST https://deriapi.site/api/v2/withdrawals/txn_6720f9e8d7c6b5a4f3e2/resend \
  -H "Authorization: Bearer $DERIPAY_API_KEY"

Works while the state is awaiting_code. Returns the same transaction. Use the newest code. Once the withdrawal has moved on, resend returns 409 WITHDRAWAL_INVALID_TRANSACTION_STATE. Respect Deriv's own limits on how often a code can be sent.

3. Confirm with the code

POST /api/v2/withdrawals/{id}/confirm

Scope: withdrawals. Rate limit: 20 per minute.

curl https://deriapi.site/api/v2/withdrawals/txn_6720f9e8d7c6b5a4f3e2/confirm \
  -H "Authorization: Bearer $DERIPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "verification_code": "048213" }'

Returns 200 with the transaction, usually in state: "processing". The money is not on the customer's phone yet. Show success only when the state is completed.

If the code is wrong or expired you get an error such as WITHDRAWAL_INVALID_OTP. Fetch the transaction: if it is back in awaiting_code, let the customer re-enter the code or resend it, on the same transaction. Never apply a code to a different transaction.

If confirm times out, fetch the transaction before retrying. Confirming a withdrawal that already completed returns the completed transaction.

Processing until paid out

After a correct code the withdrawal stays in processing while Deriv releases the funds and the mobile money payout is sent. A payout that fails on the first try is retried by Deripay. That shows as raw status WITHDRAWAL_B2C_FAILED, which is still processing, not final.

Do not start a new withdrawal to "fix" a slow one. Once Deriv has released the money, a second withdrawal would take money from the customer again. Wait for completed or failed, and contact support with the transaction id if it stays in processing longer than you expect.

One active withdrawal at a time

Deripay allows one active withdrawal per customer, Deriv login and payout number. A different idempotency key does not get round it.

When one of these refuses a request, nothing was created, so you can retry the same logical request later with the same idempotency key.

Withdrawal states

Errors

The full list is in Errors.