Split

Use this FAQ to validate payment split rules before creating or updating charges via the Asaas API.

The payment split automatically divides the amount received in a charge between one or more Asaas accounts. This page complements the Introduction - Payment Split and helps you confirm requirements, limits, payload examples, and operational considerations before implementation.

Prerequisites

1. Create or identify the Asaas account that will issue the charge.
2. Obtain the walletId of each Asaas account that will receive a portion of the amount.
3. Define whether each transfer will use a fixed amount (fixedValue) or a percentage (percentualValue).
4. Validate that the sum of transfers does not exceed the net value of the charge or 100% for percentage-based splits.
5. Refer to the create charge or update charge reference to send the splits field in the request body.

Recommended Integration Flow

1. Create the charge on the account that should receive the remaining balance.
2. Send the splits array with one entry for each account that will receive a transfer.
3. Wait for the charge to be paid. Asaas executes the split automatically upon receipt.
4. Query the charge or monitor webhook events to confirm the split status.
5. If an adjustment is needed before receipt, update the charge by sending the splits array again with the desired configuration.

Split Parameters

Example: Split on a One-Time Charge

Add the splits array to the charge creation body. In the example below, one account receives a fixed R$ 20.00 and another receives 10% of the net charge value.

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

Expected result: when the charge is received, Asaas calculates the net value, executes the configured transfers, and keeps the remaining balance in the account that issued the charge.

Example: Split on an Installment Plan

In installment plans, you can specify the amount applied to each installment using fixedValue, or the total split amount using totalFixedValue.

Amount Per Installment

{
  "totalValue": 100.00,
  "installmentCount": 4,
  "splits": [
    {
      "walletId": "48548710-9baa-4ec1-a11f-9010193527c6",
      "fixedValue": 10.00
    }
  ]
}

Expected result: Asaas applies a R$ 10.00 split to each of the 4 installments, totaling R$ 40.00 upon full repayment.

Total Installment Amount

{
  "totalValue": 300.00,
  "installmentCount": 3,
  "splits": [
    {
      "walletId": "0b763922-aa88-4cbe-a567-e3fe8511fa06",
      "totalFixedValue": 100.00
    }
  ]
}

Expected result: Asaas automatically divides the total split across the installments, applying R$ 33.33, R$ 33.33, and R$ 33.34.

Frequently Asked Questions

What happens when I reverse a charge with a split?

In the event of a charge reversal, the split is also reversed. All accounts that received funds from the charge have the transfer reversed.

Is there a limit on the number of wallets (walletId) for a split?

There is no limit on the number of walletId entries sent in a split. The limitation is the total net value of the charge for fixed-value splits and a maximum distribution of 100% for percentage-based splits.

Can I send split funds to my subaccount X days after receipt?

No. The split is executed automatically at the time of receipt and does not allow date customization.

If you need to transfer funds on a future date, create the charge without a split, receive the full amount in the issuing account, and make a transfer between Asaas accounts on the desired day.

Is it possible to use split without API integration?

Payment split is an exclusive API feature of Asaas and cannot be used or managed directly through the website.

If you do not have an API integration, see Using Split Without API to evaluate alternatives such as plugins and connectors.

What do I need to use payment split in Asaas?

You need the walletId of all Asaas accounts that will receive transfers. The walletId is returned when creating subaccounts and can also be retrieved via API when you have the API key of the destination account.

Who should configure the payment split?

Whoever creates the charge should configure the split. In the charge body, provide the walletId of the account that will receive the transfer and the fixed or percentage amount to be transferred.

All parties involved must have an Asaas account for the transfer to be processed correctly.

How does commission splitting work in a split?

Commission splitting allows the amount of a charge to be automatically divided among the parties involved. You can configure each transfer as a percentage or fixed value.

How does the system calculate the transferred amount when the commission is percentage-based?

When the commission is percentage-based, the calculation is made on the net value of the charge — that is, after the applicable fees are deducted.

For example: if a charge has a net value of R$ 98.00 and a split with percentualValue of 50, the calculated transfer is R$ 49.00.

Can I define more than one percentage to split the amount among multiple people?

Yes. You can configure different percentages for multiple accounts. The sum of the percentages cannot exceed 100%.

How does fixed-value commission splitting work?

When the split is configured with a fixed value, you define the exact amount to be transferred. The fixed value cannot exceed the net value of the charge.

What happens if the sum of percentages exceeds 100%?

The system does not allow split configuration to exceed 100%. If you attempt to configure percentages that sum to more than 100%, the API returns an error and the split is not saved to the charge.

How do Asaas fees affect percentage-based splitting?

Asaas fees are deducted before the split is distributed among the parties. The percentage is applied only to the net value of the charge.

Can I combine fixed value and percentage in the same split?

Yes. You can combine fixedValue and percentualValue transfers in the same charge, as long as the calculated total does not exceed the net value.

Example: on a charge with a net value of R$ 98.00, a fixed split of R$ 50.00 combined with a 50% percentage split would result in R$ 99.00 in total transfers. Since this exceeds the net value, the API returns an exception.

What statuses can a split have?

The available statuses are:

• PENDING
• AWAITING_CREDIT
• CANCELLED
• DONE
• REFUSED
• REFUNDED

When the status is REFUSED, the refusalReason field may indicate the reason. One possible reason is RECEIVABLE_UNIT_AFFECTED_BY_EXTERNAL_CONTRACTUAL_EFFECT, when the split is not executed due to the existence of contractual effects.

Common Errors and Best Practices

To reduce operational failures, store the internal transfer identifier in externalReference, query the charge before reprocessing updates, and monitor webhooks related to charges and splits. If your integration processes events, also refer to How to Implement Idempotency in Webhooks.

Related Content

• Introduction - Payment Split
• Split on One-Time Charges
• Split on Installment Plans
• Split on Subscriptions
• Split on Anticipated Charges
• Querying Splits via Interface
• Transfer to Asaas Account
• Create New Charge