Split Payments API

Base URL:


https://api.talo.com.ar/split

Sandbox:


https://sandbox-api.talo.com.ar/split

Todos los ejemplos usan:


Authorization: Bearer <talo_token>
Content-Type: application/json

Payout accounts

Crear payout accounts


POST /split/accounts

El body siempre contiene una lista, incluso cuando sólo se registra una cuenta:


{
  "accounts": [
    {
      "account_id": "seller_123",
      "address": "talo.destino.ejemplo",
      "metadata": { "seller_id": "seller_123" }
    }
  ]
}

Ejemplo:


curl -X POST https://sandbox-api.talo.com.ar/split/accounts \
  -H "Authorization: Bearer $TALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "accounts": [
      {
        "account_id": "seller_123",
        "address": "talo.destino.ejemplo",
        "metadata": { "seller_id": "seller_123" }
      }
    ]
  }'

Respuesta:


{
  "data": {
    "verification_request": {
      "request_id": "svr_01J...",
      "exp_timestamp": "2026-08-16T12:10:00.000Z"
    },
    "accounts": [
      {
        "account_id": "seller_123",
        "address": "talo.destino.ejemplo",
        "status": "pending_verification",
        "metadata": { "seller_id": "seller_123" },
        "created_at": "2026-08-16T12:00:00.000Z"
      }
    ]
  }
}

Cada account_id identifica el destino dentro de tu cuenta/partner y debe ser único. Ese mismo identificador se usa para consultar o deshabilitar la cuenta y para referenciarla en los payouts. Cada dirección se valida y queda registrada como pending_verification. Sólo una cuenta active, después de completar la verificación 2FA, puede utilizarse para recibir payouts.

Listar payout accounts


GET /split/accounts

La respuesta contiene únicamente las cuentas del usuario autenticado.

Respuesta:


{
  "data": {
    "accounts": [
      {
        "account_id": "seller_123",
        "address": "talo.destino.ejemplo",
        "status": "active",
        "metadata": { "seller_id": "seller_123" },
        "created_at": "2026-08-16T12:00:00.000Z"
      }
    ]
  }
}

Consultar una payout account


GET /split/accounts/{account_id}

Respuesta:


{
  "data": {
    "account_id": "seller_123",
    "address": "talo.destino.ejemplo",
    "status": "active",
    "metadata": { "seller_id": "seller_123" },
    "created_at": "2026-08-16T12:00:00.000Z"
  }
}

Verificar payout accounts


POST /split/accounts/verifications

Body:


{
  "request_id": "svr_01J...",
  "code": "123456"
}

Si el desafío 2FA es válido y la solicitud no expiró, todas las cuentas asociadas al request_id pasan a active y pueden utilizarse en payouts. Una cuenta activa es inmutable: si necesitás cambiar la dirección, creá y verificá una nueva.

Respuesta:


{
  "data": {
    "request_id": "svr_01J...",
    "status": "verified",
    "accounts": [
      {
        "account_id": "seller_123",
        "address": "talo.destino.ejemplo",
        "status": "active",
        "metadata": { "seller_id": "seller_123" },
        "created_at": "2026-08-16T12:00:00.000Z"
      }
    ]
  }
}

Deshabilitar una payout account


PUT /split/accounts/{account_id}/status

Body:


{
  "status": "disabled"
}

La cuenta queda en estado disabled y no puede utilizarse para nuevos payouts. Esta acción es irreversible: una cuenta deshabilitada no puede volver a active. Si necesitás agregar nuevamente ese destino, creá y verificá una nueva payout account. Los payouts históricos no se modifican.

Respuesta:


{
  "data": {
    "account_id": "seller_123",
    "address": "talo.destino.ejemplo",
    "status": "disabled",
    "metadata": { "seller_id": "seller_123" },
    "created_at": "2026-08-16T12:00:00.000Z"
  }
}

Split payments

Crear un split payment


POST /split/payments

Body:

El body toma la misma estructura base que Crear un pago, con los campos que aplican a Split payments:

