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

> Entenda como o checkout organiza a cobrança Pix do começo ao fim.

# 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 `settlement` com a liquidação em BRL

## O que um checkout resolve

<CardGroup cols={2}>
  <Card title="Cobrança">
    Você cria a cobrança em BRL e recebe os dados necessários para exibir o Pix.
  </Card>

  <Card title="Conciliação">
    Você usa `id`, `externalId` e `metadata` para ligar a cobrança ao seu sistema.
  </Card>

  <Card title="Acompanhamento">
    Você acompanha o status por webhook e pode consultar a API depois, se quiser confirmar o estado da cobrança.
  </Card>

  <Card title="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.
  </Card>
</CardGroup>

## O que você normalmente salva

<CardGroup cols={2}>
  <Card title="checkout.id">
    É o identificador técnico da cobrança e o melhor ponto de consulta pelo backend.
  </Card>

  <Card title="externalId">
    Use para ligar o checkout ao pedido, matrícula, assinatura ou venda do seu sistema.
  </Card>

  <Card title="amount e currency">
    Eles te ajudam a validar se a cobrança criada bate com o que o comprador deveria pagar.
  </Card>

  <Card title="livemode">
    Use para não misturar teste e produção em logs, filas e relatórios.
  </Card>
</CardGroup>

## 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 `100` (R\$ 1,00).                                 |
| `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 `900` 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 objeto `customer` é 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                                                                     |

<Info>
  `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.
</Info>

## 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`, `REFUNDED`, `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 é processada
* `200 OK` — reentrega idempotente (mesma `Idempotency-Key`, mesmo corpo)

Trate ambos como sucesso. O corpo é igual.

## 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                       |
| `REFUNDED`  | Estado terminal após o estorno de um checkout `PAID` |
| `EXPIRED`   | O prazo terminou sem pagamento                       |
| `CANCELLED` | O checkout foi cancelado                             |

## Fluxo recomendado de integração

<Steps>
  <Step title="Criar o checkout no backend">
    Gere a cobrança no seu servidor e salve `checkout.id` junto do seu identificador interno.
  </Step>

  <Step title="Exibir o Pix para o comprador">
    Use o QR Code, o copia e cola ou o checkout hospedado, dependendo do fluxo do seu produto.
  </Step>

  <Step title="Processar os webhooks">
    Trate `checkout.paid` como o evento que confirma o pagamento no seu sistema.
  </Step>

  <Step title="Consultar quando precisar confirmar">
    Se você quiser conferir o estado mais recente da cobrança, consulte `GET /v1/checkouts/{checkoutId}`.
  </Step>
</Steps>

## Quando usar consulta e quando usar webhook

<AccordionGroup>
  <Accordion title="Use webhook no fluxo do dia a dia">
    É o melhor caminho para atualizar pedido, liberar acesso e registrar pagamento em tempo real.
  </Accordion>

  <Accordion title="Use consulta para conferência e suporte">
    A consulta é ótima para investigar casos pontuais e ler o estado atual do checkout.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Próximos passos

* [Fazer o quickstart](/quickstart)
* [Configurar webhooks](/flows/webhooks)
* [Entender a liquidação em BRL](/flows/liquidacao)
* [Consultar o saldo](/flows/saldo)

## Precisa de ajuda para seguir?

<CardGroup cols={3}>
  <Card title="Boas práticas" href="/flows/boas-praticas-checkout">
    Veja o que vale a pena salvar, monitorar e revisar antes de crescer o uso.
  </Card>

  <Card title="Revisar erros" href="/flows/errors">
    Use essa página quando a API rejeitar um payload ou um status não bater com o esperado.
  </Card>

  <Card title="Abrir o app" href="https://app.troqpay.com">
    Gere chaves, acompanhe sua conta e mantenha o ambiente sob controle.
  </Card>
</CardGroup>