Payment Split
Overview
Payment Split allows you to automatically divide the value of a received PIX (Cash-In) among multiple recipients. When a payment is confirmed, the system calculates each recipient's share and executes the transfers (PIX-OUT) automatically.
The split is configured at the time the charge is created (Cash-In or Static QR Code). It is not possible to add splits to a transaction that has already been created.
Split must be enabled on your account before use. Without it, a charge sent with splits is rejected with 400 and errorCode SPLIT_NOT_CONFIGURED. Enablement, execution frequency, minimum accumulated amount, and the recipient limit per transaction are set per account by support (suporte@fypay.me [A DEFINIR]); there is no public endpoint to change them.
Use Cases
Marketplace
Automatically split the payment between the seller and the platform (commission).
Partnerships
Distribute revenue among partners with pre-defined percentages.
Franchises
Automatic transfer of royalties and fees to the franchisor.
Service Providers
Automatic transfer to the provider with platform fee retention.
How It Works
When generating a PIX Cash-In, include the splits array with the recipients and their values (fixed or percentage).
When the payer completes the PIX, the CashIn webhook is sent with status CONFIRMED.
The system calculates each recipient's amount (fixed first, then percentages of the gross value) and creates the split items.
According to the frequency configured on the account (or right away, if the split has immediate: true), the amounts are sent via PIX to each recipient.
For each transfer, a CashOut webhook is dispatched with the result (success or failure).
Split Types
FIXED — Fixed Value
The recipient receives a fixed amount regardless of the total payment value.
{
"type": "FIXED",
"value": 10.00
}The value is in BRL with up to 2 decimal places: 10.00 = R$ 10.00.
PERCENTAGE — Percentage
The recipient receives a percentage of the gross payment value (before fees).
{
"type": "PERCENTAGE",
"value": 10
}The percentage is provided directly: 10 = 10%, 25.5 = 25.5%.
Value Format
Split values use the same format as the transaction.value field — in BRL with up to 2 decimal places.
Fixed Values (FIXED)
| Value in BRL | value Field |
|---|---|
| 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 |
Minimum: 0.01
Percentages (PERCENTAGE)
| Percentage | value Field |
|---|---|
| 1% | 1 |
| 5% | 5 |
| 10% | 10 |
| 25.5% | 25.5 |
| 33.33% | 33.33 |
| 50% | 50 |
The value represents the percentage directly. No multiplication.
Execution Frequencies
The frequency determines when accumulated splits are executed. It is configured per account by support, not per transaction (the default is DAILY).
| Frequency | Behavior |
|---|---|
IMMEDIATE | Executed immediately after PIX-IN confirmation |
HOURLY | Accumulated and executed every hour |
DAILY | Accumulated and executed once per day |
WEEKLY | Accumulated and executed once per week |
With the HOURLY, DAILY, and WEEKLY frequencies, splits from multiple transactions for the same recipient are grouped into a single PIX-OUT. If the account has a minimum accumulated amount configured and the recipient's total is below it, the transfer waits for the next cycle.
immediate Field in Split
The immediate field on an individual split allows you to override the account frequency for that specific split:
{
"pixKey": "urgent@email.com",
"pixKeyType": "EMAIL",
"name": "Urgent Supplier",
"document": "12345678000199",
"type": "FIXED",
"value": 50.00,
"immediate": true
}When immediate: true, the split is executed immediately after PIX-IN confirmation, even if the account is configured with DAILY frequency.
Complete Example
Scenario: Marketplace with 3 recipients
A marketplace receives R$ 100.00 from a customer. The value should be divided:
- Seller: 70% of the value
- Platform: 20% of the value
- Delivery person: R$ 10.00 fixed
{
"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
}
]
}Result after payment (R$ 100.00 received):
| Recipient | Type | Calculation | Value |
|---|---|---|---|
| Seller | 70% | R$ 100.00 × 70% | R$ 70.00 |
| Platform | 20% | R$ 100.00 × 20% | R$ 20.00 |
| Delivery Person | Fixed | R$ 10.00 | R$ 10.00 |
| Total | R$ 100.00 |
When there is a platform fee, the percentage is calculated on the gross value (before the fee). The fee and the splits come out of the received amount, and what remains stays in your account. Split PIX-OUTs have no additional fee.
Limits and Restrictions
| Restriction | Value |
|---|---|
| Maximum recipients per transaction | 10 (or fewer, if the account limit is lower: SPLIT_MAX_RECIPIENTS_EXCEEDED) |
| Minimum value per split (FIXED) | 0.01 (R$ 0.01) |
| Minimum percentage per split | 0.01 (0.01%) |
| Maximum decimal places | 2 |
| Sum of percentages | Up to 100% (SPLIT_PERCENTAGE_EXCEEDS_100) |
| Sum of splits + fee | Cannot exceed the transaction value (SPLIT_EXCEEDS_AMOUNT) |
If the sum of fixed splits + percentages of the gross value + fee exceeds the transaction value, the API returns 400 Bad Request with errorCode SPLIT_EXCEEDS_AMOUNT and the charge is not created.
Split validation errors
All return 400 Bad Request when the charge is created:
errorCode | Cause |
|---|---|
SPLIT_NOT_CONFIGURED | Split is not enabled on the account |
SPLIT_MAX_RECIPIENTS_EXCEEDED | More recipients than the account limit (details.max) |
SPLIT_EXCEEDS_AMOUNT | Splits + fee exceed the transaction value |
SPLIT_PERCENTAGE_EXCEEDS_100 | The sum of percentages exceeds 100% |
Static QR Code Without Value
For static QR Codes (POST /api/pix/qrcode-static) created without a defined value (the payer provides the value), only PERCENTAGE splits are allowed. FIXED splits are rejected, as the final value is not known at the time of creation.
Webhooks
PIX-IN Confirmed (with splits)
When the payment is confirmed, the standard CashIn webhook is sent. Splits are processed automatically in the background.
{
"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 from Split (execution)
For each split transfer, a PIX-OUT is executed and a CashOut webhook is sent. The externalId of these transfers is generated by the platform in the split-col-<id> format, so it does not match any externalId of yours:
{
"event": "CashOut",
"status": "CONFIRMED",
"transactionType": "PIX",
"movementType": "DEBIT",
"transactionId": "67890",
"externalId": "split-col-321",
"feeAmount": 0,
"originalAmount": 70.00,
"finalAmount": 70.00,
"counterpart": {
"name": "John's Store",
"document": "98765432000188",
"bank": { ... }
},
...
}CashOut webhooks for splits follow the same format and configuration as regular Cash-Out webhooks. Configure your webhooks in Settings → Webhooks in the dashboard.