En resumen
Los pagos masivos por API requieren una cola con concurrencia limitada y reintentos con espera creciente. Cada solicitud POST /v1/withdrawals corresponde a un destinatario. Guarde un external_order_id por pago y conserve ese identificador y los mismos datos al reintentar. La cuota estándar de 30 peticiones por segundo se comparte entre todas las solicitudes de la cuenta; no mide transferencias completadas. El panel permite crear lotes manuales de hasta 50 destinatarios, con el mismo activo y red, solo en producción. La comisión de retiro de Paymos es del 0%; la tarifa de red subsidiada se muestra por separado.
Efectuar pagos y liquidaciones masivas en criptoactivos es un requisito clave para plataformas globales: redes de afiliación, portales de juego online, empresas tecnológicas y servicios de nómina internacional necesitan emitir cientos o miles de pagos por hora.
A diferencia del sistema bancario tradicional, las blockchains imponen consenso distribuido, orden secuencial de nonces y operaciones irreversibles. Un único fallo mal gestionado puede paralizar la cola completa.
El cuello de botella del Nonce en redes EVM
En redes basadas en Ethereum, las transacciones de una cuenta se ejecutan en orden de nonce (0, 1, 2...). Si una transacción queda pendiente, las posteriores de esa cuenta también pueden esperar. La frecuencia de solicitudes a la API no equivale al ritmo de transferencias completadas.
El patrón Transactional Outbox
Guarde la orden de pago junto con el cambio de saldo interno. Una única transacción de base de datos evita que una caída deje uno de los dos sin registrar. Un proceso de envío lee las órdenes pendientes y llama a la API con concurrencia limitada y reintentos con espera creciente. Ante un HTTP 429, respete Retry-After. Asigne y guarde un único external_order_id por pago antes de la primera solicitud, y reutilícelo con los mismos datos en cada reintento. Consulte nuestra guía sobre idempotencia de webhooks.
Despachadores multi-bóveda
El diseño de las billeteras afecta al envío en paralelo. La integración con Paymos no exige gestionar esa arquitectura: controle la cola de solicitudes y siga el estado de cada retiro. Consulte las medidas de custodia en nuestro artículo sobre seguridad de billeteras calientes.
Tarifas de red: subsidio de pagos y energía de TRON
La comisión de retiro de Paymos es del 0%. Usted paga solo la tarifa de red publicada de la ruta, y todas las rutas de pago están subsidiadas: paga menos de lo que cobra la cadena. Si un pago falla o se cancela, el importe reservado completo y la tarifa vuelven al saldo disponible.
En TRON, la energía y otros recursos de la red influyen en el coste de cada transferencia. Use la tarifa publicada de la ruta de pago elegida en lugar de suponer un coste fijo en dólares por envío. Consulte las tarifas en la página de precios de Paymos y el contexto en nuestro manual de alquiler de energía TRON.
Integración con la API REST para desarrolladores
Su backend envía un POST /v1/withdrawals autenticado por cada destinatario a través de la API REST Host-to-Host. Use una clave de pagos (rk_) con autenticación HMAC-SHA256; normalmente, las direcciones de destino deben estar en su lista blanca de retiros. Los valores de las cabeceras del ejemplo son marcadores de posición.
POST /v1/withdrawals HTTP/1.1
Host: api.paymos.io
Authorization: HMAC-SHA256 rk_live_<key_id>:<base64_signature>
X-Request-Timestamp: <current_unix_seconds>
Content-Type: application/json
{
"currency": "USDT",
"network": "TRC20",
"amount": "25.00",
"destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
"external_order_id": "payout_usr_101"
}
Al crearse, el retiro devuelve HTTP 201 Created con estado created; un reintento con el mismo external_order_id devuelve HTTP 200 OK y el retiro existente. Los importes y tarifas del ejemplo son ilustrativos y no constituyen un tarifario:
{
"withdrawal_id": "wdr_7K2M9P4Q8R1X5Z3A0bC2dE",
"external_order_id": "payout_usr_101",
"status": "created",
"is_final": false,
"is_test": false,
"amount": "25.00",
"fee": "0.50",
"currency": "USDT",
"network": "TRC20",
"destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
"created_at": 1739277600
}
La cuota estándar de 30 peticiones por segundo se comparte entre todas las llamadas a la API de la cuenta. Limite la concurrencia de sus procesos, espere cada vez más entre reintentos y respete Retry-After ante un HTTP 429; esta cuota no garantiza un ritmo de transferencias completadas. El panel del comercio también permite lotes manuales de hasta 50 destinatarios con el mismo activo y red, solo en producción.
Al completarse el pago, Paymos envía withdrawal.completed en el sobre versionado del webhook:
{
"event_id": "evt_CbYeOgBp9Kt2U3j74fxxLl",
"event_type": "withdrawal.completed",
"version": 1,
"occurred_at": 1739281200,
"data": {
"withdrawal_id": "wdr_7K2M9P4Q8R1X5Z3A0bC2dE",
"external_order_id": "payout_usr_101",
"status": "completed",
"is_final": true,
"is_test": false,
"amount": "25.00",
"fee": "0.50",
"currency": "USDT",
"network": "TRC20",
"destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
"tx_hash": "7f8a9b0c1d2e3f4a5b6c7d8e9f00112233445566778899aabbccddeeff001122",
"explorer_url": "https://tronscan.org/#/transaction/7f8a9b0c1d2e3f4a5b6c7d8e9f00112233445566778899aabbccddeeff001122",
"created_at": 1739277600,
"completed_at": 1739281200
}
}
Un pago fallido emite withdrawal.failed y una cancelación emite withdrawal.cancelled; en ambos casos, el importe reservado completo y la tarifa vuelven al saldo disponible. Verifique las firmas de los webhooks sobre el cuerpo original, descarte entregas duplicadas por event_id y aplique los cambios de negocio por data.withdrawal_id sin suponer un orden de entrega. Si llega withdrawal.completion_rewound, el retiro completado vuelve a signed; siga las actualizaciones posteriores.
Revise también el análisis de velocidad de retiros en criptomonedas.
| Patrón arquitectónico | Límite de envío | Gestión de la cola | Coste de red | Recomendado para |
|---|---|---|---|---|
| 1. Bucle secuencial RPC | Depende de la red y del nodo | A cargo de la integración | Depende de la red y sus recursos | Proyectos personales, pruebas internas |
| 2. Lotes manuales en panel | Hasta 50 destinatarios por lote, solo en producción | Mismo activo y red por lote | Tarifa de red subsidiada | Nóminas periódicas, pagos manuales a afiliados |
| 3. Outbox API automatizado (POST /v1/withdrawals) | Cuota estándar de 30 peticiones/s compartidas por cuenta | Un destinatario por solicitud; reintentos con el mismo external_order_id | Tarifa subsidiada y 0% de comisión Paymos | Exchanges, iGaming, prop firms, apps a gran escala |
Preguntas frecuentes
¿Por qué fallan los envíos secuenciales de criptomonedas a gran escala?
En las redes EVM, las transacciones de una misma dirección se ejecutan en orden de nonce. Si una queda pendiente, las posteriores de esa dirección también pueden esperar.
¿Cómo se previenen pagos duplicados si falla la conexión de red?
Guarde un external_order_id por pago. Si la solicitud expira, reinténtela con el mismo identificador y los mismos datos. La API devuelve el retiro existente sin crear otro. Un Transactional Outbox ayuda a conservar las órdenes pendientes ante una caída del servidor.
¿De qué forma reducen comisiones la automatización y los lotes?
La comisión de retiro de Paymos es del 0%. La tarifa de red subsidiada se muestra por separado y no tiene un importe fijo garantizado. Para envíos manuales, el panel permite lotes de hasta 50 destinatarios con el mismo activo y red, solo en producción.
¿Qué ocurre si una dirección destinataria está en listas negras de AML?
Antes de enrutar un retiro, Paymos revisa la dirección destinataria con TRM Labs, Binance AML, AMLBot, PureFi y la base de datos del proveedor de verificación. Si la dirección no supera la verificación, el retiro no se envía y pasa a failed. El importe reservado completo y la tarifa de red vuelven al saldo disponible del comercio.
Cuándo NO conviene usar APIs de pagos masivos en cripto
- Si unos pocos envíos manuales desde el panel cubren sus necesidades.
- Si liquida tokens NFT específicos que exigen acuerdos de custodia manual.
- Si su servidor no puede gestionar un Transactional Outbox con garantía de idempotencia.
- Si su política de cumplimiento exige que dos personas aprueben cada transacción saliente, sea cual sea el importe: Paymos no tiene una cadena de aprobación entre varias personas, así que constrúyala en su propio back office antes de llamar a la API.
Fuentes
Última revisión: 7 nov 2026


