Obtener

Clave de API: Payout

Devuelve el estado actual de un retiro. El tx_hash confirmado y la explorer_url aparecen en cuanto el envío llega a completed.

Respuesta (200 OK)

{
  "withdrawal_id": "wdr_2M8K6Q4P9X1Z7A3B",
  "external_order_id": "payout-001",
  "status": "completed",
  "is_final": true,
  "is_test": false,
  "amount": "100.00",
  "fee": "1.00",
  "currency": "USDT",
  "network": "TRC20",
  "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "tx_hash": "9f3b8c2a1d0e4f6789abc123def4567890abc123def4567890abc123def45678",
  "explorer_url": "https://tronscan.org/#/transaction/9f3b8c2a1d0e4f6789abc123def4567890abc123def4567890abc123def45678",
  "created_at": 1739289600,
  "completed_at": 1739289932
}

Estados del retiro

Estado	Descripción	Final
created	Retiro creado, a la espera de la firma	No
signed	Transacción firmada y difundida a la blockchain	No
cancelling	Un administrador lanzó una cancelación estando en pending_review; se espera la confirmación en cadena para saber qué transacción cuaja	No
completed	Transacción confirmada en cadena, envío entregado. Es final en el contrato (is_final: true), aunque una reorganización profunda puede devolverlo a signed; mira las transiciones de más abajo	Sí
failed	La firma falló antes de la difusión, un operador abandonó un envío atascado o se confirmó en cadena una cancelación. Los fondos vuelven al saldo	Sí
cancelled	El comercio canceló mientras el estado seguía en created	Sí
pending_review	La transacción se firmó, pero no se encontró en cadena tras vencer el TTL. Requiere resolución manual	No

Transiciones de estado

• created -> signed -- transacción firmada y difundida
• created -> cancelled -- el comercio cancela (única transición válida al cancelar)
• created -> failed -- la firma falló
• created -> completed -- el comercio simula la finalización con POST /v1/sandbox/withdrawals/{id}/simulate-completion (solo en Sandbox: sin firma y sin cadena)
• signed -> completed -- transacción confirmada en cadena
• signed -> pending_review -- la transacción firmada no aparece en cadena (o se revirtió) al vencer el TTL; una transacción revertida sigue en signed hasta que el TTL la escala
• pending_review -> cancelling -- un administrador lanza la cancelación
• pending_review -> completed -- la transacción original aparece en cadena y confirma (lo detecta el escáner, no es una acción del administrador)
• pending_review -> failed -- un administrador abandona el envío atascado
• cancelling -> completed -- la transacción original confirmó primero, así que el envío salió adelante
• cancelling -> failed -- en su lugar confirmó en cadena la transacción de cancelación; los fondos vuelven al saldo
• completed -> signed -- poco frecuente: una reorganización de la cadena desplazó la transacción confirmada del envío, así que el retiro vuelve a signed y se completa de nuevo cuando esa transacción (o su sustituta) entra en un bloque

Errores

Consulta Códigos de error para el catálogo completo. La URI de type en cada respuesta de error enlaza directamente con la fila correspondiente.