Boas práticas

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 de 97.00).
  • Toda criação leva Idempotency-Key própria do pedido e você a reutiliza ao repetir. Veja Repetição segura.
  • Você manda referencia com o número do seu pedido e guarda o id da 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 422 mostrando a mensagem ao usuário e 429, 500, 503 repetindo 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 2xx em até 5 segundos e faz o trabalho pesado depois.
  • Evento repetido e evento atrasado são ignorados (id e sequencia). Veja Receptor completo.
  • O acesso é liberado só no venda.aprovada (ou quando a consulta mostra pago), nunca quando o cliente volta ao seu site.
  • Você trata venda.reembolsada e venda.contestada tirando 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

  1. Crie uma cobrança com o valor mínimo permitido (veja Criar cobrança).
  2. Pague com o seu próprio Pix. Confirme: o webhook venda.aprovada chegou, o acesso foi liberado uma vez só e a consulta mostra pago.
  3. Peça o reembolso pelo painel e confirme que o acesso foi tirado.
  4. Deixe uma cobrança expirar e confirme o tratamento do venda.expirada.
  5. 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.