Split payments (Beta)

Split payments permite recibir una o varias transferencias en un CVU dedicado y distribuir los fondos posteriormente mediante payouts.

Esta API está pensada para marketplaces, plataformas y otros casos en los que primero se recibe el dinero y luego se decide cómo distribuirlo.

Diagrama de flujo

El flujo tiene tres recursos:

1. Payout account: una cuenta bancaria whitelistada y verificada con 2FA.
2. Split payment: un CVU dedicado para recibir fondos. No requiere especificar dónde se hará el payout al momento de crearlo ya que se desconoce el monto final recibido.
3. Payout: una instrucción para distribuir una parte o todo el saldo recibido a una payout account.

Crear payout accounts ──> Verificar solicitud con 2FA

Crear split payment ──> Transferencia al CVU dedicado
                                  │
                                  ├── webhook de fondos recibidos
                                  │      + consulta del detalle
                                  │
                                  └── crear payouts
                                         │
                                         └── comienza hold de 12 horas
                                                │
                                                └── ejecutar payouts
                                                       + webhook de resultado

La transferencia recibida hace que Talo actualice el saldo y envíe el webhook. Cuando tu sistema crea la única instrucción de payouts, comienza el hold de seguridad de 12 horas. Pasado ese período, Talo ejecuta las instrucciones y envía el webhook de resultado.

Características principales

• Un CVU dedicado por split payment.
• Los destinatarios se eligen después de recibir los fondos.
• Cada payout referencia una cuenta whitelistada; no se aceptan direcciones libres en el payout.
• Los payouts se envían siempre como una lista, incluso cuando sólo existe un destinatario.
• Cada external_id identifica un único split payment dentro de la cuenta/partner autenticado.
• Cada split payment admite una única instrucción de payouts.
• El hold comienza cuando se acepta la instrucción de payouts y dura doce horas.
• El comercio recibe webhooks y debe consultar el recurso para obtener el estado canónico.

Autenticación

Todos los endpoints requieren un token Talo:

Authorization: Bearer <talo_token>

El usuario o partner dueño del token determina la cuenta Talo que se utiliza. No intentes operar recursos de otra cuenta.

Flujo recomendado

1. Pay-in

1.1 Creá el split payment

Usá POST /split/payments cuando necesites un nuevo CVU de recepción. La respuesta incluye el CVU y el alias que tenés que mostrar para que se realice la transferencia.

1.2 Recibí el webhook de acreditación

Cuando Talo detecta una transferencia, envía un webhook a webhook_url y deja hold_until en null. En ese momento podés consultar payment_status y el detalle de cuánto se acreditó con GET /split/payments/{split_payment_id}; payout_status todavía es null porque aún no existe una instrucción de payouts.

2. Payouts

2.1 Registrá las cuentas de destino

Podés crear las cuentas antes o después del pay-in, pero deben estar verificadas antes de crear los payouts. Usá POST /split/accounts, siempre enviando una lista aunque sólo necesites una cuenta. Talo devuelve una solicitud de verificación con request_id y exp_timestamp; usá esos datos para completar una única verificación 2FA para todas las cuentas del request.

2.2 Enviá la instrucción de payouts

Usá POST /split/payments/{split_payment_id}/payouts con una lista de cuentas verificadas. Talo valida el saldo disponible, crea la única instrucción de payouts y comienza el hold de 12 horas.

2.3 Esperá la ejecución después del hold

Pasado el hold de seguridad, Talo ejecuta los payouts y envía un webhook con el resultado. Consultá nuevamente payment_status, payout_status y el estado individual de cada payout antes de marcar una orden interna como distribuida.

Seguridad operativa

La combinación de whitelist, 2FA, unicidad de recursos y hold protege el punto más sensible: la salida de fondos.

• Una payout account activa no se modifica: para cambiar la dirección se crea otra cuenta y se verifica nuevamente.
• Deshabilitar una cuenta impide nuevos payouts, pero no altera el historial.
• Un payout aceptado inicia el hold y no se ejecuta antes de hold_until.
• La ejecución de un payout nunca debe considerarse exitosa sólo porque la API aceptó la instrucción: esperá payout_status: "SUCCESS", los estados individuales SUCCESS y el webhook correspondiente.