Simular

Clave de API: Payment (Sandbox)

Solo en Sandbox. Lleva un reembolso existente de Sandbox (is_test: true) al estado terminal solicitado (completed, failed o cancelled), actualiza el saldo de Sandbox y emite el webhook withdrawal.completed, withdrawal.failed o withdrawal.cancelled con el contrato completo del reembolso.

Cuerpo de la petición

Parámetro	Tipo	Obligatorio	Descripción
status	string	Sí	Estado terminal de destino: "completed", "failed" o "cancelled"

{
  "status": "completed"
}

Respuesta (200 OK)

{
  "withdrawal_id": "wdr_6Qm2fK8xR4vN7cT1bY9dL5",
  "invoice_id": "inv_7K2M9P4Q8R1X5Z3A0bC2dE",
  "mode": "full",
  "external_order_id": "refund-1042-full",
  "status": "completed",
  "is_final": true,
  "is_test": false,
  "amount": "100.00",
  "fee": "1.00",
  "currency": "USDT",
  "network": "TRC20",
  "destination_address": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "first_sender": "TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9",
  "tx_hash": "9f3b8c2a1d0e4f6789abc123def4567890abc123def4567890abc123def45678",
  "explorer_url": "https://tronscan.org/#/transaction/9f3b8c2a1d0e4f6789abc123def4567890abc123def4567890abc123def45678",
  "created_at": 1767225600,
  "completed_at": 1767225932,
  "type": "refund",
  "project_id": "prj_3F9xL2mN8pQ4rT6vW1yZ5b"
}

Reglas

• —Crea primero el reembolso de Sandbox con POST /v1/refunds usando una clave Payment de Sandbox (pk_test_) y pasa después su withdrawal_id a este endpoint.
• —Llamar a simulate sobre un reembolso que ya está en el estado terminal solicitado es idempotente y devuelve 200 OK sin emitir un webhook duplicado.
• —Llamar a simulate con un estado terminal distinto cuando el reembolso ya es final devuelve 409 invalid_withdrawal_state.
• —Simular "completed" confirma el cargo del saldo reservado y asigna un tx_hash sintético. Simular "failed" o "cancelled" libera el importe reservado amount + fee de vuelta a tu saldo de Sandbox, permitiéndote crear un nuevo reembolso para la factura.

Errores

Código	HTTP	Cuándo ocurre
payment_key_required	403	La petición se firmó con una clave Payout (rk_)
refunds_not_enabled	503	Los reembolsos de facturas están deshabilitados en este entorno
withdrawal_not_found	404	El ID no existe, no es un reembolso de Sandbox o está fuera del alcance de proyectos de la clave
invalid_withdrawal_state	409	El reembolso ya se encuentra en otro estado terminal
field_invalid_enum	400	status no es "completed", "failed" ni "cancelled"

Consulta Pruebas para ver el flujo completo de Sandbox y Códigos de error para el catálogo completo.