Withdraw

PostAuth required

Withdraws funds from the authenticated client's account through a payment agent. The withdrawal moves the requested amount out of the client's Wallet and into the agent's Wallet - the agent then settles the equivalent value with the client outside of Deriv. Requires a 6-digit verification_code obtained from POST /payment-agents/v1/withdraw/verification_code. Withdrawals start as pending and move to complete, rejected, or failed. Supply an optional request_id to track status afterwards via GET /payment-agents/v1/withdraw/{request_id}.

Endpoint

Post/payment-agents/v1/withdraw

Base URL: https://api.derivws.com

Status Codes

200OK - Withdrawal accepted. Returns the transaction status (typically pending).

400Bad request - One of: InvalidAgentID, AgentIDNotFound, AgentInactive, AgentSelfWithdraw, AgentCurrencyUnsupported, VerificationCodeFormatInvalid, NoClientWallet, ClientCountryUnsupported, WithdrawalAmountMinimum, WithdrawalAmountMaximum, DailyWithdrawalCountLimit, DailyWithdrawalAmountLimit, WalletFundsInsufficient, InvalidCurrency, InvalidAmount, InvalidRequestIDFormat, RequestIDUsed, InvalidOTP, OtpValidationRateLimitExceeded, InputError, ClientWithdrawDisabled, AgentDepositDisabled.

401Unauthorized - Invalid or missing authentication.

403Forbidden - Valid token but insufficient scope (payment scope required).

500Internal server error - One of: ClientIdentityLookupFailed, WalletLookupFailed, WithdrawalFailed, OTPValidationFailed, InternalError.

504Gateway timeout - Upstream service unavailable.

Error Responses

400Bad request - invalid verification code

{
  "data": {},
  "errors": [
    {
      "status": 400,
      "code": "InvalidOTP",
      "detail": { "message": "Invalid OTP" }
    }
  ],
  "metadata": {
    "endpoint": "/payment-agents/v1/withdraw",
    "method": "POST",
    "timing": 19
  }
}

400Bad request - amount below minimum

{
  "data": {},
  "errors": [
    {
      "status": 400,
      "code": "WithdrawalAmountMinimum",
      "detail": { "message": "Amount is below the agent's minimum withdrawal limit" }
    }
  ],
  "metadata": {
    "endpoint": "/payment-agents/v1/withdraw",
    "method": "POST",
    "timing": 16
  }
}

Authentication Required

This endpoint requires the Deriv-App-ID header to identify your application. OAuth2 Scope: payment

About Withdraw

The POST /payment-agents/v1/withdraw endpoint: Withdraws funds from the authenticated client's account through a payment agent. The withdrawal moves the requested amount out of the client's Wallet and into the agent's Wallet - the agent then settles the equivalent value with the client outside of Deriv. Requires a 6-digit verification_code obtained from POST /payment-agents/v1/withdraw/verification_code. Withdrawals start as pending and move to complete, rejected, or failed. Supply an optional request_id to track status afterwards via GET /payment-agents/v1/withdraw/{request_id}.

Withdrawal Verification Code Withdrawal Status

Any other questions? Get in touch