Campo	Tipo	Requerido	Descripción
`price.amount`	`number`	Sí	Monto de referencia esperado
`price.currency`	`string`	Sí	Moneda. En Beta: `ARS`
`external_id`	`string`	Sí	Identificador único de la orden dentro de tu cuenta/partner
`webhook_url`	`string`	No	URL donde Talo enviará eventos
`motive`	`string`	No	Motivo del pago
`client_data`	`object`	No	Datos del cliente
`tags`	`string[]`	No	Etiquetas para categorizar el pago

price.amount es un monto de referencia y no fija el importe final que se puede distribuir: los payouts se validan contra el saldo efectivamente acreditado. Los destinatarios no se envían al crear el split payment; se registran y verifican por separado antes de crear los payouts.

external_id debe ser único dentro de la cuenta/partner autenticado. No pueden existir dos split payments con la misma combinación de cuenta/partner y external_id. Si se repite el mismo external_id con los mismos datos, Talo devuelve el split payment existente; si se repite con datos diferentes, responde 409 Conflict.

Ejemplo:


curl -X POST https://sandbox-api.talo.com.ar/split/payments \
  -H "Authorization: Bearer $TALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "price": { "amount": 30000, "currency": "ARS" },
    "external_id": "order_123",
    "webhook_url": "https://merchant.example.com/talo/split-webhook"
  }'

Respuesta:


{
  "data": {
    "id": "sp_01J...",
    "payment_status": "PENDING",
    "quotes": [
      {
        "cvu": "0000000000000000000000",
        "alias": "talo.split.ejemplo"
      }
    ],
    "expiration_timestamp": "2026-08-21T12:00:00.000Z"
  }
}

La respuesta mantiene la misma estructura base de create payment. El cvu o alias dentro de quotes es la cuenta a la que se deben transferir los fondos. Para consultar el saldo recibido, el estado del split y los payouts, usá GET /split/payments/{split_payment_id}.

Listar split payments


GET /split/payments

Query params opcionales:

Parámetro	Tipo	Descripción
`payment_status`	`string`	Filtra por el estado de acreditación
`payout_status`	`string`	Filtra por el estado agregado de payouts
`external_id`	`string`	Filtra por el ID externo
`limit`	`integer`	Cantidad máxima de resultados
`cursor`	`string`	Cursor de paginación

Consultar un split payment


GET /split/payments/{split_payment_id}

Respuesta:


{
  "data": {
    "id": "sp_01J...",
    "payment_status": "SUCCESS",
    "payout_status": null,
    "currency": "ARS",
    "funding_address": {
      "cvu": "0000000000000000000000",
      "alias": "talo.split.ejemplo"
    },
    "received_amount": "100000.00",
    "allocated_amount": "75000.00",
    "available_amount": "100000.00",
    "hold_until": null,
    "external_id": "order_123",
    "metadata": { "order_id": "order_123" }
  }
}

payment_status usa los mismos estados que Payments API y describe únicamente la acreditación de fondos. payout_status es null hasta que se crea la única instrucción de payouts. available_amount es el saldo que todavía puede asignarse a payouts. El hold no comienza al recibir fondos: comienza cuando se acepta la instrucción de payouts.

Payouts

Crear payouts


POST /split/payments/{split_payment_id}/payouts

El body siempre contiene una lista, incluso para un único destinatario:


{
  "payouts": [
    {
      "account_id": "seller_123",
      "amount": "70000.00",
      "metadata": { "seller_id": "seller_123" }
    },
    {
      "account_id": "seller_456",
      "amount": "5000.00",
      "metadata": { "seller_id": "seller_456" }
    }
  ]
}

Reglas:

todas las cuentas deben pertenecer al usuario autenticado y estar active;
todos los importes deben usar la misma moneda del split payment;
la suma de los payouts no puede superar available_amount;
la suma se valida como una única instrucción lógica;
sólo se admite una instrucción de payouts por split_payment_id;
no se acepta una dirección bancaria directa en este endpoint;
una instrucción aceptada inicia el hold y queda retenida hasta hold_until;
el estado final debe confirmarse con GET o webhook.

