Agente de Pago REST

Descubra agentes de pago y ejecute depósitos y retiros facilitados por agentes.

Descripción general

Las Payment Agent APIs permiten a las aplicaciones encontrar agentes de pago activos, recuperar el perfil completo de un agente y mover fondos — depósitos de agentes y retiros de clientes — a través de ellos. Los agentes de pago depositan fondos en el Wallet de un cliente a través del endpoint transfer, mientras que los clientes retiran a través de un agente usando un código de verificación de un solo uso. Todos los endpoints son llamadas REST estándar y requieren el alcance OAuth2 payment.

REST API

Estas son APIs REST estándar que usan métodos HTTP (GET, POST). Todas las solicitudes requieren el encabezado Deriv-App-ID: YOUR_APP_ID y un token Authorization: Bearer YOUR_OAUTH_TOKEN que contenga el alcance payment.

Especificación OpenAPI

Vea la especificación completa de OpenAPI 3.1.0 para definiciones de esquema detalladas y ejemplos:

OpenAPI Spec →

Flujo de trabajo típico

Descubriendo agentes

Llame a GET /payment-agents/v1/agent-statistics para encontrar qué monedas y países se atienden.
Liste agentes para una moneda con GET /payment-agents/v1/agents, opcionalmente filtrado por país. Los resultados están paginados; use page y per_page para navegar por ellos.
Obtenga el perfil completo de un solo agente con GET /payment-agents/v1/agents/{id}.

Retiro de cliente

Solicite un código de un solo uso a través de POST /payment-agents/v1/withdraw/verification_code. El código se envía al correo electrónico o teléfono registrado del cliente y es válido hasta que expire.
Envíe el retiro con el código de 6 dígitos a través de POST /payment-agents/v1/withdraw.
Si proporcionó un request_id, consulte GET /payment-agents/v1/withdraw/{request_id} hasta que el estado se estabilice.

Depósito de agente — un agente de pago autenticado deposita fondos directamente en el Wallet de un cliente con POST /payment-agents/v1/transfer (se completa de forma sincrónica).

Endpoints Disponibles

Listar Agentes de PagoGet

Devuelve una lista paginada de agentes de pago activos que admiten la moneda solicitada. Los resultados incluyen agentes listados públicamente, además de cualquier agente del que haya recibido previamente una transferencia incluso si ese agente no está listado públicamente. Un filtro de país opcional restringe aún más a los agentes que prestan servicio en ese país. Cada resultado incluye el perfil del agente y sus tarifas de comisión para la moneda solicitada./payment-agents/v1/agents

Obtener Agente de PagoGet

Devuelve el perfil completo de un solo agente de pago, incluidos los agentes no listados públicamente en el directorio. Use esto cuando ya tenga el id de un agente y necesite sus detalles completos. La respuesta siempre incluye un array de currencies con las tarifas de comisión del agente y los límites de retiro para cada moneda admitida, y un array de urls con los sitios web asociados del agente (null si el agente no tiene ninguno registrado). Pase me como id para devolver el propio perfil de agente del cliente autenticado./payment-agents/v1/agents/{id}

Estadísticas del Agente de PagoGet

Devuelve el conjunto agregado de países y monedas cubiertos por al menos un agente de pago activo y listado públicamente. Use esto para determinar qué valores de filtro de moneda y país son significativos antes de llamar a la lista de agentes - los resultados pueden retrasarse respecto a los agentes recientemente incorporados por un breve período./payment-agents/v1/agent-statistics

Configuración del ClienteGet

Devuelve la configuración actual de agente de pago del cliente autenticado: si puede recibir depósitos de agentes de pago, si puede retirar fondos a través de un agente de pago y si su nombre real se comparte con los agentes en las transacciones. Los clientes que nunca han utilizado un agente de pago ven los valores predeterminados deposit_enabled: true, withdraw_enabled: true y show_real_name: false./payment-agents/v1/clients/me

Actualizar la Configuración del ClientePatch

Actualiza la preferencia del cliente autenticado sobre si los agentes de pago pueden ver su nombre real en las transacciones. Establezca show_real_name en true para revelarlo o en false para ocultarlo; se devuelve la configuración actualizada. La primera interacción de un cliente con un agente de pago registra su cuenta, por lo que algunos errores 400 y 500 solo ocurren en esa primera llamada./payment-agents/v1/clients/me

Transferencia (Depósito)Post

