Primeira cobrança em 5 passos

Tudo aqui acontece no ambiente de teste: nenhum dinheiro de verdade se move, e os webhooks chegam ao seu servidor como chegariam em produção.

Os passos

  1. Crie a contaO cadastro é público, no painel. Enquanto a empresa está em cadastro ou em análise, o ambiente de teste já funciona; produção libera depois da aprovação.
  2. Gere uma chave de testeNo painel, em Desenvolvedores › Chaves de API, crie uma chave sk_test_ com charges em write. Criar a chave pede o código do app autenticador, e ela aparece uma única vez: guarde numa variável de ambiente do servidor. Mais em Chaves de API e escopos.
  3. Crie a cobrançaPOST /v1/charges com amount, currency e uma Idempotency-Key. A resposta traz o checkoutUrl e, em attempt.instructions.emv, o PIX copia e cola. Detalhes em Criar cobrança.
  4. Pague no testeAbra o checkoutUrl e use "Simular pagamento" (o mesmo simulador fica no painel, em Desenvolvedores › Ambiente de teste). O código PIX de teste não é aceito por nenhum banco. Veja Ambiente de teste.
  5. Confirme pelo webhook e pela APICadastre um endpoint de teste em Desenvolvedores › Webhooks, confira o X-Signature e trate o charge.paid. Na dúvida, GET /v1/charges/:id mostra o status de agora. Veja Configurar endpoint.

Depois do teste

  • Com o cadastro aprovado, gere uma chave sk_live_. Antes disso, o painel não cria chave de produção, e uma chave sk_live_ de empresa que não está ativa volta 403 MERCHANT_NOT_ACTIVE.
  • Endpoints de webhook são por ambiente: cadastre de novo o de produção, com o segredo novo.
  • Em produção, mande nome e CPF/CNPJ de quem paga: há provedores de PIX que exigem.
  • Libere o pedido pelo webhook ou pela consulta, nunca pelo retorno do cliente ao seu site.

Antes de ir ao ar, vale ler Idempotency-Key e Tentativas e cabeçalhos.