Configure Payment Split in Checkout

Add splits to the Checkout to automatically distribute part of the amount received among other Asaas accounts.

The Split is executed after the charge generated by the Checkout is received.

Before you start

Before configuring:

• get the walletId of each account that will receive part of the amount;
• define whether each split will be fixed or percentage-based;
• validate that the distribution does not exceed the net value of the charge;
• do not provide the walletId of the account that creates the Checkout;
• configure the Checkout and payment Webhooks.

The net difference not allocated to the recipients remains in the account that originated the charge.

How it works

%%{init: {"flowchart": {"nodeSpacing": 28,"rankSpacing": 32,"diagramPadding": 8,"padding": 10}}}%%
flowchart TD
  A["Get the walletIds"] --> B["Define the Split values"]
  B --> C["Add splits to the Checkout"]
  C --> D["Create the Checkout"]
  D --> E["Payer completes the payment"]
  E --> F["Calculate the net value"]
  F --> G["Settle the Splits"]
  G --> H["Receive the Webhooks"]

  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,F,G validacao
  class H sucesso

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

1. Define the Split values

Each item in splits must provide the walletId of the destination account and the distribution rule.

Fixed value

Use fixedValue to set a specific amount:

{
  "walletId": "WALLET_ID_1",
  "fixedValue": 100.00
}

fixedValue accepts up to two decimal places.

Percentage value

Use percentualValue to set a percentage:

{
  "walletId": "WALLET_ID_2",
  "percentualValue": 50
}

The percentage is calculated on the net value of the charge (netValue), after Asaas fees are deducted.

percentualValue accepts up to four decimal places, and the sum of the percentages cannot exceed 100%.

See the Payment Split rules.

2. Add the Split to the Checkout

Include splits in the creation body:

POST /v3/checkouts

Example:

{
  "billingTypes": ["PIX"],
  "chargeTypes": ["DETACHED"],
  "minutesToExpire": 60,
  "callback": {
    "cancelUrl": "https://mysite.com/canceled",
    "expiredUrl": "https://mysite.com/expired",
    "successUrl": "https://mysite.com/success"
  },
  "items": [
    {
      "name": "Order 1001",
      "quantity": 1,
      "value": 300.00
    }
  ],
  "splits": [
    {
      "walletId": "WALLET_ID_1",
      "fixedValue": 100.00
    },
    {
      "walletId": "WALLET_ID_2",
      "percentualValue": 50
    }
  ]
}

In this example:

• the first wallet receives R$ 100.00;
• the second receives 50% of the netValue;
• the net balance not allocated to the Splits remains in the account that originated the charge.

See the Create new checkout endpoint.

Expected result

The API returns the Checkout ID.

The Split is not settled at this point. The distribution occurs after the charge generated by the Checkout is received.

3. Track the payment and settlement

Use Webhooks to track different stages of the flow:

PAYMENT_SPLIT_DONE is triggered individually for each settled Split. When there is more than one recipient, several events may be sent.

To identify which Split was settled, use additionalInfo.splitId in the PAYMENT_SPLIT_DONE event.

See the Events for Checkout.

See the Events for payments.

Common errors

If the Checkout with Split is not created or processed as expected, check:

• whether all walletId values belong to valid Asaas accounts;
• whether the walletId of the issuing account itself was not provided;
• whether the fixed values do not exceed the netValue;
• whether the sum of the percentages does not exceed 100%;
• whether the combination of fixed and percentage values remains compatible with the net value of the charge.

For other rules and scenarios, see Payment Split.

Next steps

• Set up the Checkout link and redirection
• Track the Events for Checkout
• Track the Events for payments
• See the Payment Split rules
• See common Checkout errors
• See the Asaas Checkout FAQ