Payment Agent REST

Discover payment agents and execute agent-facilitated deposits and withdrawals.

Overview

The Payment Agent APIs let applications find active payment agents, retrieve an agent's full profile, and move funds — agent deposits and client withdrawals — through them. Payment agents deposit funds into a client's wallet via the transfer endpoint, while clients withdraw through an agent using a one-time verification code. All endpoints are standard REST calls and require the payment OAuth2 scope.

Typical Workflow

Discovering agents

1. Call GET /payment-agents/v1/agent-statistics to find which currencies and countries are served.
2. List agents for a currency with GET /payment-agents/v1/agents, optionally filtered by country. Results are paginated; use page and per_page to page through them.
3. Fetch a single agent's full profile with GET /payment-agents/v1/agents/{id}.

Client withdrawal

1. Request a one-time code via POST /payment-agents/v1/withdraw/verification_code. The code is sent to the client's registered email or phone and is valid until it expires.
2. Submit the withdrawal with the 6-digit code via POST /payment-agents/v1/withdraw.
3. If you supplied a request_id, poll GET /payment-agents/v1/withdraw/{request_id} until the status settles.

Agent deposit — an authenticated payment agent deposits funds directly into a client's wallet with POST /payment-agents/v1/transfer (completes synchronously).

Available Endpoints

Authentication

All endpoints require the Deriv-App-ID header and an Authorization: Bearer YOUR_OAUTH_TOKEN header. The token must carry the payment scope; otherwise the API returns 403 Forbidden.

OAuth2 Scopes

1curl -X GET "https://api.derivws.com/payment-agents/v1/agents?currency=USD" \
2  -H "Deriv-App-ID: YOUR_APP_ID" \
3  -H "Authorization: Bearer YOUR_OAUTH_TOKEN"

Response Status Codes

The API uses standard HTTP status codes to indicate success or failure:

Not all codes apply to every endpoint. 404 Not Found applies only to GET /payment-agents/v1/agents/{id}, and GET /payment-agents/v1/agent-statistics does not return 400.

Error Response Format

All error responses follow a consistent envelope with an empty data object, an errors array, and metadata:

1{
2  "data": {},
3  "errors": [
4    {
5      "status": 400,
6      "code": "WalletFundsInsufficient",
7      "detail": {
8        "message": "The agent's wallet does not hold enough funds for this transfer"
9      }
10    }
11  ],
12  "metadata": {
13    "endpoint": "/payment-agents/v1/transfer",
14    "method": "POST",
15    "timing": 38
16  }
17}

Error codes include: AgentIDInvalid, AgentNotFound, AgentInactive, AgentSelfTransfer, AgentSelfWithdraw, AgentCurrencyUnsupported, InvalidAgentID, NicknameNotFound, NoClientWallet, ClientCountryUnsupported, WithdrawalAmountMinimum, WithdrawalAmountMaximum, WalletFundsInsufficient, InvalidOTP, OtpRateLimitExceeded, RequestIDUsed, RequestIDNotFound, InvalidRequestIDFormat, TransferFailed, WithdrawalFailed, OTPValidationFailed, OtpValidationRateLimitExceeded, VerificationCodeFormatInvalid, VerificationCodeRequestFailed, WalletLookupFailed, NicknameLookupFailed, ClientIdentityLookupFailed