Split de Cobro

En algunos modelos de negocio, el dinero de cada pago recibido se tiene que dividir entre dos o más participantes.

En esta guía te mostramos cómo automatizar esa división entre Cuentas PAGOS360 con nuestra API. Usamos como ejemplo el modelo de marketplace, donde el dinero de cada venta se divide entre el vendedor y la plataforma.

Conceptos iniciales

Antes del paso a paso técnico, repasemos cómo se divide un pago recibido.

Hay diferentes estrategias para dividir un pago:

• Un importe, dos pagos. El total se reparte en dos cobros independientes. Cada participante crea su propia Solicitud de Pago por su parte, y el comprador paga cada una por separado. No es una función de PAGOS360: son dos Solicitudes de Pago comunes, cada una creada con la API Key de su cuenta. El comprador paga dos veces, y vos tenés que resolver el caso en que pague solo una.

• Un importe, un pago, una transferencia. El comprador paga una sola vez el total en una cuenta, y después una parte de ese dinero se transfiere a otra cuenta. Esta es la estrategia que implementa el Split de Cobro.

El Split de Cobro es una función que genera automáticamente una Transferencia Programada de una Cuenta PAGOS360 a otra en el momento en que se paga una Solicitud de Pago.

En esta guía vamos a usar estos nombres:

Tené en cuenta que:

• Las Transferencias Programadas funcionan solo entre Cuentas PAGOS360 conectadas.

• El split se define al crear la Solicitud de Pago. El importe que se transfiere es un monto fijo (no un porcentaje).

• La suma de lo que se transfiere no puede superar un porcentaje máximo del importe de la solicitud, que define PAGOS360 (ver el paso 2).

Diagrama del flujo

En el ejemplo del marketplace, la venta se cobra en la cuenta del vendedor (cuenta origen) y la comisión de la plataforma se transfiere a la cuenta del marketplace (cuenta destino).

1. Conectar las cuentas

Para conectar las cuentas, contactá a tu ejecutivo de cuenta o a Soporte. La conexión la configura el equipo de PAGOS360 a pedido: hoy no se puede hacer desde la API.

Cuando PAGOS360 habilita una cuenta como destino de Split de Cobro:

1. Se genera un Marketplace Secret para esa cuenta.

2. Se habilita el canal Transferencia Programada en su cuadro tarifario.

Para crear solicitudes con split, la cuenta origen necesita dos datos de la cuenta destino:

La cuenta destino tiene que estar activa. Si no está habilitada, no tiene Marketplace Secret o el secret no coincide, la API rechaza la solicitud (ver Errores frecuentes, más abajo).

2. Crear una Solicitud de Pago con split

El split se crea junto con la Solicitud de Pago, con un POST a /payment-request desde el backend de la cuenta origen. Además de los atributos habituales (Crear solicitud de pago), tenés que enviar:

• El atributo transfer_to dentro de payment_request, con una lista de transferencias.

• Un header X-Connect-Account por cada cuenta destino, para autorizar la transferencia.

El atributo transfer_to

transfer_to es un array de objetos. Cada objeto es una Transferencia Programada:

Tope del split: la suma de los amount de transfer_to no puede superar un porcentaje de first_total. Ese porcentaje lo define PAGOS360 (el valor por defecto es 50%). El tope se calcula siempre sobre first_total, aunque la solicitud tenga segundo vencimiento.

El header X-Connect-Account

Por cada cuenta destino, enviá un header con este formato:

• Podés enviar hasta 5 cuentas destino con los headers X-Connect-Account, X-Connect-Account-1, X-Connect-Account-2, X-Connect-Account-3 y X-Connect-Account-4.

• Cada account_id de transfer_to tiene que tener su header, y cada header tiene que corresponder a un account_id de transfer_to.

• Usá un valor distinto en cada header.

Ejemplo con curl

En este ejemplo, el vendedor cobra una venta de $10.000 y le transfiere $1.000 de comisión al marketplace:

En este ejemplo, <API Key> es la API Key de la cuenta origen (la del vendedor), y 1A2B3C4D y <Marketplace Secret> son los datos de la cuenta destino (la del marketplace).

Respuesta

Si la solicitud se crea correctamente, la API responde 201 Created. La respuesta incluye transfer_to tal como lo enviaste (respuesta recortada):

A partir de acá, el cobro sigue el flujo habitual: llevás al comprador al checkout_url (ver la guía de Botón de Pago Dinámico).

3. Qué pasa cuando se paga

Cuando se acredita el pago de la Solicitud de Pago, PAGOS360 procesa el split de forma asincrónica (en segundo plano). Por cada elemento de transfer_to:

1. En la cuenta destino se crea una nueva Solicitud de Pago, ya en estado paid, por el importe de amount. Esa solicitud tiene:

   • description: Pago en cuenta conectada <nombre de la cuenta origen> (ID <id de la solicitud original>). Concepto: <description>.

   • external_reference: el de transfer_to o, si no lo enviaste, el de la solicitud original.

   • payer_name: el nombre de la cuenta origen.

2. En la cuenta origen se registra la Transferencia Programada, que descuenta amount de su saldo. En el historial de movimientos figura como Transferencia Programada a <nombre de la cuenta destino> (<ID de cuenta destino>).

En los pagos con medios en efectivo o por archivo de rendición (por ejemplo Rapipago, Pago Fácil o débito en CBU), el split se genera cuando PAGOS360 procesa la rendición del medio de pago, es decir, el informe con los cobros que ese medio recibió.

Estados de la Transferencia Programada

La transferencia pasa a transferred cuando el cobro de la cuenta origen queda disponible, según los plazos de acreditación del medio de pago con el que se pagó.

Comisiones

• La cuenta origen paga la comisión del cobro según su cuadro tarifario, calculada sobre el importe total pagado. La transferencia no tiene una comisión adicional para la cuenta origen.

• La cuenta destino recibe el dinero como un cobro por el canal Transferencia Programada, al que se le aplican las condiciones de su propio cuadro tarifario para ese canal.

Devoluciones y contracargos

Si se devuelve el pago original o el comprador desconoce el cargo (contracargo), lo que pasa con la transferencia depende de refundable:

La reversión solo se aplica si la solicitud de la cuenta destino todavía está en estado paid.

4. Webhooks y consultas

Cada cuenta recibe los webhooks en la URL que tiene configurada (Webhooks):

Ejemplo del webhook que recibe la cuenta destino:

Para consultar el detalle, cada cuenta usa GET /payment-request/{id} con su propia API Key (Consultar solicitud de pago):

• La cuenta origen consulta la solicitud original. La respuesta incluye transfer_to con las transferencias que pediste.

• La cuenta destino consulta la solicitud generada por el split, con el id que recibe en el webhook.

La API pública no tiene hoy un endpoint para consultar el estado de una Transferencia Programada (pending, transferred o refunded).

Errores frecuentes

Si falla la validación, la API responde 400 Bad Request.

Los errores de headers llegan con este formato:

Si falta account_id, amount o description, o si amount es 0 o negativo, la API devuelve un error de validación sobre transfer_to.