Skip to main content
This section explains the money path inside Z2Pay: from the moment a charge is paid to the point where the balance is available for withdrawal. Before integrating split or querying balances, it is worth understanding how each value is represented and where it travels through.
This page is conceptual. The concrete endpoints are covered in the Fees, Split, and Settlement pages.

​
Two rules that apply to everything

Values in cents

Every monetary value is an integer in cents. R$ 10.00 is sent and returned as 1000. To display it, divide by 100. Never send decimal places (10.00) in value fields.

BRL currency

The default currency is BRL (Brazilian Real). When a currency field appears, it follows the ISO 4217 standard with 3 letters (e.g., "BRL").
If you send 1050 thinking of “R1,050.00",Z2Paywillinterpretitas∗∗R 1,050.00", Z2Pay will interpret it as **R 10.50**. Cents always. Check the conventions page for formatting details.

​
The money path

The standard flow from a sale to a withdrawal has five stages:
1

Charge paid

The customer pays a transaction (card, Pix, or boleto). The gross amount enters the system in cents. See Transactions and Payments.
2

Fee applied

Platform fees are applied to the gross amount (processing fee, flat fee, etc.). What remains is the net amount to be distributed. See Fees.
3

Split among recipients

If the transaction has a split configured, the net amount is divided among the recipients according to the configuration (by percentage or fixed amount). See Split.
4

Wallet credit

Each portion of the split becomes a credit in the recipient’s wallet. The credit may be pending (pending) until the release period passes, or already released (released). See Settlement.
5

Withdrawal

With a released balance in the wallet, the recipient requests a withdrawal to their bank account. See Settlement.

​
Key concepts

Gross amount is what the customer paid. Net amount is what remains after fees and is the value effectively distributed in the split. Both are integers in cents.
A split defines how the amount of a transaction is divided among recipients. Each split item points to a recipientId and has a value plus a valueType indicating whether that value is a percentage (percentage) or a fixed amount in cents (fixed).Important rules for split configuration:
  • All percentage items must sum to 100%.
  • Exactly 1 item assumes the processing fee (processingFee: true).
  • Exactly 1 item is the liable party (liable: true).
  • The type of each item (type) can be sale, interest, or platform_fee — the default is sale.
You can use a reusable split configuration (split config) or send an inline split when creating the transaction. Details and examples in Split and Split (Core API).
The wallet is where a recipient’s balance accumulates. Each movement appears in the wallet’s statement (wallet transactions), with a release status that can be pending (not yet released) or released (available). Details in Wallets (Core API).
A withdrawal transfers the released wallet balance to the recipient’s bank account. The withdrawal amount is an integer in cents (minimum 1) and currency is optional (3 letters, ISO 4217). Details and endpoints in Settlement and Wallets (Core API).

​
Flow example in numbers

A sale of R100.00∗∗(‘10000‘cents)withatotalfeeof∗∗R 100.00** (`10000` cents) with a total fee of **R 5.00 (500) and a 70% / 30% split between two recipients looks like this: 
{
  "grossAmount": 10000,
  "totalFees": 500,
  "netAmount": 9500,
  "split": [
    { "recipientId": "rec_1a2b3c", "valueType": "percentage", "value": 70, "netAmount": 6650 },
    { "recipientId": "rec_4d5e6f", "valueType": "percentage", "value": 30, "netAmount": 2850 }
  ]
}
The field names above are illustrative for explaining the concept. The exact fields of each response are documented on the reference pages for each resource (Transactions, Split, Wallets).

​
Next steps

Fees

How fees are applied to the gross amount.

Split

Configure the distribution among recipients.

Settlement

Wallet, balance release, and withdrawal.

Recipients

Register who receives in the split.