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

# Checkout: visão geral

> Página de pagamento hospedada pela Z2Pay: crie via API, compartilhe a URL e receba o pagamento pronto.

O **Checkout da Z2Pay** é uma **página de pagamento hospedada**: quem serve a tela de pagamento
somos nós, não você. Você cria a configuração via API — itens, métodos aceitos,
branding, splits — e recebe uma **URL pronta** para entregar ao comprador. Ele finaliza o pagamento
numa página servida pela Z2Pay (mobile-first, com a sua identidade visual), e você acompanha o
resultado pelos [webhooks de transação](/pt-BR/webhooks/visao-geral)
(`transaction.paid`, `transaction.refused`).

<Note>
  Todos os exemplos desta seção usam as URLs de **sandbox**
  (`https://api.sandbox.z2pay.com/v1` para a API e `https://pay.sandbox.z2pay.com` para a
  página). Em produção, troque para `https://api.z2pay.com/v1` e `https://pay.z2pay.com`.
</Note>

## O que você NÃO precisa implementar

<CardGroup cols={2}>
  <Card title="Página de pagamento (UI)" icon="app-window">
    A interface de checkout é nossa, responsiva e com a sua marca.
  </Card>

  <Card title="Tokenização de cartão (PCI)" icon="shield-check">
    Os dados sensíveis do cartão nunca tocam o seu servidor.
  </Card>

  <Card title="PIX, boleto e parcelamento" icon="qr-code">
    Toda a lógica de método de pagamento é nossa.
  </Card>
</CardGroup>

## Casos de uso típicos

* **Loja online** — cria uma `CheckoutSession` por pedido e redireciona o cliente.
* **Link de pagamento divulgável** (bio do Instagram, post, WhatsApp) — cria um `CheckoutLink`
  (template persistente) e compartilha a URL. Cada clique vira uma `CheckoutSession` nova.
* **Cobrança individual** — chama `/checkout/charges` (venda rápida ad-hoc) e envia a URL direto pelo
  WhatsApp ou e-mail.
* **Marketplace** — usa `splits` para dividir o valor entre múltiplos recebedores automaticamente.

## Conceitos centrais

