Split de Pagos
Descripción General
El Split de Pagos permite dividir automáticamente el valor de un PIX recibido (Cash-In) entre múltiples destinatarios. Cuando un pago se confirma, el sistema calcula la parte de cada destinatario y ejecuta los envíos (PIX-OUT) automáticamente.
El split se configura en el momento de la creación del cobro (Cash-In o QR Code Estático). No es posible agregar splits a una transacción ya creada.
El split debe estar habilitado en su cuenta antes de usarlo. Sin esa habilitación, un cobro enviado con splits es rechazado con 400 y errorCode SPLIT_NOT_CONFIGURED. La habilitación, la frecuencia de ejecución, el valor mínimo acumulado y el límite de destinatarios por transacción los define por cuenta el soporte (suporte@fypay.me [A DEFINIR]); no hay endpoint público para modificarlos.
Casos de Uso
Marketplace
Dividir automáticamente el pago entre vendedor y plataforma (comisión).
Sociedades
Distribuir ingresos entre socios con porcentajes predefinidos.
Franquicias
Transferencia automática de regalías y tarifas a la franquiciante.
Proveedores de Servicios
Transferencia automática al proveedor con retención de la tarifa de la plataforma.
Cómo Funciona
Al generar un PIX Cash-In, incluya el array splits con los destinatarios y sus valores (fijo o porcentual).
Cuando el pagador realiza el PIX, se envía el webhook CashIn con estado CONFIRMED.
El sistema calcula el valor de cada destinatario (fijos primero, luego porcentajes sobre el valor bruto) y crea los ítems de split.
Según la frecuencia configurada en la cuenta (o de inmediato, si el split tiene immediate: true), los valores se envían vía PIX a cada destinatario.
Por cada envío, se dispara un webhook CashOut con el resultado (éxito o falla).
Tipos de Split
FIXED — Valor Fijo
El destinatario recibe un valor fijo, independientemente del valor total del pago.
{
"type": "FIXED",
"value": 10.00
}El valor está en reales con hasta 2 decimales: 10.00 = R$ 10,00.
PERCENTAGE — Porcentaje
El destinatario recibe un porcentaje del valor bruto del pago (antes de las tarifas).
{
"type": "PERCENTAGE",
"value": 10
}El porcentaje se informa directamente: 10 = 10%, 25.5 = 25,5%.
Formato de Valores
Los valores de split usan el mismo formato que el campo transaction.value — en reales con hasta 2 decimales.
Valores Fijos (FIXED)
| Valor en Reales | Valor en el 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 | Valor en el Campo value |
|---|---|
| 1% | 1 |
| 5% | 5 |
| 10% | 10 |
| 25,5% | 25.5 |
| 33,33% | 33.33 |
| 50% | 50 |
El valor representa el porcentaje directamente. Sin multiplicación.
Frecuencias de Ejecución
La frecuencia determina cuándo se ejecutan los splits acumulados. El soporte la configura por cuenta, no por transacción (el predeterminado es DAILY).
| Frecuencia | Comportamiento |
|---|---|
IMMEDIATE | Se ejecuta inmediatamente después de la confirmación del PIX-IN |
HOURLY | Se acumula y se ejecuta cada hora |
DAILY | Se acumula y se ejecuta una vez al día |
WEEKLY | Se acumula y se ejecuta una vez por semana |
En las frecuencias HOURLY, DAILY y WEEKLY, los splits de múltiples transacciones para el mismo destinatario se agrupan en un único PIX-OUT. Si la cuenta tiene configurado un valor mínimo acumulado y el total del destinatario queda por debajo de él, el envío espera al próximo ciclo.
Campo immediate en el Split
El campo immediate en el split individual permite sobrescribir la frecuencia de la cuenta para ese split específico:
{
"pixKey": "urgente@email.com",
"pixKeyType": "EMAIL",
"name": "Proveedor Urgente",
"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, aunque 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 fijo
{
"transaction": {
"value": 100.00,
"description": "Pedido #12345 - Marketplace",
"externalId": "ORDER-12345",
"generateQrCode": true
},
"payer": {
"fullName": "Carlos Oliveira",
"document": "12345678901"
},
"splits": [
{
"pixKey": "vendedor@email.com",
"pixKeyType": "EMAIL",
"name": "Tienda de João",
"document": "98765432000188",
"type": "PERCENTAGE",
"value": 70,
"immediate": false
},
{
"pixKey": "plataforma@marketplace.com",
"pixKeyType": "EMAIL",
"name": "Marketplace Ltda",
"document": "11222333000144",
"type": "PERCENTAGE",
"value": 20,
"immediate": false
},
{
"pixKey": "12345678901",
"pixKeyType": "CPF",
"name": "Repartidor 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 × 70% | R$ 70,00 |
| Plataforma | 20% | R$ 100,00 × 20% | R$ 20,00 |
| Repartidor | Fijo | R$ 10,00 | R$ 10,00 |
| Total | R$ 100,00 |
Cuando hay tarifa de la plataforma, el porcentaje se calcula sobre el valor bruto (antes de la tarifa). La tarifa y los splits salen del valor recibido, y lo que sobra queda en su cuenta. Los PIX-OUT de split no tienen tarifa adicional.
Límites y Restricciones
| Restricción | Valor |
|---|---|
| Máximo de destinatarios por transacción | 10 (o menos, si el límite de la cuenta es menor: SPLIT_MAX_RECIPIENTS_EXCEEDED) |
| 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 los porcentajes | Hasta 100% (SPLIT_PERCENTAGE_EXCEEDS_100) |
| Suma de los splits + tarifa | No puede exceder el valor de la transacción (SPLIT_EXCEEDS_AMOUNT) |
Si la suma de los splits fijos + porcentajes sobre el valor bruto + tarifa excede el valor de la transacción, la API devuelve 400 Bad Request con errorCode SPLIT_EXCEEDS_AMOUNT y el cobro no se crea.
Errores de validación del split
Todos devuelven 400 Bad Request en la creación del cobro:
errorCode | Causa |
|---|---|
SPLIT_NOT_CONFIGURED | El split no está habilitado en la cuenta |
SPLIT_MAX_RECIPIENTS_EXCEEDED | Más destinatarios que el límite de la cuenta (details.max) |
SPLIT_EXCEEDS_AMOUNT | Splits + tarifa exceden el valor de la transacción |
SPLIT_PERCENTAGE_EXCEEDS_100 | La suma de los porcentajes supera el 100% |
QR Code Estático sin Valor
Para QR Codes estáticos (POST /api/pix/qrcode-static) creados sin valor definido (el pagador informa el valor), solo se permiten splits del tipo PERCENTAGE. Los splits FIXED son rechazados, ya que el valor final no se conoce en el momento de la creación.
Webhooks
PIX-IN Confirmado (con splits)
Cuando el pago se confirma, se envía el webhook CashIn estándar. Los splits se procesan automáticamente en segundo plano.
{
"event": "CashIn",
"status": "CONFIRMED",
"transactionType": "PIX",
"movementType": "CREDIT",
"transactionId": "12345",
"externalId": "ORDER-12345",
"endToEndId": "E00416968202501151030VX5Sx8fIpkY",
"feeAmount": 0.50,
"originalAmount": 100.00,
"finalAmount": 99.50,
...
}PIX-OUT del Split (ejecución)
Por cada envío de split, se ejecuta un PIX-OUT y se envía un webhook CashOut. El externalId de estos envíos lo genera la plataforma con el formato split-col-<id>, por lo que no corresponde a ninguno de sus externalId:
{
"event": "CashOut",
"status": "CONFIRMED",
"transactionType": "PIX",
"movementType": "DEBIT",
"transactionId": "67890",
"externalId": "split-col-321",
"feeAmount": 0,
"originalAmount": 70.00,
"finalAmount": 70.00,
"counterpart": {
"name": "Tienda de João",
"document": "98765432000188",
"bank": { ... }
},
...
}Los webhooks de CashOut de los splits siguen el mismo formato y configuración que los webhooks de Cash-Out normales. Configure sus webhooks en Configuración → Webhooks en el panel.