Obtener

Clave de API: Payout

Devuelve el estado actual de un retiro. tx_hash y explorer_url se rellenan en cuanto hay una transacción en cadena bajo seguimiento, es decir antes de completed. Lo que indica que el envío terminó es status e is_final, no la presencia del hash.

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	El retiro está creado y todavía no ha salido a la red	No
signed	La transacción está firmada y enviada a la blockchain	No
cancelling	El retiro se está cancelando; cómo acaba lo dirá el siguiente estado	No
completed	La transacción está confirmada en cadena y el dinero, entregado	Sí
failed	El retiro no llegó a salir. El importe volvió al saldo	Sí
cancelled	El comercio canceló el retiro y no salió. El importe volvió al saldo	Sí
pending_review	La transacción aún no está confirmada en la red y el importe sigue retenido. En el panel este estado aparece como «Sin confirmar»	No

Cómo leer esto desde el código

Hay tres estados finales: completed, failed y cancelled. Cada respuesta y cada webhook llevan el campo is_final; ramifica por él y no por una lista de nombres que tendrías que mantener tú.

Un retiro solo se puede cancelar mientras está en created. Después, la petición de cancelación se rechaza; ver Cancelar un retiro. El motivo por el que un retiro no salió no lo devuelve la API: failed tiene estado, pero no un campo que lo explique.

En sandbox, POST /v1/sandbox/withdrawals/{id}/simulate-completion lleva un retiro de created a completed, sin firma y sin cadena.

Errores

Una clave Payment (pk_) se rechaza con 403 payout_key_required. 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.