Payout a cuenta bancaria

Un payout saca dinero de la plataforma hacia el mundo. Es siempre asíncrono: la respuesta no dice "salió" — dice "reservado y avanzando".

1. Crear

curl -X POST https://api.tikin.is/v1/payouts \
  -H "Authorization: Bearer tk_live_…" \
  -H "Idempotency-Key: $(uuidgen | tr 'A-Z' 'a-z')" \
  -H "Content-Type: application/json" \
  -d '{
    "source_account": "7b0d0f52-3f3e-4bf0-9d5a-111111111111",
    "destination": {
      "type": "bank_account",
      "bank": "bancolombia",
      "account_number": "03612345678",
      "account_kind": "savings",
      "holder": {
        "name": "María Fernanda Rojas",
        "document": { "type": "CC", "number": "1017654321" }
      }
    },
    "amount": { "raw": "50000000", "asset": "COPM" }
  }'

amount es lo que RECIBE el beneficiario ($500.000); la comisión se suma aparte y la respuesta la desglosa en fee. 201:

{ "id": "…", "status": "received", "amount": { "raw": "50000000", "asset": "COPM" },
  "fee": { "raw": "290000", "asset": "COPM" }, "destination_type": "bank_account" }

Desde este instante neto + fee quedan retenidos (held en el saldo): no hay doble gasto mientras el payout avanza, y la reserva se libera ENTERA si se rechaza — la comisión jamás se cobra por un payout que no ocurrió.

2. Seguir los estados

received → approved → in_progress → completed, con rejected / failed / returned como desvíos. Por polling:

curl https://api.tikin.is/v1/payouts/{payout_id} \
  -H "Authorization: Bearer tk_live_…"

…o por los eventos payout.completed / payout.failed / payout.returned (webhooks). Haz las dos: el webhook avisa, el polling es la verdad cuando el webhook no llegó.

3. El returned — el que nadie programa

Un banco puede rechazar DESPUÉS de que el payout quedó completed (cuenta cerrada, titular no coincide — pasa en la vida real). Eso llega como returned: el dinero vuelve al saldo de la cuenta origen.

Tu integración tiene que soportar que un payout "terminado" cambie de estado días después: no congeles el registro al ver completed, y concilia contra los movimientos — el related de cada movimiento apunta al payout que lo causó. Si tu sistema le pagó a María y el payout volvió, alguien tiene que enterarse: failure_reason dice por qué.