Primeiros passos

1. Pegue uma chave de sandbox

No painel, em Integração → Chaves de API, crie uma chave de sandbox (sk_sandbox_…). Ela aparece uma única vez: guarde num cofre de segredos, nunca no código. Chaves de sandbox existem desde a aprovação do cadastro; as de produção (sk_live_…), depois da ativação da unidade.

2. Crie uma cobrança

curl -X POST "https://sandbox.api.exemplo.com.br/v1/charges" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"amount": "149.90", "description": "Pedido 10293", "external_ref": "10293"}'

Ou com um SDK:

import { GatewayPix } from "gateway-pix";
const pix = new GatewayPix(process.env.PIX_API_KEY!);
const charge = await pix.charges.create({ amount: "149.90", description: "Pedido 10293", external_ref: "10293" });

A resposta traz:

• br_code — o Pix Copia e Cola (mostre também como QR Code);
• checkout_url — uma página de pagamento pronta, hospedada por nós, com QR, Copia e Cola, nome e CNPJ do recebedor e confirmação automática. Redirecione o cliente para ela e você não precisa desenhar nada;
• status: "active" e expires_at.

3. Simule o pagamento

No sandbox não existe dinheiro de verdade. Simule o Pix:

curl -X POST "https://sandbox.api.exemplo.com.br/v1/sandbox/charges/ch_…/simulate_payment" \
  -H "Authorization: Bearer $PIX_API_KEY" -H "Idempotency-Key: $(uuidgen)"

A simulação percorre o mesmo caminho da produção: aviso do banco, confirmação do Pix, eventos e webhooks.

4. Receba o webhook e confirme

Cadastre um endpoint (POST /v1/webhook_endpoints) para receber charge.paid. Verifique a assinatura com o SDK (veja Webhooks) e, antes de liberar a mercadoria, confira a cobrança com GET /v1/charges/{id} — o webhook avisa, a consulta confirma.

5. Vá para produção

Troque a chave por uma sk_live_…. A URL muda sozinha nos SDKs (api. em vez de sandbox.api.). Nada mais muda.