Quickstart

Vamos receber um pagamento de teste de ponta a ponta usando o Checkout hospedado — o caminho mais rápido, sem precisar lidar com dados de cartão. Tudo acontece no sandbox, então nenhum dinheiro real é movimentado.

Prefere a integração transparente (enviar o pagamento direto pela API)? Veja Transactions depois de terminar este guia.

Pré-requisitos

Uma conta na Z2Pay e acesso ao ambiente de testes (sandbox). Veja Ambientes.
Uma API key secret de sandbox (z2_test_sk_...). A mesma chave vale para todos os produtos, e todos os passos abaixo usam a mesma URL base: https://api.sandbox.z2pay.com/v1. Veja Autenticação.

Crie um link de checkout

Um Checkout Link é um template de cobrança reutilizável. Cada vez que alguém abre a URL, uma nova compra (Session) é criada.

curl -X POST https://api.sandbox.z2pay.com/v1/checkout/links \
  -H "x-api-key: z2_test_sk_suachavedesandbox" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu primeiro produto",
    "items": [
      { "name": "Plano Pro", "quantity": 1, "unitAmount": 4990 }
    ],
    "paymentMethods": {
      "card":   { "enabled": true, "installments": { "maxInstallments": 12 } },
      "pix":    { "enabled": true },
      "boleto": { "enabled": true }
    }
  }'

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$ 49,90 = 4990. Nunca envie float (49.90) — é rejeitado pela validação.

Cadastre um webhook

Antes de pagar, diga à Z2Pay para onde enviar o resultado. Em produção você não fica consultando o status — você recebe uma notificação a cada mudança. Cadastre um endpoint de webhook e escute transaction.paid / transaction.refused:

curl -X POST https://api.sandbox.z2pay.com/v1/webhooks \
  -H "x-api-key: z2_test_sk_suachavedesandbox" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu endpoint",
    "url": "https://meusite.com/webhooks/z2pay",
    "secret": "s3nh4-webhook-sandbox",
    "events": ["transaction.paid", "transaction.refused"]
  }'

O secret (mínimo 8 caracteres) faz cada entrega chegar assinada (X-Webhook-Signature) — recomendamos sempre usar um. Veja Webhooks para o catálogo de eventos e como validar a assinatura.

Sem um endpoint público à mão? Use um serviço de inspeção de webhooks durante o teste — ou siga sem este passo e acompanhe pelo Dashboard no passo 4.

Abra a URL e pague com um cartão de teste

Abra a url retornada no passo 1 no navegador. Você verá a página de pagamento hospedada do Z2Pay.Use o gerador abaixo para criar um número de cartão válido que será aprovado:→ Gerar cartão de testePreencha:

Número: o cartão gerado (cenário “Aprovado”).
Validade: qualquer data futura, ex. 12/30.
CVV: qualquer, ex. 123.
Nome/dados do comprador: qualquer valor válido.

Para testar uma recusa, gere um cartão com o cenário “Cartão recusado”.

Receba o webhook e consulte a transação

No Checkout hospedado, a compra vira uma transação (txn_...) no servidor — esse id não é devolvido na hora para o navegador (a página pública é mascarada por segurança). Ele chega no webhook que você cadastrou no passo 2:

data.id é o id da transação (txn_...).
data.referenceCode é o id da Session do checkout (cs_...), preenchido automaticamente pela Z2Pay — use-o para saber de qual compra o evento fala.

Alternativa sem webhook: durante o desenvolvimento, veja a transação recém-criada no Dashboard do sandbox.Com o id em mãos, consulte a transação:

curl https://api.sandbox.z2pay.com/v1/transactions/txn_fauvgc0ymmb9pne13uldzjpkr \
  -H "x-api-key: z2_test_sk_suachavedesandbox"

Resposta (200):

{
  "id": "txn_fauvgc0ymmb9pne13uldzjpkr",
  "status": "paid",
  "currency": "BRL",
  "items": [{ "description": "Plano Pro", "quantity": 1, "amount": 4990 }],
  "paidAt": "2026-06-24T12:01:30.000Z"
}

status: "paid" — pagamento aprovado no sandbox.

A página pública do Checkout (pay.sandbox.z2pay.com) não expõe o id da transação nem campos internos. Para saber o resultado de forma programática, use webhooks — não tente adivinhar o txn_ a partir do chk_/cs_.

Próximos passos

Cartões e cenários de teste

Todos os cartões que passam e que falham, com gerador.

API direta (Transactions)

Crie e processe pagamentos sem o checkout hospedado.

Assinaturas

Cobrança recorrente, planos e faturas.

Split de pagamentos

Divida o valor entre vários recebedores.

Começar aqui

Sandbox & Testes

Pré-requisitos

Próximos passos

Cartões e cenários de teste

API direta (Transactions)

Assinaturas

Split de pagamentos

​Pré-requisitos

​Próximos passos

Cartões e cenários de teste

API direta (Transactions)

Assinaturas

Split de pagamentos

Pré-requisitos

Próximos passos