Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.troqpay.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Sandbox

O sandbox existe para você validar a integração inteira sem movimentar valores reais. É nele que você confirma se:
  • o checkout é criado do jeito certo
  • o Pix aparece como esperado
  • os webhooks chegam
  • sua conciliação funciona

​
Como identificar respostas de teste

Sempre que você usar uma chave trq_test_, a resposta virá com:
  • livemode: false
  • dados marcados como teste
  • webhooks com livemode: false
O ambiente não muda pela URL. Ele muda pela chave que você usa na requisição.

​
O que vale a pena testar no sandbox

1

Criação do checkout

Confirme se seu backend cria a cobrança, salva checkout.id e relaciona tudo com externalId.
2

Exibição do Pix

Verifique se seu front-end mostra o copyPaste, o QR Code ou o checkout hospedado sem depender do backend a cada refresh.
3

Consulta e reconciliação

Teste GET /v1/checkouts/{checkoutId} para ler o estado mais recente. Salve sempre checkout.id no momento da criação — ele é o ponto de consulta canônico.
4

Recebimento de webhooks

Valide assinatura, responda 2xx rápido e confirme que o mesmo evento não é processado duas vezes.
5

Simular pagamento de teste

No app, abra um checkout de teste e use o botão de simulação de pagamento para disparar o webhook checkout.paid sem precisar pagar de verdade.

​
Onde revisar isso no app

No fluxo mais comum, você usa o app da troqpay para:
  • gerar uma chave trq_test_
  • revisar se está no ambiente certo
  • cadastrar um endpoint de webhook de teste
  • acompanhar a configuração da conta antes de ir para produção

​
Estados que você vai ver com mais frequência

StatusO que significa
PENDINGCheckout criado e aguardando pagamento
PAIDPix confirmado
EXPIREDO prazo da cobrança terminou
CANCELLEDCheckout cancelado

​
O que observar antes de avançar

Dados que precisam bater

checkout.id, externalId, amount e livemode precisam estar salvos e fáceis de localizar nos seus logs.

Pix que precisa aparecer

Seu front-end deve conseguir exibir copyPaste, QR Code ou checkoutUrl sem depender de uma tela manual da troqpay.

Webhook que precisa chegar

Seu endpoint deve validar assinatura, responder 2xx rápido e ignorar duplicidade com segurança.

Ambientes separados

Mantenha teste e produção em chaves, URLs e logs separados desde o início.

​
Checklist antes de ir para produção

  • o checkout é criado sem duplicidade
  • o app consegue renderizar o Pix corretamente
  • o sistema processa checkout.paid
  • a reconciliação usa checkout.id ou externalId
  • seus logs e monitoramento diferenciam teste e produção
Se possível, use uma URL de webhook separada para sandbox. Isso facilita debug, replay e leitura de logs.

​
Próximos passos

Quickstart

Se você ainda não fez a primeira cobrança, volte e execute o fluxo completo.

Webhooks

Aprofunde assinatura, reentregas e o processamento dos eventos.

Produção

Veja o checklist para trocar a chave e subir tráfego real com segurança.

​
Precisa de ajuda para seguir?

Revisar erros

Use a página de erros para interpretar falhas de autenticação, validação e rate limit.

Boas práticas

Veja o que vale a pena salvar, monitorar e validar antes de crescer o uso.

Abrir o app

Gere chaves de teste e mantenha sua configuração de sandbox organizada.