Antes de ir pra produção
Uma lista para conferir antes de receber vendas de verdade. Teste primeiro com a chave gp_test_ (Modo de teste), que não cria Pix de verdade. Com a chave de produção todo Pix é real: faça os testes abaixo com valores pequenos.
Chaves e acesso
- A chave está só em variável de ambiente ou cofre de segredos, nunca no código, no navegador, em app de celular ou no repositório.
- Cada sistema tem a sua chave, com só as permissões de que precisa (transações, conta, saques).
- Os IPs autorizados do seu servidor estão cadastrados em Integrações › API (obrigatório para saques).
- A chave tem data de validade e você sabe como trocá-la sem parar o sistema (cadastre a nova, troque, revogue a antiga). Veja Autenticação.
- O 2FA da conta está ligado (sem ele nem o painel de API abre e o saque é recusado).
- Toda chamada vai por
https://.
Criando cobranças
- O
valoré inteiro, em centavos (nada de97.00). - Toda criação leva
Idempotency-Keyprópria do pedido e você a reutiliza ao repetir. Veja Repetição segura. - Você manda
referenciacom o número do seu pedido e guarda oidda cobrança no pedido. - O CPF, o nome e o e-mail vêm do cliente de verdade: dados inventados são recusados (
422 dados_invalidos). - O seu código trata
422mostrando a mensagem ao usuário e429,500,503repetindo com espera crescente. Veja Erros.
Webhooks
- O webhook está cadastrado com https, escolhendo os eventos de que você precisa. Veja Como funcionam.
- O botão Testar devolveu sucesso. Veja Teste.
- O segredo
whsec_...está guardado com segurança e a assinatura é conferida (com o corpo cru e o limite de 5 minutos). - O seu receptor responde
2xxem até 5 segundos e faz o trabalho pesado depois. - Evento repetido e evento atrasado são ignorados (
idesequencia). Veja Receptor completo. - O acesso é liberado só no
venda.aprovada(ou quando a consulta mostrapago), nunca quando o cliente volta ao seu site. - Você trata
venda.reembolsadaevenda.contestadatirando o acesso.
Rede de segurança
- Existe uma rotina de conciliação que confere as cobranças pendentes e a soma do dia.
- Os limites da API foram considerados: a rotina não faz mais pedidos por minuto do que a chave aguenta. Veja Limites.
- Você tem alerta quando o seu receptor de webhook devolve erro por muito tempo.
Teste ponta a ponta com dinheiro real
- Crie uma cobrança com o valor mínimo permitido (veja Criar cobrança).
- Pague com o seu próprio Pix. Confirme: o webhook
venda.aprovadachegou, o acesso foi liberado uma vez só e a consulta mostrapago. - Peça o reembolso pelo painel e confirme que o acesso foi tirado.
- Deixe uma cobrança expirar e confirme o tratamento do
venda.expirada. - Desligue o seu receptor por alguns minutos, gere uma venda e religue: o aviso deve chegar numa nova tentativa, ou a conciliação deve achar a venda.
Se a chave de produção vazar (apareceu num repositório, num print, numa conversa): revogue na hora em Integrações › API e crie outra. Revogar é imediato.