Split calculation - Z2Pay Developers

Split is the division of a payment amount between two or more recipients (rec_). You define a split configuration (percentage or fixed amounts), and Z2Pay calculates how much each recipient receives, who bears the processing fee, and who is the financial liable party for the transaction. This page explains how the calculation works, with numeric examples. To create, edit, and list split configurations (the API CRUD), see Core API · Splits.

All values on this page are integers in cents. A payment of R$ 100.00 is 10000. See Conventions.

Anatomy of a split item

A split configuration is a list (config) of items. Each item describes one recipient’s share:

recipientId

string

required

ID of the recipient who receives this share (rec_...). The recipient must exist and be linked to the gateway used in the payment.

value

number

required

The share amount. Minimum 0.01. When valueType is percentage, this is the percentage (e.g., 60 = 60%). When it is fixed, this is the amount in cents (e.g., 3000 = R$ 30.00).

valueType

string

required

How to interpret value. One of:

percentage — value is a percentage.
fixed — value is a fixed amount in cents.

type

string

default:"sale"

The nature of the share. One of:

sale — sale share (default).
interest — interest/surcharge share.
platform_fee — platform share (marketplace fee). Has a special effect on the calculation (see When platform_fee exists).

processingFee

boolean

Indicates that this recipient bears the processing fee (MDR/acquiring) for the payment. Optional on the item, but the entire configuration must have exactly one item with processingFee: true.

liable

boolean

Indicates that this recipient is the financial liable party for the transaction — who is responsible for chargebacks and absorbs rounding remainders. Optional on the item, but the entire configuration must have exactly one item with liable: true.

Validation rules

When saving or using a split configuration, Z2Pay validates:

The list must have at least 1 item

config cannot be empty.

If percentage-based, the sum must be 100%

When items use valueType: "percentage", the sum of all value fields must be exactly 100 (tolerance of 0.01). Otherwise, the request is rejected with the message “Sum of percentages must be 100%”.

Exactly 1 item with processingFee

Not zero, not two. Exactly one item in the list must have processingFee: true.

Exactly 1 item with liable

Same rule: exactly one item must have liable: true.

The processingFee and liable rules apply to the configuration as a whole. If you build the list with none (or more than one) marked item, validation will fail. Payload validation errors return 400 (VALIDATION_ERROR); see Errors.

The amount (amount) of each item, in cents, depends on valueType:

`valueType`	Formula	Note
`percentage`	`floor(paymentAmount × value / 100)`	Rounds down (truncates cents).
`fixed`	`value`	Used as-is (already in cents).

Percentage rounding is always downward (floor). As a result, the sum of shares may be a few cents below the total amount — this remainder is handled in the next section.

`processingFee` and `liable`, in one sentence each

processingFee → who pays the processing fee (MDR/acquiring) for that payment.
liable → who is the financial liable party: responsible for chargebacks and who absorbs the rounding remainder (the leftover cents from floor).

Rounding via the liable party (remainder)

When the sum of shares does not exactly match the payment amount (an effect of floor on percentages), the remaining difference is added to the share of the processing fee bearer. This ensures the split always closes to the exact total amount, down to the cent.

In practice: the recipient who bears the processing fee is also who receives (or loses) the rounding cents. This keeps the math exact without distributing fractions among all parties.

Example 1 — Simple percentage split (60/40)

Payment of R$ 100.00 (10000 cents), divided between two recipients: 60% for the merchant, 40% for a partner. The merchant bears the fee and is the liable party.

{
  "name": "Lojista + parceiro 60/40",
  "config": [
    {
      "recipientId": "rec_lojista",
      "type": "sale",
      "value": 60,
      "valueType": "percentage",
      "processingFee": true,
      "liable": true
    },
    {
      "recipientId": "rec_parceiro",
      "type": "sale",
      "value": 40,
      "valueType": "percentage"
    }
  ]
}

Calculation over 10000:

Recipient	Percentage	`floor(10000 × %)`	After remainder
`rec_lojista`	60%	`6000`	`6000`
`rec_parceiro`	40%	`4000`	`4000`
Total	100%	`10000`	`10000`

In this case there is no remainder: 6000 + 4000 = 10000.

Example 2 — Rounding (remainder goes to the liable party)

Payment of R$ 100.01 (10001 cents), same 60/40 split.

Recipient	Percentage	`floor(10001 × %)`	After remainder
`rec_lojista`	60%	`floor(6000.6)` = `6000`	`6000 + 1` = `6001`
`rec_parceiro`	40%	`floor(4000.4)` = `4000`	`4000`
Total	100%	`10000` (missing `1`)	`10001`

