Skip to main content

​
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-Key nas criações
  • salve checkout.id junto do seu identificador interno
  • confirme pagamento pelo backend, nunca só pela tela do comprador
  • trate webhooks como at least once
  • se você consulta saldo pelo backend, valide também GET /v1/balance em sandbox antes de subir; saques são uma operação de produção

​
O que mostrar para o comprador

​
Boas práticas para webhook e conciliação

1

Valide a assinatura

Não processe um evento antes de conferir x-troqpay-signature.
2

Responda 2xx rápido

Faça o ack da entrega e deixe o trabalho pesado para uma fila interna.
3

Evite duplicidade

Guarde event.id e trate reentregas sem efeitos colaterais.
4

Concilie com contexto

Use checkout.id, externalId, requestId, livemode e settlement para fechar a leitura do fluxo.

​
Prefixos de ID que você vai ver

Cada recurso público tem um prefixo estável. Guarde isso no seu sistema: Veja o Glossário para a lista completa de termos.

​
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.