Customer authorization
Connect a customer’s Deriv account and save their connection ID.
Ask the customer to authorize your registered Deriv OAuth application. Send the resulting access token as deriv_api_token, together with your client_id, to POST /api/deriv/customers/authorize.
You can also send external_customer_id to identify the customer in your system, preferred_account_id to select an account, and token_expires_in for the token's remaining lifetime in seconds. Omit the lifetime if you do not know it.
The customer needs an eligible real USD account. Wallet payments require payment access; Wallet–Options transfers also require trade access. Demo accounts cannot process real payments.
Save data.connection_id with your customer record. Reauthorizing a customer refreshes their existing connection. Keep access tokens and verification codes out of logs and support screenshots.
GET /api/deriv/connections/{connection_id} returns the customer's details and linked accounts. Check authorization_status. If it requires reconnection, repeat OAuth authorization. If Deripay cannot check authorization temporarily, retry later before asking the customer to reconnect.
GET /api/deriv/connections/{connection_id}/balance returns the Wallet balance and, when available, the Options balance. Withdrawals use the Wallet balance. Transfer funds from Options to the Wallet before withdrawing them.
To save a default phone number, send phone_number to PATCH /api/deriv/connections/{connection_id}/default-phone. Include country if it differs from your workspace default. This saves the number for that connection; payment requests still require an explicit phone number and customer consent. Saving a number does not verify its owner. The payment_methods array is normally empty for partner connections.
See the reference for field requirements and response examples.