Agente de Pagamento REST

Descubra agentes de pagamento e execute depósitos e levantamentos facilitados por agentes.

Visão Geral

As APIs de Agente de Pagamento permitem que as aplicações encontrem agentes de pagamento ativos, obtenham o perfil completo de um agente e movam fundos — depósitos de agentes e levantamentos de clientes — através deles. Os agentes de pagamento depositam fundos numa Wallet de um cliente via o endpoint transfer, enquanto os clientes levantam através de um agente utilizando um código de verificação único. Todos os endpoints são chamadas REST padrão e requerem o âmbito OAuth2 payment.

Fluxo de Trabalho Típico

A descobrir agentes

1. Chame GET /payment-agents/v1/agent-statistics para descobrir quais moedas e países são servidos.
2. Liste agentes para uma moeda com GET /payment-agents/v1/agents, opcionalmente filtrados por país. Os resultados são paginados; utilize page e per_page para navegar por eles.
3. Obtenha o perfil completo de um único agente com GET /payment-agents/v1/agents/{id}.

Levantamento de cliente

1. Solicite um código único via POST /payment-agents/v1/withdraw/verification_code. O código é enviado para o e-mail ou telefone registado do cliente e é válido até expirar.
2. Submeta o levantamento com o código de 6 dígitos via POST /payment-agents/v1/withdraw.
3. Se forneceu um request_id, consulte GET /payment-agents/v1/withdraw/{request_id} até que o estado seja definido.

Depósito de agente — um agente de pagamento autenticado deposita fundos diretamente numa Wallet de um cliente com POST /payment-agents/v1/transfer (concluído de forma síncrona).

Endpoints Disponíveis

Autenticação

Todos os endpoints requerem o cabeçalho Deriv-App-ID e um cabeçalho Authorization: Bearer YOUR_OAUTH_TOKEN. O token deve ter o âmbito payment; caso contrário, a API devolve 403 Forbidden.

Âmbitos OAuth2

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"

Códigos de Estado da Resposta

A API usa códigos de estado HTTP padrão para indicar sucesso ou falha:

Nem todos os códigos se aplicam a todos os endpoints. 404 Not Found aplica-se apenas a GET /payment-agents/v1/agents/{id}, e GET /payment-agents/v1/agent-statistics não devolve 400.

Formato de Resposta de Erro

Todas as respostas de erro seguem um envelope consistente com um objeto data vazio, um array errors e 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}

Os códigos de erro incluem: 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