<AccordionGroup>
  <Accordion title="CheckoutLink (template persistente) — chk_">
    Um **template de cobrança reutilizável**. Você define uma vez (itens, preço, métodos, branding) e
    divulga a URL N vezes — cada acesso de comprador gera uma `CheckoutSession` independente. IDs
    começam com `chk_`.

    **Quando usar:** divulgar um produto/serviço em massa, link "vitrine" para a bio do Instagram,
    página de captura, etc.
  </Accordion>

  <Accordion title="CheckoutSession (instância de compra) — cs_">
    Uma **tentativa concreta de compra**. Tem um valor congelado (snapshot do Link no momento da
    criação), um comprador (parcial ou completo) e um estado que progride: `created` → `opened` →
    `paying` → `paid`. IDs começam com `cs_` (48 chars hex = 192 bits de entropia, seguro para expor
    em URL).
  </Accordion>

  <Accordion title="Snapshot imutável">
    Ao criar uma Session a partir de um Link, **todos** os dados (items, preço, splits, branding,
    métodos) são copiados. Editar o Link depois **não afeta** Sessions já criadas. Isso garante que o
    que o comprador viu na hora do pagamento é exatamente o que ele paga.
  </Accordion>

  <Accordion title="Session ad-hoc / venda rápida">
    Você não é obrigado a criar um Link antes — pode criar uma Session "ad-hoc" (sem `linkId`), com
    toda a config inline. Útil para cobranças únicas/personalizadas. As **vendas rápidas** são um atalho para
    esse mesmo fluxo, com listagem filtrada só para Sessions sem `linkId`. Dá para reaproveitar a
    identidade visual de um Link existente numa venda rápida — veja
    [Espelhar a config de um Link](/pt-BR/checkout/charges#espelhar-a-config-de-um-link-numa-venda-rápida).
  </Accordion>

  <Accordion title="Preço errado num Link já divulgado">
    Corrigir o Link **não** muda as Sessions que já existem — é o mesmo snapshot que protege o
    comprador de ver um valor e pagar outro. Quem abrir a partir daí já pega o preço novo; o que
    fica exposto são as Sessions abertas nas últimas 24 horas (o prazo padrão de validade).

    Para fechar essa janela, liste as Sessions abertas daquele Link com
    `GET /checkout/sessions?linkId=chk_...&status=created,opened,filling` e cancele cada uma em
    [`POST /checkout/charges/{id}/cancel`](/pt-BR/checkout/charges/cancel). Quem estiver com a
    página aberta recebe "sessão expirada" e recomeça com o valor certo — ninguém é cobrado acima
    do que viu na tela.
  </Accordion>
</AccordionGroup>

## Mapa de endpoints

Todas as requisições usam o header `x-api-key`. Veja [Autenticação](/pt-BR/autenticacao).

| Método   | Rota                            | Recurso      | O que faz                                                         |
| -------- | ------------------------------- | ------------ | ----------------------------------------------------------------- |
| `POST`   | `/checkout/links`               | Link         | Cria um template de cobrança                                      |
| `GET`    | `/checkout/links`               | Link         | Lista templates (paginado)                                        |
| `GET`    | `/checkout/links/{id}`          | Link         | Busca um template pelo ID                                         |
| `PATCH`  | `/checkout/links/{id}`          | Link         | Atualiza um template                                              |
| `DELETE` | `/checkout/links/{id}`          | Link         | Arquiva um template (muda o status, não apaga)                    |
| `POST`   | `/checkout/charges`             | Venda rápida | **Cria uma venda rápida** (cobrança individual ad-hoc)            |
| `GET`    | `/checkout/charges`             | Venda rápida | Lista vendas rápidas                                              |
| `GET`    | `/checkout/charges/{id}`        | Venda rápida | Busca uma venda rápida pelo ID                                    |
| `POST`   | `/checkout/charges/{id}/cancel` | Venda rápida | Cancela uma venda rápida                                          |
| `POST`   | `/checkout/sessions`            | Session      | Cria uma Session server-to-server (a partir de um Link ou ad-hoc) |
| `GET`    | `/checkout/sessions`            | Session      | Lista Sessions (de Link e ad-hoc)                                 |
| `GET`    | `/checkout/sessions/{id}`       | Session      | Busca uma Session pelo ID                                         |

<Info>
  **A Session (`cs_`) é o objeto que representa uma tentativa de compra**, e ela nasce de três
  formas: materializada sozinha quando o comprador abre um Link, criada por uma venda rápida
  (`/checkout/charges`), ou criada por você em
  [`POST /checkout/sessions`](/pt-BR/checkout/links/session-create) — informando um `linkId` ou a
  configuração inteira. Use esta última quando quiser a `url` de pagamento em mãos **antes** de
  redirecionar o comprador. Veja
  [a Session (o objeto)](/pt-BR/checkout/links#do-link-à-session).
</Info>

## Quickstart

Em 3 passos, do zero ao primeiro pagamento.

<Steps>
  <Step title="Crie um Checkout Link">
    ```bash theme={null}
    curl -X POST https://api.sandbox.z2pay.com/v1/checkout/links \
      -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "Curso de Backend",
        "items": [
          { "name": "Curso de Backend — vitalício", "quantity": 1, "unitAmount": 49900 }
        ],
        "paymentMethods": {
          "card":   { "enabled": true, "installments": { "maxInstallments": 12, "freeInstallments": 3 } },
          "pix":    { "enabled": true, "expiresIn": 3600 },
          "boleto": { "enabled": true, "dueDateDays": 3 }
        }
      }'
    ```

    Resposta (`201`):

    ```json theme={null}
    {
      "id": "chk_byd8p3p79re859jpkmr0j65n3",
      "status": "active",
      "url": "https://pay.sandbox.z2pay.com/c/chk_byd8p3p79re859jpkmr0j65n3",
      "createdAt": "2026-06-24T12:00:00.000Z"
    }
    ```

    <Warning>
      `unitAmount` é **inteiro em centavos**: R\$ 499,00 = `49900`. Nunca envie float (`499.00`) — é
      rejeitado pela validação.
    </Warning>
  </Step>

  <Step title="Compartilhe a URL">
    A `url` retornada (`https://pay.sandbox.z2pay.com/c/chk_byd8p3p79re859jpkmr0j65n3`) é o link de pagamento. Pode ser
    compartilhada em qualquer canal. Cada vez que alguém abre o link, uma nova `CheckoutSession` é
    materializada automaticamente.
  </Step>

  <Step title="Receba webhooks">
    O resultado do pagamento chega pelos **eventos de transação**: escute
    `transaction.paid` (aprovado) e `transaction.refused` (recusado), cadastrando o seu endpoint via
    `POST /webhooks` (`api.sandbox.z2pay.com/v1`). Os eventos `checkout.session.*` são
    internos e **não são assináveis** — não existe webhook de "Session criada". Veja
    [Webhooks](/pt-BR/webhooks/visao-geral).
  </Step>
</Steps>

## Estados da Session (resumo)

```
created → opened → paying → paid                     (terminal ✓)
                         → partially_paid → paid     (combinado: completou)
                                          → failed   (combinado: expirou parcial)
                         → failed → opened           (retry permitido)
                         → expired                   (terminal)
                → canceled                           (terminal)
```

A máquina completa tem 10 estados — inclui ainda `filling` (comprador preenchendo o formulário) e
`abandoned` (inatividade, recuperável). Os detalhes estão em
[Estados da Session](/pt-BR/checkout/links#estados-da-session).

## Veja também

<CardGroup cols={2}>
  <Card title="Checkout Links" icon="link" href="/pt-BR/checkout/links">
    Crie e gerencie templates de cobrança reutilizáveis.
  </Card>

  <Card title="A Session (o objeto)" icon="receipt" href="/pt-BR/checkout/links#do-link-à-session">
    Instâncias de compra, estados e snapshot imutável.
  </Card>

  <Card title="Charges (venda rápida)" icon="zap" href="/pt-BR/checkout/charges">
    Cobrança individual ad-hoc, sem Link.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/pt-BR/quickstart">
    Receba um pagamento de teste de ponta a ponta.
  </Card>

  <Card title="Cartões de teste" icon="credit-card" href="/pt-BR/sandbox/cartoes">
    Cenários de aprovação e recusa no sandbox.
  </Card>
</CardGroup>