Primer payout - Zopay Connect

Flujo mínimo del contrato de payouts (campos alineados con los tests del API). La implementación actual usa el sandbox de payouts: respuestas reales de forma y esquema, sin movimiento de fondos en producción.

Prerrequisitos

Clave Connect (sk_test_ o sk_live_).
Organización aprobada en Connect.
Un external_ref que el API ya conozca para tu usuario (si no existe, la cotización puede responder external_ref_unknown).

1. Cotización

POST /connect/v1/payouts/quote requiere Idempotency-Key y este cuerpo (ejemplo usado en tests):

curl -X POST "https://api.zopay.cash/connect/v1/payouts/quote" \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "external_ref": "user_abc_123",
    "destination": "TRX1234567890ABCDEFGHIJKL",
    "asset": "USDT",
    "amount": "100.00"
  }'

La respuesta incluye al menos: quote_id (prefijo qt_pay_), expires_at, user_sends, recipient_gets, fee_total_usd, route (con type, from_network, to_network, estimated_seconds). El campo recommendation es opcional.

2. Ejecución

Dentro de la validez de la cotización, ejecuta con solo el quote_id:

curl -X POST "https://api.zopay.cash/connect/v1/payouts" \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "quote_id": "qt_pay_..."
  }'

Sustituye qt_pay_... por el quote_id devuelto en el paso 1. Cada ejecución debe usar una nueva Idempotency-Key; reutiliza la misma clave solo al reintentar la misma petición tras un fallo de red.

3. Consultar estado

curl -X GET "https://api.zopay.cash/connect/v1/payouts/{payout_id}" \
  -H "Authorization: Bearer sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Notas

Sin Idempotency-Key en quote o execute → idempotency_key_required (400).
Cuenta no aprobada → account_pending_approval (403).
Más reglas en Idempotencia y Payouts.