Pular para o conteúdo principal
Esta seção explica o caminho do dinheiro dentro do Z2Pay: do momento em que uma cobrança é paga até o valor ficar disponível para saque. Antes de integrar split ou consultar saldos, vale entender como cada valor é representado e por onde ele passa.
Esta página é conceitual. Os endpoints concretos estão nas páginas Taxas, Split e Liquidação.

​
Duas regras que valem para tudo

Valores em centavos

Todo valor monetário é um inteiro em centavos. R$ 10,00 é enviado e retornado como 1000. Para exibir, divida por 100. Nunca envie casas decimais (10.00) em campos de valor.

Moeda BRL

A moeda padrão é BRL (Real). Quando um campo currency aparece, ele segue o padrão ISO 4217 com 3 letras (ex.: "BRL").
Se você enviar 1050 pensando em “R1.050,00",oZ2Payvaientender∗∗R 1.050,00", o Z2Pay vai entender **R 10,50**. Centavos sempre. Confira a página de convenções para os detalhes de formatação.

​
O caminho do dinheiro

O fluxo padrão de uma venda até o saque tem cinco etapas:
1

Cobrança paga

O cliente paga uma transação (cartão, Pix ou boleto). O valor bruto entra no sistema em centavos. Veja Transações e Pagamentos.
2

Taxa aplicada

Sobre o valor bruto incidem as taxas da plataforma (taxa de processamento, taxa fixa, etc.). O que sobra é o valor líquido a ser distribuído. Veja Taxas.
3

Split entre recebedores

Se a transação tiver um split configurado, o valor líquido é repartido entre os recebedores conforme a configuração (por percentual ou valor fixo). Veja Split.
4

Crédito na carteira

Cada parcela do split vira um crédito na carteira (wallet) do recebedor. O crédito pode ficar pendente (pending) até passar pelo período de liberação, ou já liberado (released). Veja Liquidação.
5

Saque

Com saldo liberado na carteira, o recebedor solicita um saque (withdrawal) para sua conta bancária. Veja Liquidação.

​
Conceitos-chave

Valor bruto é o que o cliente pagou. Valor líquido é o que sobra depois das taxas e é o valor efetivamente distribuído no split. Ambos são inteiros em centavos.
Um split define como o valor de uma transação é dividido entre recebedores. Cada item do split aponta para um recipientId e tem um value mais um valueType que indica se esse valor é percentual (percentage) ou valor fixo em centavos (fixed).Regras importantes da configuração de split:
  • Todos os itens percentuais somam 100%.
  • Exatamente 1 item assume a taxa de processamento (processingFee: true).
  • Exatamente 1 item é o responsável (liable: true).
  • O tipo de cada item (type) pode ser sale, interest ou platform_fee — o padrão é sale.
Você pode usar uma configuração de split reutilizável (split config) ou enviar um split inline na criação da transação. Detalhes e exemplos em Split e Split (Core API).
A carteira é onde o saldo de um recebedor fica acumulado. Cada movimentação aparece no extrato da carteira (wallet transactions), com um status de liberação que pode ser pending (ainda não liberado) ou released (disponível). Detalhes em Carteiras (Core API).
O saque transfere o saldo liberado da carteira para a conta bancária do recebedor. O valor do saque é um inteiro em centavos (mínimo 1) e o currency é opcional (3 letras, ISO 4217). Detalhes e endpoints em Liquidação e Carteiras (Core API).

​
Exemplo do fluxo em números

Uma venda de R100,00∗∗(‘10000‘centavos)comumataxatotalde∗∗R 100,00** (`10000` centavos) com uma taxa total de **R 5,00 (500) e um split de 70% / 30% entre dois recebedores fica assim: 
{
  "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 }
  ]
}
Os nomes de campo acima são ilustrativos para explicar o conceito. Os campos exatos de cada resposta estão nas páginas de referência de cada recurso (Transações, Split, Carteiras).

​
Próximos passos

Taxas

Como as taxas incidem sobre o valor bruto.

Split

Configurar o rateio entre recebedores.

Liquidação

Carteira, liberação de saldo e saque.

Recebedores

Cadastrar quem recebe no split.