Boas práticas de checkout
Você não precisa de uma arquitetura complicada para integrar a troqpay com segurança. Se o seu checkout estiver bem modelado, os webhooks estiverem organizados e seus logs tiverem o contexto certo, a maior parte da integração fica previsível.O que vale a pena salvar desde o início
checkout.id
Use como identificador técnico principal para consulta, suporte e conferência.
externalId
Ligue o checkout ao pedido, assinatura, matrícula ou registro do seu sistema.
livemode
Separe teste e produção logo na origem dos seus logs, filas e eventos.
requestId e event.id
Eles ajudam você a investigar chamadas HTTP e entregas de webhook sem adivinhação.
Checklist rápido para o backend
- gere checkout apenas pelo backend
- use
Idempotency-Keynas criações - salve
checkout.idjunto do seu identificador interno - confirme pagamento pelo backend, nunca só pela tela do comprador
- trate webhooks como
at least once
O que mostrar para o comprador
| Campo | Uso recomendado |
|---|---|
pix.copyPaste | Botão de copia e cola |
pix.qrCodeUrl | QR Code na interface |
checkoutUrl | Fluxo hospedado quando fizer sentido enviar o comprador para fora |
expiresAt | Aviso de expiração da cobrança |
Boas práticas para webhook e conciliação
Erros comuns que valem prevenir
Misturar ambientes
Não use a mesma URL, chave ou leitura de logs para teste e produção.
Não salvar IDs suficientes
Sem
checkout.id e externalId, suporte e reconciliação ficam muito mais difíceis.Confirmar pagamento só no front-end
A confirmação final precisa acontecer pelo backend, de preferência via webhook.
Ignorar expiração
Se o checkout expirar, seu sistema precisa lidar com isso sem assumir pagamento pendente para sempre.
Próximos passos
Checkouts Pix
Revise o objeto principal da API e o ciclo de vida dos estados.
Webhooks
Aprofunde assinatura, reentregas e resposta do endpoint.
Produção
Confira o checklist antes de usar a integração com clientes reais.
Precisa de ajuda para seguir?
Quickstart
Volte ao caminho mais curto se quiser comparar o seu fluxo com o exemplo base.
Erros
Use a página de erros para interpretar status HTTP,
code e requestId.Abrir o app
Revise chaves, ambiente e configuração da conta direto no app da troqpay.