Pular para o conteúdo principal
O Checkout do Z2Pay é uma página de pagamento hospedada (Z2Pay-hosted, no estilo Stripe Checkout / Mercado Pago Checkout Pro). 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 pelo Z2Pay (mobile-first, com a sua identidade visual), e você recebe webhooks ao longo de todo o ciclo de vida.
Todos os exemplos desta seção usam as URLs de sandbox (https://checkout-api.sandbox.z2pay.com para a API e https://pay.sandbox.z2pay.com para a página). Em produção, troque para https://checkout-api.z2pay.com 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.

Roteamento entre adquirentes

Basta cadastrar o gateway uma vez no painel.

​
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

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).
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.
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 Charges são um atalho para esse mesmo fluxo, com listagem filtrada só para Sessions sem linkId.
Toda credencial está vinculada a um tenant (sua conta de seller). As listagens são filtradas automaticamente pelo tenant — você nunca vê recursos de outro seller. IDs seguem o padrão com prefixo: chk_ (Link), cs_ (Session), ci_ (item), cmed_ (mídia), rec_ (recipient para splits).

​
Mapa de endpoints

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

​
Recursos do seller (autenticados)

MétodoRotaRecursoO que faz
POST/checkout/linksLinkCria um template de cobrança
GET/checkout/linksLinkLista templates (paginado)
GET/checkout/links/{id}LinkBusca um template pelo ID
PUT/checkout/links/{id}LinkAtualiza um template
DELETE/checkout/links/{id}LinkArquiva (soft-delete) um template
POST/checkout/sessionsSessionCria uma Session (a partir de Link ou ad-hoc)
GET/checkout/sessionsSessionLista Sessions (paginado)
GET/checkout/sessions/{id}SessionBusca uma Session pelo ID
GET/checkout/chargesChargeLista vendas rápidas (Sessions ad-hoc)
POST/checkout/chargesChargeCria uma venda rápida ad-hoc
GET/checkout/charges/{id}ChargeBusca uma venda rápida pelo ID
POST/checkout/charges/{id}/cancelChargeCancela uma venda rápida

​
Endpoints públicos (consumidos pelo navegador do comprador)

MétodoRotaO que faz
GET/public/checkout/{id}Obtém a config pública para renderizar a página
POST/public/checkout/{id}/openedMarca a Session como “aberta pelo comprador”
POST/public/checkout/{id}/confirmConfirma o pagamento (tokenId + dados do comprador)
Você normalmente não chama os endpoints públicos — quem chama é a página de pagamento do Z2Pay. Eles estão documentados em Comprador (página pública) para fins de transparência, ou caso você queira construir um checkout custom em cima da nossa API.

​
Quickstart

Em 3 passos, do zero ao primeiro pagamento.
1

Crie um Checkout Link

curl -X POST https://checkout-api.sandbox.z2pay.com/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_abc123...",
  "status": "active",
  "url": "https://pay.sandbox.z2pay.com/c/chk_abc123...",
  "createdAt": "2026-06-24T12:00:00.000Z"
}
unitAmount é inteiro em centavos: R$ 499,00 = 49900. Nunca envie float (499.00) — é rejeitado pela validação.
2

Compartilhe a URL

A url retornada (https://pay.sandbox.z2pay.com/c/chk_abc123...) é o link de pagamento. Pode ser compartilhada em qualquer canal. Cada vez que alguém abre o link, uma nova CheckoutSession é materializada automaticamente.
3

Receba webhooks

Toda mudança relevante (Session criada, pagamento aprovado, etc.) dispara um webhook para a URL configurada no painel. Veja Webhooks para o catálogo completo de eventos do checkout.

​
Estados da Session (resumo)

created → opened → paying → paid          (terminal ✓)
                         → failed → opened  (retry permitido)
                         → expired         (terminal)
                → canceled                 (terminal)
Os detalhes da máquina de estados estão em Checkout Sessions.

​
Veja também

Checkout Links

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

Checkout Sessions

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

Charges (venda rápida)

Cobrança individual ad-hoc, sem Link.

Comprador (página pública)

Os endpoints que a página de pagamento consome.

Quickstart

Receba um pagamento de teste de ponta a ponta.

Cartões de teste

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