> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Do zero ao primeiro pagamento aprovado no sandbox, em poucos minutos.

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.

<Note>
  Prefere a integração transparente (enviar o pagamento direto pela API)? Veja
  [Transactions](/pt-BR/transactions) depois de terminar este guia.
</Note>

## Pré-requisitos

* Uma conta na Z2Pay e acesso ao **ambiente de testes** (sandbox). Veja [Ambientes](/pt-BR/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](/pt-BR/autenticacao).

<Steps>
  <Step title="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.

    ```bash theme={null}
    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`):

    ```json theme={null}
    {
      "id": "chk_byd8p3p79re859jpkmr0j65n3",
      "status": "active",
      "url": "https://pay.sandbox.z2pay.com/c/chk_byd8p3p79re859jpkmr0j65n3",
      "createdAt": "2026-06-24T12:00:00.000Z"
    }
    ```

    <Warning>
      `unitAmount` é **inteiro em centavos**: R\$ 49,90 = `4990`. Nunca envie float (`49.90`) — é
      rejeitado pela validação.
    </Warning>
  </Step>

  <Step title="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`:

    ```bash theme={null}
    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](/pt-BR/webhooks/visao-geral) para o catálogo de
    eventos e como validar a assinatura.

    <Tip>
      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.
    </Tip>
  </Step>

  <Step title="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**:

    <a href="/pt-BR/sandbox/cartoes">→ Gerar cartão de teste</a>

    Preencha:

    * **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".
  </Step>

  <Step title="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:

    ```bash theme={null}
    curl https://api.sandbox.z2pay.com/v1/transactions/txn_fauvgc0ymmb9pne13uldzjpkr \
      -H "x-api-key: z2_test_sk_suachavedesandbox"
    ```

    Resposta (`200`):

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

    <Check>
      `status: "paid"` — pagamento aprovado no sandbox.
    </Check>

    <Note>
      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_`.
    </Note>
  </Step>
</Steps>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Cartões e cenários de teste" icon="credit-card" href="/pt-BR/sandbox/cartoes">
    Todos os cartões que passam e que falham, com gerador.
  </Card>

  <Card title="API direta (Transactions)" icon="code" href="/pt-BR/transactions">
    Crie e processe pagamentos sem o checkout hospedado.
  </Card>

  <Card title="Assinaturas" icon="repeat" href="/pt-BR/subscriptions/visao-geral">
    Cobrança recorrente, planos e faturas.
  </Card>

  <Card title="Split de pagamentos" icon="scissors" href="/pt-BR/splits">
    Divida o valor entre vários recebedores.
  </Card>
</CardGroup>