> ## 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.
# Transações
> Como funcionam as transações — itens, pagamentos e o status derivado deles.
A **transação** (`txn_`) reúne **o que** o comprador está pagando (os itens) e **como** está pagando
(os pagamentos). Cada pagamento é uma tentativa por uma forma específica — cartão, boleto ou Pix — e
uma mesma transação pode ter mais de um.
O `status` da transação é **derivado**: você nunca o define. Ele é recalculado a cada mudança nos
pagamentos — é por isso que uma transação com dois pagamentos pode ficar `partially_paid`.
Todas as rotas exigem o header `x-api-key` (sua chave de sandbox). Veja
[Autenticação](/pt-BR/autenticacao). Os exemplos nas páginas de cada endpoint usam a base URL de
sandbox `https://api.sandbox.z2pay.com/v1`.
***
## Endpoints
Cada endpoint tem sua própria página, com os campos aceitos, exemplos e o playground para testar.
| Método | Rota | Descrição |
| ------ | -------------------------- | ---------------------------------------------------------------------------- |
| `GET` | `/transactions` | [Lista paginada de transações, com filtros](/pt-BR/transactions/list) |
| `GET` | `/transactions/:id` | [Busca uma transação com seus pagamentos e itens](/pt-BR/transactions/get) |
| `POST` | `/transactions` | [Cria uma nova transação](/pt-BR/transactions/create) |
| `POST` | `/transactions/:id/refund` | [Estorna todos os pagamentos pagos da transação](/pt-BR/transactions/refund) |
***
## Status da transação
Você nunca define o status da transação — ele é **derivado** dos pagamentos e recalculado sempre que
um deles muda de estado. Com um único pagamento, a transação acompanha o status dele. Com mais de
um, ela resume o conjunto (veja [Quando há mais de um pagamento](#quando-há-mais-de-um-pagamento)).
| Status | O que significa | Quando acontece |
| -------------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `pending` | Sem pagamento confirmado nem aguardando pagamento | Pagamentos criados sem os dados de cobrança, esperando [`POST /transactions/:id/payments/process`](/pt-BR/payments/process) |
| `waiting_payment` | Aguardando o pagador | Pix ou boleto emitido — exige um pagamento nesse status cobrindo o valor da transação |
| `partially_paid` | Parte do valor foi paga, mas não o total | Transação com vários pagamentos em que só parte foi aprovada, sem estorno em andamento |
| `paid` | O valor pago cobre o total | Os pagamentos aprovados somam o valor da transação |
| `refused` | Pagamento recusado pelo emissor | Cartão recusado. Prevalece sobre falha técnica (veja abaixo) |
| `failed` | Falha terminal, sem recusa | Erro no gateway ou expiração do meio de pagamento |
| `canceled` | Cancelada antes da liquidação | Todos os pagamentos ativos foram cancelados sem chegar a ser pagos |
| `waiting_refund` | Estorno solicitado, aguardando processamento | Estorno criado sem aprovação automática, ou estorno de boleto (depende de dados bancários) |
| `partially_refunded` | Parte do valor pago foi estornada | Estorno parcial, ou estorno de um pagamento entre vários |
| `refunded` | Todo o valor pago foi estornado | Todos os pagamentos liquidados foram estornados |
| `chargeback` | Pagamento revertido pelo emissor | O portador contestou a compra e a contestação foi concluída contra você |
| `in_protest` | Contestação em análise | Chargeback aberto e ainda sem desfecho. Veja [Chargebacks](/pt-BR/chargebacks) |
### Quando há mais de um pagamento
Uma transação pode ter vários pagamentos: Pix + cartão, dois cartões, ou uma nova tentativa depois
de uma recusa. Nesses casos, quatro regras explicam o status que você vê.
**`paid` significa que o valor pago cobre o total** — não que todos os pagamentos foram aprovados.
A diferença aparece quando a transação recebe mais do que foi cobrado: o caso mais comum é o
comprador gerar um Pix, desistir e pagar no cartão, e depois acabar pagando o Pix também. Estornar
o excedente mantém a transação `paid`, porque o valor que restou continua cobrindo o total — e ela
segue `paid` inclusive enquanto esse estorno está sendo processado.
**Pagamento incompleto e sem estorno fica `partially_paid`.** Assim que qualquer estorno entra em
cena, a transação passa a refletir o ciclo de estorno (`waiting_refund`, `partially_refunded` ou
`refunded`) em vez de continuar como parcialmente paga — mesmo que parte do dinheiro ainda esteja
retida.
**Recusa prevalece sobre falha técnica.** Se um pagamento foi recusado pelo emissor e outro falhou
por erro do gateway, a transação fica `refused` — a informação acionável para você e para o
comprador é a recusa.
**Pagamentos cancelados não travam o estorno.** Numa transação com Pix cancelado e cartão pago, o
estorno do cartão leva a transação a `refunded`: a parte cancelada é ignorada, porque nunca houve
cobrança ali.
***
## Veja também
Detalhes de cada forma de pagamento dentro da transação.
Estorno de um pagamento específico e estornos parciais.
Gere o `token` do cartão antes de criar a transação.
Configure repasses por pagamento com `split` ou `splitId`.
Cadastre clientes para reusar via `customerId`.
Receba notificações de mudança de status da transação.