División de Pago
Descripción General
La División de Pago le permite dividir automáticamente el valor de un PIX recibido (Cash-In) entre múltiples destinatarios. Cuando se confirma un pago, el sistema calcula la parte de cada destinatario y ejecuta las transferencias (PIX-OUT) automáticamente.
La división se configura al momento de crear el cobro (Cash-In o QR Code Estático). No es posible agregar splits a una transacción ya creada.
Casos de Uso
Marketplace
Divida automáticamente el pago entre el vendedor y la plataforma (comisión).
Asociaciones
Distribuya ingresos entre socios con porcentajes predefinidos.
Franquicias
Transferencia automática de regalías y tarifas al franquiciante.
Proveedores de Servicios
Transferencia automática al proveedor con retención de tarifa de la plataforma.
Cómo Funciona
Al generar un PIX Cash-In, incluya el array splits con los destinatarios y sus valores (fijos o porcentaje).
Cuando el pagador completa el PIX, se envía el webhook CashIn con estado CONFIRMED.
El sistema calcula el monto de cada destinatario (después de deducir tarifas) y crea los elementos de la división.
Dependiendo de la frecuencia configurada, los montos se envían automáticamente vía PIX a cada destinatario.
Por cada transferencia, se despacha un webhook CashOut con el resultado (éxito o fallo).
Tipos de Split
FIXED -- Valor Fijo
El destinatario recibe un monto fijo independientemente del valor total del pago.
{
"type": "FIXED",
"value": 10.00
}El valor está en BRL con hasta 2 decimales: 10.00 = R$ 10.00.
PERCENTAGE -- Porcentaje
El destinatario recibe un porcentaje del valor bruto del pago (antes de tarifas).
{
"type": "PERCENTAGE",
"value": 10
}El porcentaje se proporciona directamente: 10 = 10%, 25.5 = 25.5%.
Formato de Valores
Los valores de split usan el mismo formato que el campo transaction.value -- en BRL con hasta 2 decimales.
Valores Fijos (FIXED)
| Valor en BRL | Campo value |
|---|---|
| R$ 0.01 | 0.01 |
| R$ 1.00 | 1.00 |
| R$ 10.00 | 10.00 |
| R$ 100.00 | 100.00 |
| R$ 1,500.50 | 1500.50 |
Mínimo: 0.01
Porcentajes (PERCENTAGE)
| Porcentaje | Campo value |
|---|---|
| 1% | 1 |
| 5% | 5 |
| 10% | 10 |
| 25.5% | 25.5 |
| 33.33% | 33.33 |
| 50% | 50 |
El valor representa el porcentaje directamente. No se necesita multiplicación.
Frecuencias de Ejecución
La frecuencia determina cuándo se ejecutan los splits acumulados. Se configura por cuenta, no por transacción.
| Frecuencia | Comportamiento |
|---|---|
IMMEDIATE | Se ejecuta inmediatamente después de la confirmación del PIX-IN |
HOURLY | Se acumula y ejecuta cada hora |
DAILY | Se acumula y ejecuta una vez al día |
WEEKLY | Se acumula y ejecuta una vez por semana |
Cuando la frecuencia es DAILY o WEEKLY, los splits de múltiples transacciones para el mismo destinatario se agrupan en un solo PIX-OUT. Esto reduce los costos de transacción.
Campo immediate en el Split
El campo immediate en un split individual le permite sobrescribir la frecuencia de la cuenta para ese split específico:
{
"pixKey": "urgent@email.com",
"pixKeyType": "EMAIL",
"name": "Urgent Supplier",
"document": "12345678000199",
"type": "FIXED",
"value": 50.00,
"immediate": true
}Cuando immediate: true, el split se ejecuta inmediatamente después de la confirmación del PIX-IN, incluso si la cuenta está configurada con frecuencia DAILY.
Ejemplo Completo
Escenario: Marketplace con 3 destinatarios
Un marketplace recibe R$ 100.00 de un cliente. El valor debe dividirse:
- Vendedor: 70% del valor
- Plataforma: 20% del valor
- Repartidor: R$ 10.00 fijos
{
"transaction": {
"value": 100.00,
"description": "Order #12345 - Marketplace",
"externalId": "ORDER-12345",
"generateQrCode": true
},
"payer": {
"fullName": "Carlos Oliveira",
"document": "12345678901"
},
"splits": [
{
"pixKey": "seller@email.com",
"pixKeyType": "EMAIL",
"name": "John's Store",
"document": "98765432000188",
"type": "PERCENTAGE",
"value": 70,
"immediate": false
},
{
"pixKey": "platform@marketplace.com",
"pixKeyType": "EMAIL",
"name": "Marketplace Ltd",
"document": "11222333000144",
"type": "PERCENTAGE",
"value": 20,
"immediate": false
},
{
"pixKey": "12345678901",
"pixKeyType": "CPF",
"name": "Delivery Person Silva",
"document": "12345678901",
"type": "FIXED",
"value": 10.00,
"immediate": true
}
]
}Resultado después del pago (R$ 100.00 recibidos):
| Destinatario | Tipo | Cálculo | Valor |
|---|---|---|---|
| Vendedor | 70% | R$ 100.00 x 70% | R$ 70.00 |
| Plataforma | 20% | R$ 100.00 x 20% | R$ 20.00 |
| Repartidor | Fijo | R$ 10.00 | R$ 10.00 |
| Total | R$ 100.00 |
Cuando hay tarifas de la plataforma (fee), el cálculo de porcentaje se basa en el valor bruto (antes de tarifas). Las tarifas se deducen del monto restante después de los splits.
Límites y Restricciones
| Restricción | Valor |
|---|---|
| Máximo de destinatarios por transacción | 10 |
| Valor mínimo por split (FIXED) | 0.01 (R$ 0.01) |
| Porcentaje mínimo por split | 0.01 (0.01%) |
| Máximo de decimales | 2 |
| Suma de splits | No puede exceder el valor de la transacción |
Si la suma de los splits fijos + porcentajes del valor bruto + tarifas excede el valor de la transacción, la API retornará error 400 Bad Request.
QR Code Estático Sin Valor
Para QR Codes estáticos creados sin valor definido (el pagador proporciona el valor), solo se permiten splits de tipo PERCENTAGE. Los splits FIXED serán rechazados, ya que el valor final no se conoce al momento de la creación.
Webhooks
PIX-IN Confirmado (con splits)
Cuando se confirma el pago, se envía el webhook estándar CashIn. Los splits se procesan automáticamente en segundo plano.
{
"event": "CashIn",
"status": "CONFIRMED",
"transactionId": "12345",
"externalId": "ORDER-12345",
"originalAmount": 100.00,
"finalAmount": 99.50,
"feeAmount": 0.50
}PIX-OUT del Split (ejecución)
Por cada destinatario del split, se ejecuta un PIX-OUT y se envía un webhook CashOut:
{
"event": "CashOut",
"status": "CONFIRMED",
"transactionId": "67890",
"externalId": "SPLIT-12345-seller",
"originalAmount": 70.00,
"finalAmount": 70.00,
"counterpart": {
"name": "John's Store",
"document": "*.765.432/0001-**"
}
}Los webhooks CashOut de splits siguen el mismo formato y configuración que los webhooks regulares de Cash-Out. Configure sus webhooks en Configuración -> Webhooks en el dashboard.