> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Conceitos centrais

> Os objetos da Z2Pay e como eles se relacionam: transação, pagamento, cliente, recebedor, split e carteira.

Antes de integrar, vale entender os objetos principais e como eles se encaixam.

## O modelo em uma frase

Uma **transação** representa uma cobrança e contém um ou mais **pagamentos** (tentativas de pagamento
por um método). Quando um pagamento é pago, o valor é creditado em uma ou mais **carteiras** de
**recebedores**, opcionalmente dividido por um **split**.

```mermaid theme={null}
flowchart LR
  C[Customer<br/>cliente] --> T[Transaction<br/>cobrança]
  T --> P[Payment<br/>tentativa por método]
  P -->|pago| S[Split<br/>divisão opcional]
  S --> W[Wallet<br/>saldo do recebedor]
  W --> WD[Withdrawal<br/>saque]
```

## Glossário rápido

| Objeto               | Prefixo do ID | O que é                                                                                        |
| -------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
| **Transaction**      | `txn_`        | Uma cobrança. Agrupa items e pagamentos. Tem um `status` derivado dos pagamentos.              |
| **Pagamento**        | `pay_`        | Uma tentativa de pagar parte (ou todo) o valor por um método (`credit_card`, `pix`, `boleto`). |
| **Cliente**          | `cust_`       | O comprador (pessoa física ou jurídica).                                                       |
| **Recebedor**        | `rec_`        | Quem recebe o dinheiro (você e/ou terceiros num marketplace).                                  |
| **Split**            | `spl_`        | Regra de divisão do valor entre recebedores.                                                   |
| **Wallet**           | `wlt_`        | Saldo virtual de um recebedor, por moeda.                                                      |
| **Saque**            | `wdr_`        | Saque do saldo da carteira para a conta bancária.                                              |
| **Reembolso**        | `rfd_`        | Estorno (total ou parcial) de um pagamento.                                                    |
| **Chargeback**       | `cbk_`        | Contestação do portador junto à adquirente.                                                    |
| **Card**             | `crd_`        | Cartão tokenizado e armazenado para reuso.                                                     |
| **Card token**       | `tok_`        | Token **efêmero** (24h) gerado pelo Tokenizer no navegador. Vira um `crd_` quando salvo.       |
| **Webhook**          | `whk_`        | Endpoint seu que recebe notificações de eventos.                                               |
| **Webhook delivery** | `whd_`        | Uma **entrega** individual de um evento ao seu endpoint (use para deduplicar).                 |
| **Checkout Link**    | `chk_`        | Template de cobrança reutilizável do Checkout hospedado.                                       |
| **Checkout Session** | `cs_`         | Uma compra individual, criada quando alguém abre um Link.                                      |
| **Company**          | `comp_`       | Sua conta/empresa na Z2Pay (aparece como `companyId`).                                         |

<Note>
  No mundo de **assinaturas** existem mais objetos — **plano** (`plan_`), **preço** (`price_`),
  **Assinatura** (`sub_`) e **fatura** (`inv_`). Veja [Assinaturas](/pt-BR/subscriptions/visao-geral).
  Outros prefixos que você verá: documento de chargeback (`cbkd_`), conta bancária (`rba_`) e
  movimentações de carteira (`wtx_`).
</Note>

## Transação × pagamento

Uma transação pode ter **mais de um pagamento** (pagamento combinado — ex.: parte no cartão, parte no
PIX). O `status` da transação é **calculado** a partir dos status dos seus pagamentos:

| Status da transação               | Quando                                                          |
| --------------------------------- | --------------------------------------------------------------- |
| `waiting_payment`                 | Aguardando pagamento (ex.: PIX/boleto emitido, ainda não pago). |
| `paid`                            | Soma dos pagamentos pagos cobre o total.                        |
| `refused`                         | Pagamento recusado pela adquirente.                             |
| `refunded` / `partially_refunded` | Estornado total/parcialmente.                                   |
| `chargeback`                      | Em contestação/contestado.                                      |
| `canceled`                        | Cancelada.                                                      |

A lógica completa de cálculo está em [Transactions](/pt-BR/transactions).

## Recebedor, carteira e saque

* Por padrão, **você** é o recebedor "owner" e recebe 100% do valor (menos as taxas).
* Em um **marketplace**, você cria outros **recebedores** e usa **split** para dividir cada venda.
* O valor recebido entra na **wallet** do recebedor (com saldo `available`, `pending` e `blocked`).
* O recebedor pode então solicitar um **saque** para a conta bancária.

Veja [Split](/pt-BR/splits), [Wallets](/pt-BR/wallets) e
[Valores & Taxas](/pt-BR/valores/visao-geral).