Agent de paiement REST

Découvrez les agents de paiement et effectuez des dépôts et des retraits facilités par les agents.

Vue d'ensemble

Les API d'agent de paiement permettent aux applications de trouver des agents de paiement actifs, de récupérer le profil complet d'un agent et de déplacer des fonds — dépôts d'agents et retraits de clients — par leur intermédiaire. Les agents de paiement déposent des fonds dans le Wallet d'un client via le point de terminaison transfer, tandis que les clients se retirent via un agent en utilisant un code de vérification à usage unique. Tous les points de terminaison sont des appels REST standard et nécessitent la portée OAuth2 payment.

Flux de travail typique

Découverte des agents

1. Appelez GET /payment-agents/v1/agent-statistics pour déterminer quelles devises et quels pays sont pris en charge.
2. Listez les agents pour une devise avec GET /payment-agents/v1/agents, éventuellement filtrés par pays. Les résultats sont paginés ; utilisez page et per_page pour les parcourir.
3. Récupérez le profil complet d'un seul agent avec GET /payment-agents/v1/agents/{id}.

Retrait du client

1. Demandez un code à usage unique via POST /payment-agents/v1/withdraw/verification_code. Le code est envoyé à l'adresse e-mail ou au téléphone enregistré du client et est valide jusqu'à son expiration.
2. Soumettez le retrait avec le code à 6 chiffres via POST /payment-agents/v1/withdraw.
3. Si vous avez fourni un request_id, interrogez GET /payment-agents/v1/withdraw/{request_id} jusqu'à ce que le statut se stabilise.

Dépôt d'agent — un agent de paiement authentifié dépose des fonds directement dans le Wallet d'un client avec POST /payment-agents/v1/transfer (se termine de manière synchrone).

Points de terminaison disponibles

Authentification

Tous les endpoints nécessitent un en-tête Authorization: Bearer YOUR_OAUTH_TOKEN portant le scope payment ; sinon l'API renvoie 403 Forbidden. Lors de l'authentification avec un Personal Access Token (PAT), l'en-tête Deriv-App-ID est également requis (voir Authentication).

Portées OAuth2

1curl -X GET "https://api.derivws.com/payment-agents/v1/agents?currency=USD" \
2  -H "Authorization: Bearer YOUR_OAUTH_TOKEN"
3# Add -H "Deriv-App-ID: YOUR_APP_ID" when authenticating with a Personal Access Token (PAT).

Codes de statut de réponse

L'API utilise des codes de statut HTTP standard pour indiquer le succès ou l'échec :

Tous les codes ne s'appliquent pas à chaque point de terminaison. 404 Not Found s'applique uniquement à GET /payment-agents/v1/agents/{id}, et GET /payment-agents/v1/agent-statistics ne renvoie pas 400.

Format de réponse d'erreur

Toutes les réponses d'erreur suivent une enveloppe cohérente avec un objet data vide, un tableau errors et 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}

Les codes d'erreur incluent : 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