6000 + 4000 = 10000, leaving 1 cent short of the 10001 total. Since rec_lojista is the one bearing the fee (processingFee: true), it absorbs the remainder and receives 6001. The split closes exactly.

Example 3 — Fixed amounts with multiple recipients

Payment of R$ 150.00 (15000 cents), divided into fixed amounts for three recipients. The first bears the fee and is the liable party.

{
  "name": "Três fornecedores (fixo)",
  "config": [
    {
      "recipientId": "rec_fornecedorA",
      "type": "sale",
      "value": 10000,
      "valueType": "fixed",
      "processingFee": true,
      "liable": true
    },
    { "recipientId": "rec_fornecedorB", "type": "sale", "value": 3000, "valueType": "fixed" },
    { "recipientId": "rec_fornecedorC", "type": "sale", "value": 2000, "valueType": "fixed" }
  ]
}

Recipient	`value` (cents)	Receives
`rec_fornecedorA`	`10000`	`10000`
`rec_fornecedorB`	`3000`	`3000`
`rec_fornecedorC`	`2000`	`2000`
Total	—	`15000`

In a fixed split, ensuring the values add up correctly is your responsibility — Z2Pay does not enforce that the sum matches the payment amount. If the fixed shares do not add up to the total, the difference goes to the liable party’s share (same remainder mechanism as Example 2). Make sure your fixed amounts sum to what you expect.

You cannot mix percentage and fixed logic in the sum: if any items use percentage, the sum of those must be 100%. Keep the configuration consistent (all percentages summing to 100, or fixed amounts consistent with the payment).

When `platform_fee` exists

If any item in the configuration has type: "platform_fee", the platform (owner of the platform_fee share) automatically takes on the liable role, regardless of individual flags:

The platform_fee share becomes the one who bears the processing fee.
The platform_fee share becomes the liable party (financial responsible).
The platform_fee share absorbs the rounding remainder.

In other words: when platform_fee exists, the processingFee/liable flags on other items do not change who assumes the fee/liability in the calculation — the platform takes over. Use platform_fee to model the marketplace fee.

Example 4 — Marketplace with `platform_fee`

Payment of R$ 100.00 (10000 cents): 90% for the seller, 10% platform fee.

{
  "name": "Marketplace 90/10",
  "config": [
    {
      "recipientId": "rec_vendedor",
      "type": "sale",
      "value": 90,
      "valueType": "percentage",
      "processingFee": true,
      "liable": true
    },
    {
      "recipientId": "rec_plataforma",
      "type": "platform_fee",
      "value": 10,
      "valueType": "percentage"
    }
  ]
}

Recipient	Type	`floor(10000 × %)`	Role in calculation
`rec_vendedor`	`sale`	`9000`	Receives `9000`
`rec_plataforma`	`platform_fee`	`1000`	Bears the fee, `liable`, absorbs remainder
Total	—	`10000`	—

Even though rec_vendedor has processingFee: true and liable: true in the JSON, because a platform_fee item exists it is the platform that assumes the fee and liability when the rules are submitted to the gateway. The configuration must still comply with the “exactly 1 processingFee and 1 liable” rule at save time.

Where the split appears afterward

Each payment processed with a split generates payment split records (one per recipient), containing the calculated amount in cents, the type, the valueType, and the effective processingFee/liable flags. You can query these records via the Core API · Splits.

Common errors

Situation	Status	Where to look
Sum of percentages differs from 100%	400	Errors
Zero or more than one item with `processingFee`	400	Errors
Zero or more than one item with `liable`	400	Errors
Recipient not linked to the payment’s gateway	422	Errors

Core API · Splits

CRUD for split configurations and querying the splits of a payment.

Recipients

Values overview

How fees, split, and settlement fit together.

Settlement

When and how each share is settled to the recipient.

​Anatomy of a split item

​Validation rules

​How each share amount is calculated

​processingFee and liable, in one sentence each

​Rounding via the liable party (remainder)

​Example 1 — Simple percentage split (60/40)

​Example 2 — Rounding (remainder goes to the liable party)

​Example 3 — Fixed amounts with multiple recipients

​When platform_fee exists

​Example 4 — Marketplace with platform_fee

​Where the split appears afterward

​Common errors

​See also

Core API · Splits

Recipients

Values overview

Settlement

Anatomy of a split item

Validation rules

How each share amount is calculated

`processingFee` and `liable`, in one sentence each

Rounding via the liable party (remainder)

Example 1 — Simple percentage split (60/40)

Example 2 — Rounding (remainder goes to the liable party)

Example 3 — Fixed amounts with multiple recipients

When `platform_fee` exists

Example 4 — Marketplace with `platform_fee`

Where the split appears afterward

Common errors

See also