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

# Boas práticas de checkout

> Use um checklist simples para integrar checkout, webhook e conciliação com mais previsibilidade.

# 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

<CardGroup cols={2}>
  <Card title="checkout.id">
    Use como identificador técnico principal para consulta, suporte e conferência.
  </Card>

  <Card title="externalId">
    Ligue o checkout ao pedido, assinatura, matrícula ou registro do seu sistema.
  </Card>

  <Card title="livemode">
    Separe teste e produção logo na origem dos seus logs, filas e eventos.
  </Card>

  <Card title="requestId e event.id">
    Eles ajudam você a investigar chamadas HTTP e entregas de webhook sem adivinhação.
  </Card>
</CardGroup>

## 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

| Campo           | Uso recomendado                                                   |
| --------------- | ----------------------------------------------------------------- |
| `pix.copyPaste` | Botão de copia e cola                                             |
| `pix.qrCodeUrl` | QR Code na interface                                              |
| `checkoutUrl`   | Fluxo hospedado quando fizer sentido enviar o comprador para fora |
| `expiresAt`     | Aviso de expiração da cobrança                                    |

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

<Steps>
  <Step title="Valide a assinatura">
    Não processe um evento antes de conferir `x-troqpay-signature`.
  </Step>

  <Step title="Responda 2xx rápido">
    Faça o ack da entrega e deixe o trabalho pesado para uma fila interna.
  </Step>

  <Step title="Evite duplicidade">
    Guarde `event.id` e trate reentregas sem efeitos colaterais.
  </Step>

  <Step title="Concilie com contexto">
    Use `checkout.id`, `externalId`, `requestId`, `livemode` e `settlement` para fechar a leitura do fluxo.
  </Step>
</Steps>

## Prefixos de ID que você vai ver

Cada recurso público tem um prefixo estável. Guarde isso no seu sistema:

| Prefixo  | Recurso                     | Forma             |
| -------- | --------------------------- | ----------------- |
| `chk_`   | Checkout                    | 20 caracteres hex |
| `evt_`   | Evento de webhook           | 24 caracteres hex |
| `req_`   | Identificador de requisição | 24 caracteres hex |
| `plink_` | Link de pagamento           | 16 caracteres hex |

Veja o [Glossário](/glossary) para a lista completa de termos.

## Erros comuns que valem prevenir

<CardGroup cols={2}>
  <Card title="Misturar ambientes">
    Não use a mesma URL, chave ou leitura de logs para teste e produção.
  </Card>

  <Card title="Não salvar IDs suficientes">
    Sem `checkout.id` e `externalId`, suporte e reconciliação ficam muito mais difíceis.
  </Card>

  <Card title="Confirmar pagamento só no front-end">
    A confirmação final precisa acontecer pelo backend, de preferência via webhook.
  </Card>

  <Card title="Ignorar expiração">
    Se o checkout expirar, seu sistema precisa lidar com isso sem assumir pagamento pendente para sempre.
  </Card>
</CardGroup>

## Próximos passos

<CardGroup cols={3}>
  <Card title="Checkouts Pix" href="/flows/checkouts-pix">
    Revise o objeto principal da API e o ciclo de vida dos estados.
  </Card>

  <Card title="Webhooks" href="/flows/webhooks">
    Aprofunde assinatura, reentregas e resposta do endpoint.
  </Card>

  <Card title="Produção" href="/production">
    Confira o checklist antes de usar a integração com clientes reais.
  </Card>
</CardGroup>

## Precisa de ajuda para seguir?

<CardGroup cols={3}>
  <Card title="Quickstart" href="/quickstart">
    Volte ao caminho mais curto se quiser comparar o seu fluxo com o exemplo base.
  </Card>

  <Card title="Erros" href="/flows/errors">
    Use a página de erros para interpretar status HTTP, `code` e `requestId`.
  </Card>

  <Card title="Abrir o app" href="https://app.troqpay.com">
    Revise chaves, ambiente e configuração da conta direto no app da TroqPay.
  </Card>
</CardGroup>