Pular para o conteúdo principal
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 no Z2Pay e acesso ao ambiente de testes (sandbox). Veja Ambientes.
  • Sua API key de sandbox (z2_chk_sk_... ou z2_psp_sk_...). Veja Autenticação.
1

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://checkout-api.sandbox.z2pay.com/checkout/links \
  -H "x-api-key: z2_chk_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_abc123...",
  "status": "active",
  "url": "https://pay.sandbox.z2pay.com/c/chk_abc123...",
  "createdAt": "2026-06-24T12:00:00.000Z"
}
unitAmount é inteiro em centavos: R$ 49,90 = 4990. Nunca envie float (49.90) — é rejeitado pela validação.
2

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

Abra a url retornada 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”.
3

Confirme o pagamento

Após o pagamento, consulte a transação pela API. O referenceCode/id aparece nos webhooks e na resposta do checkout.
curl https://api.sandbox.z2pay.com/transactions/txn_abc123 \
  -H "x-api-key: z2_psp_sk_suachavedesandbox"
Resposta (200):
{
  "id": "txn_abc123",
  "status": "paid",
  "amount": 4990,
  "currency": "BRL",
  "paidAt": "2026-06-24T12:01:30.000Z"
}
status: "paid" — pagamento aprovado no sandbox.
4

(Recomendado) Receba webhooks

Em produção você não fica consultando o status — você recebe uma notificação a cada mudança. Cadastre um webhook e escute eventos como transaction.paid:
curl -X POST https://api.sandbox.z2pay.com/webhooks \
  -H "x-api-key: z2_psp_sk_suachavedesandbox" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Meu endpoint",
    "url": "https://meusite.com/webhooks/z2pay",
    "events": ["transaction.paid", "transaction.refused"]
  }'
Veja Webhooks para o catálogo de eventos e como validar a assinatura.

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