Checkout: visão geral

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 (transaction.paid, transaction.refused).

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.

O que você NÃO precisa implementar

Página de pagamento (UI)

A interface de checkout é nossa, responsiva e com a sua marca.

Tokenização de cartão (PCI)

Os dados sensíveis do cartão nunca tocam o seu servidor.

PIX, boleto e parcelamento

Toda a lógica de método de pagamento é nossa.

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

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.

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

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.

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.

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

Mapa de endpoints

Todas as requisições usam o header x-api-key. Veja Autenticação.

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

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 — 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).

Quickstart

Em 3 passos, do zero ao primeiro pagamento.

Crie um Checkout Link

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):

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

unitAmount é inteiro em centavos: R$ 499,00 = 49900. Nunca envie float (499.00) — é rejeitado pela validação.

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.

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.

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.

Veja também

Checkout Links

Crie e gerencie templates de cobrança reutilizáveis.

A Session (o objeto)

Instâncias de compra, estados e snapshot imutável.

Charges (venda rápida)

Cobrança individual ad-hoc, sem Link.

Quickstart

Receba um pagamento de teste de ponta a ponta.

Cartões de teste

Cenários de aprovação e recusa no sandbox.

Cobranças

Clientes & Cartões

Checkout

Cobrança recorrente

Split & Recebedores

Webhooks & Eventos

Valores & Taxas

O que você NÃO precisa implementar

Página de pagamento (UI)

Tokenização de cartão (PCI)

PIX, boleto e parcelamento

Casos de uso típicos

Conceitos centrais

Mapa de endpoints

Quickstart

Estados da Session (resumo)

Veja também

Checkout Links

A Session (o objeto)

Charges (venda rápida)

Quickstart

Cartões de teste

​O que você NÃO precisa implementar

Página de pagamento (UI)

Tokenização de cartão (PCI)

PIX, boleto e parcelamento

​Casos de uso típicos

​Conceitos centrais

​Mapa de endpoints

​Quickstart

​Estados da Session (resumo)

​Veja também

Checkout Links

A Session (o objeto)

Charges (venda rápida)

Quickstart

Cartões de teste

O que você NÃO precisa implementar

Casos de uso típicos

Conceitos centrais

Mapa de endpoints

Quickstart

Estados da Session (resumo)

Veja também