Si se reintenta la misma instrucción después de un timeout, Talo devuelve la instrucción ya creada. Si se envía una lista diferente para el mismo split_payment_id, responde 409 Conflict.

Respuesta:


{
  "data": {
    "split_payment_id": "sp_01J...",
    "payment_status": "SUCCESS",
    "payout_status": "PENDING",
    "hold_until": "2026-08-17T00:00:00.000Z",
    "total_amount": "75000.00",
    "paid_amount": "0.00",
    "payouts": [
      {
        "id": "po_01J...",
        "account_id": "seller_123",
        "amount": "70000.00",
        "currency": "ARS",
        "status": "PENDING"
      },
      {
        "id": "po_01J...",
        "account_id": "seller_456",
        "amount": "5000.00",
        "currency": "ARS",
        "status": "PENDING"
      }
    ]
  }
}

Listar payouts de un split payment


GET /split/payments/{split_payment_id}/payouts

La respuesta devuelve el estado agregado de payouts, el hold, los totales y el array con el estado individual de cada payout. El estado agregado lo calcula Talo; no es necesario derivarlo a partir del array.


{
  "data": {
    "split_payment_id": "sp_01J...",
    "payout_status": "PENDING",
    "hold_until": "2026-08-17T00:00:00.000Z",
    "total_amount": "75000.00",
    "paid_amount": "0.00",
    "payouts": [
      {
        "id": "po_01J...",
        "account_id": "seller_123",
        "amount": "70000.00",
        "currency": "ARS",
        "status": "PENDING"
      }
    ]
  }
}

No existe un recurso público global /payouts: los payouts siempre se consultan dentro del split payment que los originó.

Estados

Split payment

Estado	Descripción
`PENDING`	El pago todavía no se resolvió
`SUCCESS`	Se acreditó el monto de referencia
`OVERPAID`	Se acreditó un monto superior al de referencia
`UNDERPAID`	Se acreditó un monto inferior al de referencia
`EXPIRED`	El CVU o el pago expiró por una regla operativa

EXPIRED no se usa porque todavía no se hayan creado payouts: los casos sin una instrucción de payouts quedan pendientes de resolución manual.

Estado agregado de payouts

Estado	Descripción
`null`	Todavía no existe una instrucción de payouts
`PENDING`	La instrucción fue aceptada y está dentro del hold de seguridad
`PROCESSING`	Talo inició la ejecución de los payouts
`SUCCESS`	Todos los payouts fueron confirmados
`PARTIAL_SUCCESS`	Algunos payouts fueron confirmados y otros requieren atención
`FAILED`	Ningún payout pudo completarse
`CANCELLED`	La instrucción fue cancelada por una acción operativa autorizada
`MANUAL_REVIEW`	El caso requiere intervención manual

Estado individual de un payout

Estado	Descripción
`PENDING`	Aceptado, pero retenido por el buffer de seguridad
`PROCESSING`	Talo inició la transferencia
`SUCCESS`	La transferencia fue confirmada
`FAILED`	La transferencia no pudo completarse
`CANCELLED`	Cancelado por una acción operativa autorizada

Un payout FAILED no se reintenta automáticamente sin una nueva decisión operativa. El saldo se mantiene en el split payment o pasa a MANUAL_REVIEW, según el caso.

Errores frecuentes

HTTP	Código	Cuándo ocurre
`401`	`unauthorized`	Falta el Bearer token o es inválido
`403`	`forbidden`	El token no puede operar el recurso solicitado
`404`	`split_payment.not_found`	El recurso no pertenece a la cuenta o no existe
`409`	`external_id_already_exists`	Ya existe un split payment con ese `external_id` y el payload es diferente
`409`	`payouts_already_created`	Ya existe una instrucción de payouts para el split payment
`409`	`account.not_active`	La payout account no está verificada o fue deshabilitada
`409`	`payout.insufficient_balance`	El total solicitado supera el saldo disponible
`422`	`validation_error`	El body no cumple el contrato
`423`	`split_payment.frozen`	El split payment está bloqueado por riesgo u operación