Split Payments Webhooks

Talo envía un webhook a webhook_url cuando cambia el estado de un split payment o de sus payouts. El formato es el mismo que usa Payments API: un payload mínimo con message, splitPaymentId y externalId.

El webhook es una notificación, no la fuente de verdad. Respondé rápido y consultá GET /split/payments/{splitPaymentId} antes de actualizar el estado de tu orden.

Payload


{
  "message": "Pago Actualizado",
  "splitPaymentId": "sp_01J...",
  "externalId": "order_123"
}

splitPaymentId contiene el identificador del split payment. externalId contiene el external_id enviado al crear el split payment.

Cuándo se envía

Situación	Payload
Se acredita una transferencia al CVU dedicado	`message: "Pago Actualizado"`
Termina el hold y los payouts pueden ejecutarse	`message: "Pago Actualizado"`
Cambia el estado de un payout	`message: "Pago Actualizado"`
Talo requiere resolver el caso manualmente	`message: "Pago Actualizado"`

El webhook no incluye montos ni estados. Después de recibirlo, consultá:


GET /split/payments/{splitPaymentId}

Reintentos y deduplicación

Respondé 2xx sólo cuando hayas guardado el evento o puesto su ID en una cola.
Si respondés 4xx o 5xx, Talo puede reenviar el evento.
El mismo webhook puede llegar más de una vez y un mismo splitPaymentId puede generar varias notificaciones: procesá el handler de forma idempotente y consultá el estado actual antes de aplicar cambios.
Procesá los eventos fuera de orden consultando el recurso actual antes de aplicar una transición.
No uses el webhook para calcular balances: usá los importes y estados de la API.

Verificación del evento

Guardá el payload recibido y validá que splitPaymentId corresponda a un recurso de tu cuenta. El contrato de firma criptográfica para webhooks de Split payments se incorporará antes de General Availability; mientras tanto, usá una URL no pública o un secreto adicional en la URL y tratá cualquier evento no reconocido como no confiable.

Ejemplo de handler


app.post("/talo/split-webhook", async (req, res) => {
	const event = req.body
 
	// 1. Validar estructura y guardar event.splitPaymentId.
	// 2. Encolar el evento.
	// 3. Responder rápido.
	res.sendStatus(200)
})

Después, consultá el estado canónico:


curl https://sandbox-api.talo.com.ar/split/payments/sp_01J... \
  -H "Authorization: Bearer $TALO_TOKEN"