Checkout Sessions - Z2Pay Developers

Uma Checkout Session (cs_) é uma instância concreta de compra. Diferente do Link (template), ela tem um valor congelado e um estado que progride conforme o comprador interage. O id tem 48 chars hex (192 bits de entropia), seguro para expor em URL.

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 de seller usam o header x-api-key — veja Autenticação.

Endpoints

Método	Rota	Descrição
`POST`	`/checkout/sessions`	Cria uma Session (a partir de Link ou ad-hoc)
`GET`	`/checkout/sessions`	Lista Sessions (paginado)
`GET`	`/checkout/sessions/{id}`	Busca uma Session pelo ID

Para criar Sessions ad-hoc com listagem separada (venda direta), veja também Charges — o atalho /checkout/charges.

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 para a Session. 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.

Criar Session

POST /checkout/sessions

Aceita duas formas, discriminadas pela presença do campo linkId. Retorna 201. Suporta idempotência via header Idempotency-Key (veja Convenções).

Forma A — a partir de um Link

Materializa a Session copiando o snapshot do Link.

linkId

string

obrigatório

ID do CheckoutLink (chk_*). É a presença desse campo que discrimina o body como “a partir de Link”.

customer

object

Pré-preenche os dados do comprador. Veja Customer.

metadata

object

Metadata específico desta Session (sobrepõe o do Link).

curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/sessions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -d '{
    "linkId": "chk_abc123...",
    "customer": {
      "name": "João Silva",
      "email": "joao@example.com",
      "document": "12345678900",
      "documentType": "cpf"
    },
    "metadata": { "order_id": "ord_42", "shop": "loja-principal" }
  }'

Forma B — ad-hoc (sem Link)

Body completo com a config inline. Equivalente ao body de criar Link, com pequenas diferenças: sem name/slug, com customer (pré-preenche o comprador) e com description (exibida na página).

curl -X POST https://checkout-api.sandbox.z2pay.com/checkout/sessions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "payment",
    "currency": "BRL",
    "locale": "pt-BR",
    "items": [{ "name": "Pedido #1234", "quantity": 1, "unitAmount": 8500 }],
    "paymentMethods": {
      "card": { "enabled": true },
      "pix":  { "enabled": true }
    },
    "customer": { "email": "joao@example.com" },
    "successUrl": "https://meu-site.com/obrigado",
    "expirationMinutes": 30,
    "metadata": { "order_id": "ord_42" }
  }'

Os campos de config (items, paymentMethods, branding, splits, requiredFields, customFields, successUrl, cancelUrl, expirationMinutes) seguem exatamente o mesmo schema do Checkout Link.

Resposta (201):

{
  "id": "cs_a1b2c3d4...48hex",
  "tenantId": "ten_xyz...",
  "linkId": "chk_abc123...",
  "status": "created",
  "mode": "payment",
  "currency": "BRL",
  "locale": "pt-BR",
  "config": {
    "items": [{ "...": "..." }],
    "paymentMethods": { "...": "..." },
    "splits": null,
    "branding": { "...": "..." },
    "requiredFields": ["email", "document", "phone"],
    "customFields": [],
    "successUrl": "https://meu-site.com/obrigado",
    "cancelUrl": null
  },
  "customer": { "name": "João Silva", "email": "joao@example.com" },
  "subtotal": 8500,
  "discountTotal": 0,
  "amount": 8500,
  "discounts": null,
  "paymentAttempts": 0,
  "transactionId": null,
  "metadata": { "order_id": "ord_42" },
  "createdAt": "2026-06-24T12:00:00.000Z",
  "updatedAt": "2026-06-24T12:00:00.000Z",
  "openedAt": null,
  "paidAt": null,
  "canceledAt": null,
  "expiresAt": "2026-06-25T12:00:00.000Z",
  "deletedAt": null,
  "version": 0,
  "url": "https://pay.sandbox.z2pay.com/c/cs_a1b2c3d4..."
}

Em Sessions ad-hoc, linkId é null. A url retornada já está pronta para entregar ao comprador.

Erros comuns

HTTP	Code	Quando
`400`	`validation_failed`	Body inválido
`404`	`not_found`	`linkId` não existe ou foi arquivado
`409`	`link_not_active`	Link existe mas está arquivado

Veja Erros para o formato completo.

Objeto Customer

name

string

Nome completo (≤ 255 chars).

string

