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.
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 (after deducting fees) and creates the split items.
Depending on the configured frequency, the amounts are automatically 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 needed.
Execution Frequencies
The frequency determines when accumulated splits are executed. It is configured per account, not per transaction.
| 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 |
When the frequency is DAILY or WEEKLY, splits from multiple transactions for the same recipient are grouped into a single PIX-OUT. This reduces transaction costs.
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 x 70% | R$ 70.00 |
| Platform | 20% | R$ 100.00 x 20% | R$ 20.00 |
| Delivery Person | Fixed | R$ 10.00 | R$ 10.00 |
| Total | R$ 100.00 |
When there are platform fees (fee), the percentage calculation is based on the gross value (before fees). Fees are deducted from the remaining amount after splits.
Limits and Restrictions
| Restriction | Value |
|---|---|
| Maximum recipients per transaction | 10 |
| Minimum value per split (FIXED) | 0.01 (R$ 0.01) |
| Minimum percentage per split | 0.01 (0.01%) |
| Maximum decimal places | 2 |
| Sum of splits | Cannot exceed the transaction value |
If the sum of fixed splits + percentages of the gross value + fees exceeds the transaction value, the API will return error 400 Bad Request.
Static QR Code Without Value
For static QR Codes created without a defined value (the payer provides the value), only PERCENTAGE splits are allowed. FIXED splits will be 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",
"transactionId": "12345",
"externalId": "ORDER-12345",
"originalAmount": 100.00,
"finalAmount": 99.50,
"feeAmount": 0.50
}PIX-OUT from Split (execution)
For each split recipient, a PIX-OUT is executed and a CashOut webhook is sent:
{
"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-**"
}
}CashOut webhooks for splits follow the same format and configuration as regular Cash-Out webhooks. Configure your webhooks in Settings -> Webhooks in the dashboard.