Crear un payout
Saca dinero de una cuenta hacia el mundo. Siempre asíncrono: amount + fee
quedan reservados al instante y el payout avanza:
received → approved → in_progress → completed, con rejected / failed /
returned / canceled. Si se rechaza o cancela, la reserva se libera ENTERA —
la comisión jamás se cobra por un payout que no ocurrió. Un rechazo del banco
DESPUÉS de completado llega como returned.
El destination nombra la CAPACIDAD: bank_account o cash_pickup (la
respuesta trae código e instrucciones para el beneficiario).
El beneficiario viaja en destination.holder, y ahí va también su
country (ISO 3166-1 alpha-2): es lo que el screening de cumplimiento
evalúa antes de soltar la plata. Es opcional y sin él se asume CO — hoy Tikin
paga únicamente en Colombia — pero mandarlo es lo correcto si tu beneficiario
no reside en Colombia. Un país mal escrito se rechaza con 400 invalid_field,
no se corrige por su cuenta.
Variante del producto Tikin: X-Product-Session: true selecciona la sesión de usuario y exige Tenant, Account y Pin. El servidor valida JWT/PIN y pertenencia de la cuenta en Auth. source_account debe coincidir con Account; source_wallet y destination_id deben pertenecer a esa cuenta activa y verificada. debit_amount es el DÉBITO TOTAL bruto en centavos COPM como texto; amount en la respuesta sigue siendo el neto recibido. Esta variante no acepta cash_pickup.
recipient_country es sólo el país que la persona declaró para el titular del destino. Si se omite no se deduce del banco ni se aplica un default; Rails puede retener por falta de datos AML. Conserva la misma Idempotency-Key al reintentar, incluso después de un timeout. Una configuración futura cuyas tarifas brutas/netas sean incompatibles devuelve 503 antes de la reserva.
Tu token de tenant: tk_live_…. El entorno sandbox llega pronto; los tokens tk_test_ quedarán reservados para él. Scopes: read, lookup, transfers, bonuses, payouts, webhooks. Usa el mínimo.
In: header
Header Parameters
La versión del contrato a la que anclas este pedido, como fecha YYYY-MM-DD. Rige la última publicada en o antes de esa fecha; sin el header, la más reciente.
dateUUID tuyo. Reintentar con la misma llave es el MISMO pedido (200 en vez de 201, y la respuesta trae el header Idempotent-Replay: true para que tu observabilidad distinga el replay del original); la misma llave con otro cuerpo — bytes de archivos incluidos — es 409.
uuidtrue selecciona el contrato del producto; no es una credencial.
Value in
- "true"
Obligatorio en la variante del producto.
Value in
- "tikin"
- "beu"
Obligatorio en la variante del producto.
uuidObligatorio en la variante del producto.
^\d{4,8}$Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/payouts" \ -H "Idempotency-Key: 497f6eca-6276-4993-bfeb-53cbbbba6f08" \ -H "Content-Type: application/json" \ -d '{ "source_account": "0b96a69a-83bf-4bb3-9b52-1bfb05c01fa0", "destination": { "type": "bank_account", "bank": "string", "account_number": "string", "account_kind": "savings", "holder": { "name": "string", "document": { "type": "string", "number": "string" } } }, "amount": { "raw": "string", "asset": "COPM" } }'{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "status": "received", "source_account": "0b96a69a-83bf-4bb3-9b52-1bfb05c01fa0", "destination_type": "bank_account", "destination_summary": { "bank": "string", "account_number_masked": "string", "holder_name": "string" }, "amount": { "raw": "string", "asset": "COPM" }, "fee": { "raw": "string", "asset": "COPM" }, "pickup": { "code": "string", "instructions": "string", "expires_at": "2019-08-24T14:15:22Z" }, "failure_reason": "string", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z"}