> ## 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.

# Pagamentos

> Como funcionam os pagamentos — a tentativa de cobrança dentro de uma transação, o método e o estado de cada uma.

O **pagamento** (`pay_`) é uma tentativa de cobrança dentro de uma transação, por uma forma
específica — cartão, boleto ou Pix. Uma mesma transação pode ter mais de um, e é por isso que todas
as rotas vivem sob `/transactions/:transactionId/payments`.

Você **não cria um pagamento avulso**: ele nasce junto com a transação, no `POST /transactions` —
que exige pelo menos um —, ou quando o comprador troca a forma de pagamento no Checkout. Não existe
rota de criação aqui: os endpoints abaixo consultam, processam e estornam o que a transação já
criou.

<Info>
  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`.
</Info>

***

## 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/:transactionId/payments/:paymentId`        | [Busca um pagamento por ID](/pt-BR/payments/get)            |
| `POST` | `/transactions/:transactionId/payments/process`           | [Processa os pagamentos pendentes](/pt-BR/payments/process) |
| `POST` | `/transactions/:transactionId/payments/:paymentId/refund` | [Estorna um pagamento](/pt-BR/payments/refund)              |

***

## Status do pagamento

O status do pagamento diz o que **aquela tentativa** conseguiu — diferente do status da transação,
que resume o conjunto (veja [Status da transação](/pt-BR/transactions#status-da-transação)). O
estado inicial já depende do método: cartão nasce `pending`, Pix e boleto nascem `waiting_payment`,
porque o QR Code e o boleto são emitidos na própria criação.

| Status               | O que significa                              | Quando acontece                                                                            |
| -------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `pending`            | Criado, ainda não enviado ao gateway         | Pagamento de cartão criado na transação, antes de ser processado                           |
| `waiting_payment`    | Aguardando o pagador                         | Pix ou boleto emitido — o QR Code e a linha digitável saem na criação                      |
| `paid`               | Pago                                         | O gateway confirmou a liquidação                                                           |
| `refused`            | Recusado pelo emissor                        | Cartão negado por limite, dados inválidos ou suspeita de fraude                            |
| `failed`             | Falha técnica, sem recusa                    | Erro no gateway ou no adquirente antes de a cobrança chegar ao emissor                     |
| `canceled`           | Cancelado antes de ser pago                  | Pix ou boleto cancelado, **e também** QR Code vencido ou boleto que passou do vencimento   |
| `replaced`           | Substituído por outra tentativa              | O comprador trocou a forma de pagamento e uma nova tentativa nasceu no lugar               |
| `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 foi estornada                 | Estorno de valor menor que o total do pagamento                                            |
| `refunded`           | Estornado integralmente                      | Todo o valor do pagamento voltou ao comprador                                              |
| `chargeback`         | 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)             |

<Note>
  **Expiração chega como `canceled`.** Pode-se esperar um status `expired` para o Pix que venceu ou o
  boleto que passou da data — ele não existe na prática. Os gateways o convertem para `canceled`
  antes de chegar até você, então um `case 'expired'` no seu código nunca seria executado. Para
  distinguir vencimento de cancelamento ativo, compare `expiresAt` com `canceledAt`.
</Note>

### Quando uma tentativa é substituída

Um pagamento não é editado quando o comprador muda de ideia: a tentativa antiga é encerrada como
`replaced` e uma nova nasce apontada por ela. Três consequências explicam o que você vê.

<Note>
  **Tentativas substituídas não aparecem nas listagens.** Um pagamento `replaced` fica de fora do
  `payments` que vem embutido em [`GET /transactions/:id`](/pt-BR/transactions/get) e em
  [`GET /transactions`](/pt-BR/transactions/list). Para alcançar a tentativa anterior, use o
  `replacedByPaymentId` do pagamento novo em
  [`GET /transactions/:transactionId/payments/:paymentId`](/pt-BR/payments/get), que não filtra por
  status.
</Note>

<Note>
  **Só tentativa em aberto ou malsucedida é substituída.** Um pagamento já pago nunca vira
  `replaced` — para desfazer uma cobrança liquidada existe o [estorno](/pt-BR/refunds), que é outro
  caminho e deixa rastro próprio.
</Note>

<Note>
  **Não existe status `processing` para pagamento.** Ele existe em [reembolsos](/pt-BR/refunds) e em
  [saques](/pt-BR/withdrawals), e a confusão é comum: um pagamento que está sendo processado continua
  `pending` até o gateway responder.
</Note>

***

## Veja também

<CardGroup cols={2}>
  <Card title="Transactions" icon="receipt" href="/pt-BR/transactions">
    O recurso pai, e como o status da transação sai do conjunto de pagamentos.
  </Card>

  <Card title="Reembolsos" icon="rotate-ccw" href="/pt-BR/refunds">
    Como estornar um pagamento, no todo ou em parte.
  </Card>

  <Card title="Tokenizer" icon="key" href="/pt-BR/tokenizer">
    Gere o token de cartão antes de pagar com `credit_card`.
  </Card>

  <Card title="Simular pagamentos (Sandbox)" icon="flask-conical" href="/pt-BR/sandbox/simular">
    Force o desfecho de um Pix ou boleto no ambiente de testes.
  </Card>
</CardGroup>