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.
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
| Campo | Quando usar |
|---|---|
pix.copyPaste | Quando seu fluxo tem botão de copia e cola |
pix.qrCodeUrl | Quando você quer renderizar o QR Code direto na sua interface |
checkoutUrl | Quando faz mais sentido enviar o comprador para um checkout hospedado |
Campos mais importantes ao criar um checkout
| Campo | Tipo | Obrigatório | O que significa |
|---|---|---|---|
amount | inteiro | sim | Valor em centavos de BRL. Mínimo 1. |
currency | "BRL" | não | Sempre BRL. Padrão BRL. |
description | string | não | Texto livre, 1-255 caracteres. |
externalId | string | não | ID do pedido no seu sistema, 1-255 caracteres. |
expiresIn | inteiro | não | Tempo de expiração em segundos. Entre 60 e 86400. Padrão 1800 (30 minutos). |
customer | objeto | não | Dados do comprador (veja abaixo). |
metadata | objeto | não | Pares chave-valor livres. Apenas valores string. |
Customer (campos de comprador)
O objetocustomer é opcional. Quando você envia, é obrigatório informar name e pelo menos um de email, document ou phone.
| Campo | Tipo | Restrição |
|---|---|---|
name | string | 1-200 caracteres, sempre obrigatório quando customer é enviado |
email | string | formato de e-mail |
document | string | 3-32 caracteres. Não valida CPF/CNPJ — qualquer string nesse intervalo é aceita |
phone | string | 8-32 caracteres |
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
| Campo | Tipo | O que significa |
|---|---|---|
id | string | chk_ + 20 caracteres hex |
livemode | boolean | true para chaves trq_live_; false para trq_test_ |
status | string | PENDING, PAID, EXPIRED ou CANCELLED |
amount | inteiro | Valor em centavos de BRL |
currency | string | Sempre BRL |
description | string | null | O texto livre que você enviou |
externalId | string | null | O ID do seu pedido |
checkoutUrl | string | URL hospedada https://pay.troqpay.com/pay/{id} |
createdAt | ISO 8601 | Quando o checkout foi criado |
expiresAt | ISO 8601 | Quando ele expira (se ainda não foi pago) |
paidAt | ISO 8601 | null | Preenchido quando o status muda para PAID |
customer | objeto | null | { name, email, document } — sem phone |
pix | objeto | { copyPaste, qrCodeUrl } |
settlement | objeto | { currency, status, amount } — amount é string decimal em BRL ou null quando ainda não liquidado |
metadata | objeto | Os pares chave-valor que você enviou |
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
| Status | O que quer dizer |
|---|---|
PENDING | A cobrança foi criada e está aguardando pagamento |
PAID | O pagamento Pix foi confirmado |
EXPIRED | O prazo terminou sem pagamento |
CANCELLED | O checkout foi cancelado |
Fluxo recomendado de integração
Criar o checkout no backend
Gere a cobrança no seu servidor e salve
checkout.id junto do seu identificador interno.Exibir o Pix para o comprador
Use o QR Code, o copia e cola ou o checkout hospedado, dependendo do fluxo do seu produto.
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.