Permite que un agente de pago autenticado deposite fondos directamente en la Wallet de Deriv de un cliente, identificado por su apodo de cuenta (to_nickname). En caso de éxito, devuelve un TransferResult: estado "complete" con un transaction_id para una transferencia real, estado "pending" con transaction_id nulo si la transferencia aún está siendo procesada (consulte GET /payment-agents/v1/transfer/{request_id} con el request_id proporcionado para el estado final), o estado "dry_run_ok" con transaction_id nulo cuando dry_run es verdadero. client_real_name y client_is_agent describen al destinatario./payment-agents/v1/transfer

Estado de la transferenciaGet

Devuelve el estado actual de una transferencia iniciada previamente con un request_id. Tanto el agente de pago que envió la transferencia como el cliente receptor pueden verificarlo. La mayoría de las transferencias devuelven el estado completo en la respuesta inicial y no requieren sondeo; si el estado inicial está pendiente, progresa a completo, rechazado o fallido. Un request_id que no coincide con ninguna de sus transferencias devuelve RequestIDNotFound./payment-agents/v1/transfer/{request_id}

Código de Verificación de RetiroPost

Solicita que se envíe un código de verificación de un solo uso al contacto registrado del cliente (correo electrónico o teléfono). Llame a este endpoint antes de enviar un retiro mediante POST /payment-agents/v1/withdraw — el código debe incluirse como verification_code en esa solicitud. El código es válido hasta expires_at (segundos epoch). No se puede solicitar un nuevo código antes de next_request_at (segundos epoch). Las mismas verificaciones de elegibilidad del agente y de reglas de negocio que protegen POST /payment-agents/v1/withdraw también se ejecutan aquí — si esta solicitud tiene éxito, el retiro posterior no fallará en dichas verificaciones. Consulte la respuesta 400 para obtener la lista completa de códigos de error./payment-agents/v1/withdraw/verification_code

RetirarPost

Retira fondos de la cuenta del cliente autenticado a través de un agente de pago. El retiro traslada el monto solicitado fuera del Wallet del cliente y al Wallet del agente; el agente luego liquida el valor equivalente con el cliente fuera de Deriv. Requiere un verification_code de 6 dígitos obtenido mediante POST /payment-agents/v1/withdraw/verification_code. Los retiros comienzan como pendientes y pasan a completados, rechazados o fallidos. Proporcione un request_id opcional para rastrear el estado posteriormente a través de GET /payment-agents/v1/withdraw/{request_id}./payment-agents/v1/withdraw

Estado del retiroGet

Devuelve el estado actual de un retiro previamente enviado con un request_id. Tanto el cliente que inició el retiro como el agente de pago pueden consultar este endpoint. El estado avanza de pendiente a completado, rechazado o fallido. Un request_id que no coincida con ninguno de sus retiros devuelve RequestIDNotFound./payment-agents/v1/withdraw/{request_id}

Autentificación

Todos los endpoints requieren el encabezado Deriv-App-ID y un encabezado Authorization: Bearer YOUR_OAUTH_TOKEN. El token debe tener el alcance payment; de lo contrario, la API devuelve 403 Forbidden.

Alcances de OAuth2

Endpoint	Alcance
`GET /payment-agents/v1/agents`	`payment`
`GET /payment-agents/v1/agents/{id}`	`payment`
`GET /payment-agents/v1/agent-statistics`	`payment`
`POST /payment-agents/v1/transfer`	`payment`
`POST /.../withdraw/verification_code`	`payment`
`POST /payment-agents/v1/withdraw`	`payment`
`GET /.../withdraw/{request_id}`	`payment`

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 de respuesta

La API utiliza códigos de estado HTTP estándar para indicar éxito o fallo:

2xx Éxito

200 OK — Solicitud exitosa

Errores 4xx/5xx

400 Bad Request — Parámetros no válidos o fallo de regla de negocio

401 Unauthorized — Autenticación no válida o faltante

403 Forbidden — El token carece del alcance payment

404 Not Found — Agente no encontrado

500 Internal Server Error — Error del lado del servidor

504 Gateway Timeout — Tiempo de espera del servicio upstream

No todos los códigos se aplican a cada endpoint. 404 Not Found se aplica solo a GET /payment-agents/v1/agents/{id}, y GET /payment-agents/v1/agent-statistics no devuelve 400.

Formato de respuesta de error

Todas las respuestas de error siguen un formato consistente con un objeto data vacío, un array errors y 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}

Los códigos de error incluyen: 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

Extracto Listar Agentes de Pago

¿Alguna otra pregunta? Póngase en contacto