Configure Split in single payments

To split the amount of a one-time charge, add the split array to the charge creation request.

The other charge settings remain the same as in the flow without Split.

Before you start

Have the walletId of each account that will receive part of the amount and define whether the transfer will be:

• fixed, with fixedValue;
• percentage-based, with percentualValue.

The calculation rules on netValue, limits and combinations are in Payment Split.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
    A["Define the recipients"] --> B["Add split to the charge"]
    B --> C["Create the charge"]
    C --> D["Receive the payment"]
    D --> E["Settle the Splits"]
    E --> F["Receive the Webhook"]

    classDef inicio fill:#DBEAFE,stroke:#2563EB,color:#1E3A8A,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

    class A inicio
    class B,C,D,E validacao
    class F sucesso

    linkStyle default stroke:#94A3B8,stroke-width:2px

1. Add the Split to the charge

Include split when creating the charge:

{
  "...": "...",
  "split": [
    {
      "walletId": "48548710-9baa-4ec1-a11f-9010193527c6",
      "fixedValue": 20.00
    },
    {
      "walletId": "0b763922-aa88-4cbe-a567-e3fe8511fa06",
      "percentualValue": 10.00
    }
  ]
}

In this example:

• the first wallet receives R$ 20.00;
• the second receives 10% of the netValue;
• the net balance not allocated to recipients remains in the account that created the charge.

See the Create new payment with summary data in response endpoint.

Expected result

The charge will be created with the associated Split settings.

The amounts will be distributed when the respective Splits are settled.

2. Update the Split

Retrieve the charge ID and send the new split configuration in the update:

PUT /v3/lean/payments/{id}

{
  "...": "...",
  "split": [
    {
      "walletId": "48548710-9baa-4ec1-a11f-9010193527c6",
      "fixedValue": 10.00
    }
  ]
}

See the Update existing payment with summary data in response endpoint.

Updating a Split has additional rules when the charge is already confirmed. See Update existing payment to check the allowed statuses and conditions.

3. Check the charge's Split

To retrieve a specific charge, use:

GET /v3/lean/payments/{id}

See the Retrieve a single payment with summary data endpoint.

To find charges using filters, use List payments with summary data.

When a Split is configured, the corresponding data is returned along with the charge.

Prefer Webhooks to track changes and settlement instead of continuously querying the charge.

4. Track the settlement

Split data is also included in charge-related events.

To identify when a specific Split is settled, handle:

PAYMENT_SPLIT_DONE

The event is sent individually for each settled Split. Use additionalInfo.splitId to identify the corresponding Split.

See Payment events.

Next steps

• See the general Payment Split rules
• Configure Split into installments
• Configure Split on subscriptions
• See Split in anticipated payments
• View Splits through the interface
• See the Split FAQ