Split for accounts with Escrow Account

When a charge with Split directs amounts to subaccounts with different Escrow Account settings, treat Split settlement and balance availability as separate steps.

Each recipient account follows its own Escrow Account configuration. Therefore, amounts originating from the same charge may become available at different times.

Before you start

Before combining the features:

• obtain the walletId of each account that will receive the Split;
• configure the Escrow Account on the subaccounts that should keep amounts in escrow;
• define the daysToExpire of each subaccount individually;
• configure the Escrow Account before the receipt that should be held in escrow;
• define the Split amounts taking into account the charge's netValue.

Changes to daysToExpire only affect new receipts processed after the configuration is updated.

See Configuring the Escrow Account for subaccounts and Split in single payments for the complete configuration flows.

How it works

The Split is processed for each recipient account. The availability of the amount depends on the configuration applied to the destination account.

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Define the recipients"] --> B["Create charge with Split"]
    B --> C["Receive the charge"]
    C --> D["Settle a Split"]
    D --> E["Receive<br/>PAYMENT_SPLIT_DONE"]
    E --> F{"Does the destination account use an Escrow Account?"}

    F --> FSim(("Yes"))
    F --> FNao(("No"))

    FSim --> G["Keep amount in escrow"]
    FNao --> I["Make amount available in the balance"]

    G --> H["End the escrow"]
    H --> I

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,stroke-width:3px,font-size:17px
    classDef decisao fill:#FEF3C7,stroke:#D97706,color:#78350F,stroke-width:3px,font-size:17px
    classDef validacao fill:#E0F2FE,stroke:#0284C7,color:#0C4A6E,stroke-width:2px,font-size:17px
    classDef sucesso fill:#DCFCE7,stroke:#16A34A,color:#14532D,stroke-width:3px,font-size:17px

    classDef respostaSim fill:#22C55E,stroke:#15803D,color:#FFFFFF,stroke-width:3px,font-size:16px
    classDef respostaNao fill:#EF4444,stroke:#B91C1C,color:#FFFFFF,stroke-width:3px,font-size:16px

    class A inicio
    class F decisao
    class B,C,D,E,G,H validacao
    class I sucesso

    class FSim respostaSim
    class FNao respostaNao

    linkStyle default stroke:#94A3B8,stroke-width:2px
    linkStyle 5 stroke:#22C55E,stroke-width:4px
    linkStyle 6 stroke:#EF4444,stroke-width:4px

When there are multiple recipients, this behavior must be considered individually for each account.

Example with different rules

Consider a charge whose Split directs amounts to three subaccounts:

The remaining 10% stays in the account that created the charge.

B and C can receive Splits from the same charge and keep different escrow periods, because daysToExpire belongs to each subaccount's configuration.

1. Configure the Escrow Account on the accounts that should hold amounts

Configure each recipient individually.

Account B

POST /v3/accounts/{id}/escrow

{
  "daysToExpire": 10,
  "enabled": true,
  "isFeePayer": true
}

Account C

POST /v3/accounts/{id}/escrow

{
  "daysToExpire": 15,
  "enabled": true,
  "isFeePayer": true
}

Account D remains without an Escrow Account.

See the Save or update Escrow Account configuration for subaccount endpoint.

2. Create the charge with Split

Add the split array when creating the charge:

POST /v3/payments

{
  "customer": "cus_000005219613",
  "billingType": "PIX",
  "value": 500.00,
  "dueDate": "2026-09-20",
  "split": [
    {
      "walletId": "<walletId-account-B>",
      "percentualValue": 20.00
    },
    {
      "walletId": "<walletId-account-C>",
      "percentualValue": 20.00
    },
    {
      "walletId": "<walletId-account-D>",
      "percentualValue": 50.00
    }
  ]
}

The percentualValue is calculated on the netValue, after the applicable fees. The net amount not directed to recipients remains in the account that created the charge.

See the Create new payment endpoint.

3. Track the settlement via Webhook

Use the event:

PAYMENT_SPLIT_DONE

The event is sent individually when a Split is settled. In a charge with multiple recipients, each Split may generate its own notification.

Use additionalInfo.splitId to identify the corresponding Split:

{
  "additionalInfo": {
    "splitId": "064a4957-1eee-4d06-9c96-deaf8a17534d"
  }
}

See Payment events.

4. Take the escrow into account in reconciliation

For accounts with an Escrow Account, do not treat an amount as available just because the respective Split was settled.

While the escrow is active:

• the receipt has already occurred;
• the amount remains in escrow;
• the account cannot yet use these funds as available balance.

The escrow can end automatically upon reaching expirationDate, manually through the API, or by disabling the Escrow Account.

To query and release escrowed amounts, follow the flow in Amounts held in the Escrow Account and Release of escrowed amounts.

How to validate

After the charge is received:

• confirm the PAYMENT_SPLIT_DONE of each expected Split;
• treat B and C as received amounts, but still in escrow while the hold is active;
• take into account the period configured individually for each subaccount;
• treat D according to the normal Split settlement flow;
• do not use recurring queries just to check the settlement of the Splits.

Common mistakes

Treating PAYMENT_SPLIT_DONE as confirmation of available balance

The event confirms the Split settlement. The availability of the amount also depends on the recipient account's Escrow Account.

Configuring daysToExpire in the Split

The period belongs to the subaccount's Escrow Account configuration, not to the charge's split array.

Calculating the Split on the gross amount

percentualValue uses the netValue. Take the applicable fees into account before defining the distribution.

Using polling to track each Split

Use PAYMENT_SPLIT_DONE as the main mechanism for tracking the settlement.

Next steps

• Split in single payments
• Configuring the Escrow Account for subaccounts
• Amounts held in the Escrow Account
• Release of escrowed amounts
• Payment events