Checkouts Pix
Tudo gira em torno doCheckout.
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
- os dados de liquidação em
USDT
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, o status e o valor ligados à liquidação em USDT.Campos mais importantes ao criar um checkout
| Campo | Tipo | Obrigatório | O que significa |
|---|---|---|---|
amount | inteiro | sim | Valor em centavos de BRL |
currency | string | não | Hoje, use BRL |
description | string | não | Texto para identificar a cobrança |
externalId | string | não | ID do pedido no seu sistema |
expiresIn | inteiro | não | Tempo de expiração em segundos |
settlementCurrency | string | não | Hoje, USDT |
customer | objeto | não | Dados do comprador |
metadata | objeto | não | Campos livres para conciliação |
O que você recebe de volta
Quando o checkout é criado com sucesso, os campos mais importantes da resposta costumam ser:idstatuscheckoutUrlpix.copyPastepix.qrCodeUrlsettlement.currencysettlement.status
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.