E-mail (≤ 255 chars). Sempre obrigatório no confirm — ver required fields.

document

string

CPF, CNPJ ou passaporte (6–30 chars; apenas dígitos para CPF/CNPJ).

documentType

string

"cpf", "cnpj" ou "passport".

phone

string

Telefone (≤ 30 chars). Recomendado E.164: +5511999999999.

address

object

Endereço (zipCode, street, number, complement, neighborhood, city, state, country default "BR"). Opt-in: só exigido se "address" estiver em requiredFields.

Listar Sessions

GET /checkout/sessions

Lista paginada de Sessions do tenant.

status

string

Filtra por status (CSV). Ex.: ?status=paid,opened. Valores: created, opened, paying, partially_paid, paid, failed, expired, canceled.

linkId

string

Filtra Sessions de um Link específico.

string

Busca por ID da Session ou nome/email/documento do comprador.

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/sessions \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -d status=paid \
  -d page=1 \
  -d limit=20

Resposta (200): objeto paginado { data, total, page, limit }.

Buscar Session por ID

GET /checkout/sessions/{id}

Retorna a visão completa do seller (inclui tenantId, metadata, transactionId).

curl https://checkout-api.sandbox.z2pay.com/checkout/sessions/cs_a1b2c3d4... \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

Status possíveis: 200 (encontrada) · 404 (não encontrada).

Estados e transições

created → opened → paying → paid          (terminal ✓)
                         → failed → opened  (retry permitido)
                         → expired         (terminal)
                → expired                  (sem chegar a opened)
                → canceled                 (terminal)

opened  → expired                          (timeout sem confirmar)
        → canceled

Tabela de transições válidas

De	Para
`created`	`opened`, `expired`, `canceled`
`opened`	`paying`, `expired`, `canceled`
`paying`	`paid`, `partially_paid`, `failed`, `expired`
`partially_paid`	`paid`, `failed`
`failed`	`opened` (retry), `expired`, `canceled`
`paid`	— (terminal)
`expired`	— (terminal)
`canceled`	— (terminal)

Significado de cada estado

Estado	Significado
`created`	Session criada (via API), comprador ainda não abriu a página
`opened`	Comprador abriu a página de pagamento
`paying`	Comprador clicou em “Pagar”; transação sendo processada pelo gateway
`partially_paid`	Pagamento combinado: ao menos um payment confirmou, mas o agregado ainda não bate com `session.amount` (ex: PIX pago, cartão pendente)
`paid`	Pagamento confirmado. Webhook `checkout.session.payment_succeeded` disparado
`failed`	Pagamento recusado. A Session volta a `opened` automaticamente para permitir retry
`expired`	`expiresAt` atingido sem confirmação
`canceled`	Cancelamento manual (via `POST /charges/{id}/cancel` ou painel)

partially_paid é exclusivo do fluxo combinado. Em pagamento single-method, a Session vai direto de paying para paid ou failed.

Toda Session tem um campo version (inteiro) incrementado a cada transição (optimistic locking). Se duas threads tentarem confirmar a mesma Session, apenas uma vence; a outra recebe session_already_processing ou invalid_status_transition. Você normalmente não precisa se preocupar com isso.

Reconciliação

Toda Session tem um transactionId (preenchido após entrar em paying) que liga a Session ao registro de pagamento na PSP. Use o transactionId para puxar detalhes de processamento (gateway, NSU, autorização, etc.) na API de transações, caso precise para conciliação financeira.

Veja também

Visão geral do Checkout

Conceitos, casos de uso e mapa de endpoints.

Checkout Links

Templates reutilizáveis e schema completo da config.

Charges (venda rápida)

Sessions ad-hoc com listagem separada e cancelamento.

Comprador (página pública)

Como a Session avança de created até paid.

Webhooks

Eventos de mudança de estado da Session.

Erros

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

​Endpoints

​Snapshot imutável

​Criar Session

​Erros comuns

​Objeto Customer

​Listar Sessions

​Buscar Session por ID

​Estados e transições

​Tabela de transições válidas

​Significado de cada estado

​Reconciliação

​Veja também

Visão geral do Checkout

Checkout Links

Charges (venda rápida)

Comprador (página pública)

Webhooks

Erros

Endpoints

Snapshot imutável

Criar Session

Erros comuns

Objeto Customer

Listar Sessions

Buscar Session por ID

Estados e transições

Tabela de transições válidas

Significado de cada estado

Reconciliação

Veja também