Pular para o conteúdo principal
As Charges são um atalho para criar Sessions ad-hoc (sem Link). Use quando o seu caso é cobrança individual — um pedido específico, uma fatura avulsa — e não um link divulgado em massa. Tecnicamente, /checkout/charges cria as mesmas Checkout Sessions que /checkout/sessions ad-hoc, mas a listagem é filtrada para mostrar apenas Sessions sem linkId — deixando o dashboard mais limpo para fluxos de venda direta. Além disso, oferece um endpoint de cancelamento.
Os exemplos usam o sandbox: API em https://checkout-api.sandbox.z2pay.com e página em https://pay.sandbox.z2pay.com. Em produção, use https://checkout-api.z2pay.com e https://pay.z2pay.com. Requisições usam o header x-api-key — veja Autenticação.

​
Endpoints

MétodoRotaDescrição
GET/checkout/chargesLista vendas rápidas (Sessions ad-hoc)
POST/checkout/chargesCria uma venda rápida ad-hoc
GET/checkout/charges/{id}Busca uma venda rápida pelo ID
POST/checkout/charges/{id}/cancelCancela uma venda rápida

​
Criar charge

POST /checkout/charges
Cria uma Session ad-hoc com configuração inline. O body é idêntico ao do POST /checkout/sessions na forma ad-hoc — mesmo schema de items, paymentMethods, branding, splits, customer, etc. Retorna 201 com a Session criada e a url pronta para enviar. Suporta idempotência via header Idempotency-Key. 
curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/charges \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{
    "items": [{ "name": "Consultoria 1h", "quantity": 1, "unitAmount": 30000 }],
    "paymentMethods": { "pix": { "enabled": true } },
    "customer": { "name": "Cliente X", "email": "x@example.com" }
  }'
A resposta é uma CheckoutSession (com linkId: null) e a url para compartilhar pelo seu canal.

​
Listar charges

GET /checkout/charges
Lista paginada de Sessions ad-hoc (sem linkId) do tenant.
​
status
string
Filtra por status (CSV). Valores: created, opened, paying, partially_paid, paid, failed, expired, canceled.
​
search
string
Busca por ID da Session ou customer (nome, email, documento).
​
page
number
padrão:"1"
Número da página (≥ 1).
​
limit
number
padrão:"20"
Itens por página (1–100).
curl -G https://checkout-api.sandbox.z2pay.com/checkout/charges \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -d status=paid \
  -d page=1 \
  -d limit=20

​
Buscar charge por ID

GET /checkout/charges/{id}
Idêntico a GET /checkout/sessions/{id} — retorna a visão completa da Session ad-hoc. 
curl https://checkout-api.sandbox.z2pay.com/checkout/charges/cs_a1b2c3d4... \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Status possíveis: 200 (encontrada) · 404 (não encontrada).

​
Cancelar charge

POST /checkout/charges/{id}/cancel
Move a Session para status canceled. Permitido apenas se o status atual for created, opened ou failed. Retorna 200. Suporta idempotência. 
curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/charges/cs_a1b2c3d4.../cancel \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Status possíveis: 200 (cancelada) · 404 (não encontrada) · 409 (session_not_cancellable — status atual não permite cancelamento, ex. paid).
Não é possível cancelar uma Session já paga (paid) ou em processamento (paying). A tentativa retorna 409 session_not_cancellable. Veja Erros.

​
Exemplo: cobrança individual recorrente

Cenário comum: enviar uma fatura mensal por boleto, com customer pré-preenchido e validade longa. 
{
  "mode": "payment",
  "currency": "BRL",
  "locale": "pt-BR",
  "items": [{ "name": "Cobrança fatura jan/2026", "quantity": 1, "unitAmount": 25000 }],
  "paymentMethods": { "boleto": { "enabled": true, "dueDateDays": 7 } },
  "customer": {
    "name": "João Silva",
    "email": "joao@example.com",
    "document": "12345678900",
    "documentType": "cpf"
  },
  "metadata": { "invoice_id": "inv_2026_01_joao" },
  "expirationMinutes": 10080
}
O customer já vem preenchido (o comprador não digita de novo) e a Session expira em 7 dias (10080 min). Envie a url retornada pelo seu canal (e-mail, WhatsApp).
Para cobrança recorrente de verdade (planos, renovação automática, faturas geradas pelo sistema), veja Assinaturas — Charges são para cobranças avulsas montadas por você.

​
Veja também

Checkout Sessions

O recurso por baixo das Charges: estados, schema e listagem.

Checkout Links

Para divulgação em massa, prefira um Link.

Comprador (página pública)

O que acontece quando o comprador abre a url.

Erros

Formato dos erros e códigos de domínio do checkout.