Checkouts Pix
Quando você cria um checkout, a TroqPay te devolve tudo o que você precisa para cobrar com Pix e acompanhar a cobrança depois. Se você entender bem esse objeto, o resto da integração fica muito mais simples. É nele que você encontra:- o valor cobrado em BRL
- os dados do Pix para o comprador
- o status da cobrança
- os metadados do seu pedido
- o objeto
settlementcom a liquidação em BRL
O que um checkout resolve
Cobrança
Você cria a cobrança em BRL e recebe os dados necessários para exibir o Pix.
Conciliação
Você usa
id, externalId e metadata para ligar a cobrança ao seu sistema.Acompanhamento
Você acompanha o status por webhook e pode consultar a API depois, se quiser confirmar o estado da cobrança.
Liquidação
O objeto
settlement mostra a moeda (BRL), o status e o valor da liquidação. Saques usam um fluxo próprio em produção.O que você normalmente salva
checkout.id
É o identificador técnico da cobrança e o melhor ponto de consulta pelo backend.
externalId
Use para ligar o checkout ao pedido, matrícula, assinatura ou venda do seu sistema.
amount e currency
Eles te ajudam a validar se a cobrança criada bate com o que o comprador deveria pagar.
livemode
Use para não misturar teste e produção em logs, filas e relatórios.
O que mostrar para o comprador
Campos mais importantes ao criar um checkout
Customer (campos de comprador)
O objetocustomer é opcional. Quando você envia, é obrigatório informar name e pelo menos um de email, document ou phone.
phone é aceito no envio mas não volta na resposta do checkout (nem no payload do webhook). Se você precisa do telefone do comprador no seu sistema, salve-o do seu lado antes de criar o checkout.Resposta do checkout
Códigos de criação
A criação de checkout devolve dois status diferentes dependendo do contexto:201 Created— primeira vez que essa requisição é processada200 OK— reentrega idempotente (mesmaIdempotency-Key, mesmo corpo)
Ciclo de vida do checkout
Fluxo recomendado de integração
1
Criar o checkout no backend
Gere a cobrança no seu servidor e salve
checkout.id junto do seu identificador interno.2
Exibir o Pix para o comprador
Use o QR Code, o copia e cola ou o checkout hospedado, dependendo do fluxo do seu produto.
3
Processar os webhooks
Trate
checkout.paid como o evento que confirma o pagamento no seu sistema.4
Consultar quando precisar confirmar
Se você quiser conferir o estado mais recente da cobrança, consulte
GET /v1/checkouts/{checkoutId}.Quando usar consulta e quando usar webhook
Use webhook no fluxo do dia a dia
Use webhook no fluxo do dia a dia
É o melhor caminho para atualizar pedido, liberar acesso e registrar pagamento em tempo real.
Use consulta para conferência e suporte
Use consulta para conferência e suporte
A consulta é ótima para investigar casos pontuais e ler o estado atual do checkout.
Não use só a tela do cliente para confirmar pagamento
Não use só a tela do cliente para confirmar pagamento
O estado final da cobrança deve ser confirmado no seu backend, nunca apenas pelo front-end.
Próximos passos
Precisa de ajuda para seguir?
Boas práticas
Veja o que vale a pena salvar, monitorar e revisar antes de crescer o uso.
Revisar erros
Use essa página quando a API rejeitar um payload ou um status não bater com o esperado.
Abrir o app
Gere chaves, acompanhe sua conta e mantenha o ambiente sob controle.