# Meu Rastreio — API de Checkout (referência para modelos de IA)

> Documento em Markdown para agentes e modelos de IA. Versão para pessoas: https://meurastreio.app/pt-BR/api-de-checkout

Cobre por Pix ou cartão pela API do Meu Rastreio: crie checkouts, embuta o widget de pagamento no seu site com o SDK em JavaScript ou pague direto pela API, com status e webhooks.

Base URL: `https://painel.meurastreio.app/api/v1`

## Visão geral

O checkout do Meu Rastreio cobra por **Pix ou cartão de crédito** em nome de **uma filial**, com o provedor de pagamento instalado nela. Você cria a cobrança informando valor, descrição e pagador; o pagamento acontece num widget embutido no seu site ou pela própria API.

| cenário | como fazer | quem vê o cartão |
|---|---|---|
| Site com servidor próprio | O servidor cria o checkout (`POST /checkouts`) e o navegador abre o widget com a `external_reference`. | Só o Meu Rastreio, dentro do widget. |
| Página sem servidor | O SDK cria o checkout e abre o widget numa chamada só (`MeuRastreioCheckout.pay`). | Só o Meu Rastreio, dentro do widget. |
| Tela própria de pagamento (app, totem, sistema) | O seu servidor cria o checkout e paga com `POST /checkouts/{external_reference}/payments`. | O seu servidor e o Meu Rastreio. |

- A `external_reference` é um UUID gerado pelo Meu Rastreio na criação. Ela identifica o checkout em todas as chamadas e no widget.
- Sem `payment_method` na criação, o pagador escolhe entre Pix e cartão no widget (ou você escolhe na chamada de pagamento).
- O status final chega pela consulta, pelos eventos do widget e pelos webhooks. **Libere o que foi vendido só depois de confirmar `PAID` no seu servidor.**

## Requisitos e ativação

Antes da primeira chamada, confira com o administrador da sua conta no Meu Rastreio:

1. O plano da empresa inclui o módulo **Checkout**. Sem ele, a API responde `402 PLAN_WITHOUT_CHECKOUTS`.
2. A filial que vai receber tem uma extensão de pagamento instalada (Asaas ou eRede, na tela **Extensões**). Ela define quais formas de pagamento a filial aceita.
3. Existe uma integração com o canal **API** nessa filial, criada no painel em **Integrações → nova integração**, ativa e com a permissão **Permite criar checkouts?** ligada. Sem a permissão, a API responde `401 CHECKOUT_NOT_ALLOWED`.

> Para usar o token no navegador (SDK), crie uma integração **só para o checkout**, com apenas a permissão de checkout ligada. Dúvidas na ativação: suporte@meurastreio.app.

## Autenticação

Envie o token da integração no cabeçalho `x-api-token` de todas as chamadas da API.

cabeçalho:

```http
x-api-token: 0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9
```

- O token pertence a **uma integração de uma filial**: os checkouts que você cria e consulta com ele são dessa filial.
- Ele aparece na tela da integração, no painel, e não tem validade. Para revogar, desative ou exclua a integração, ou substitua o token.
- Token ausente ou desconhecido responde `401` com `{"message":"Acesso negado"}`.

> **Atenção:** O token é o mesmo das outras rotas da integração. Colocá-lo no navegador expõe tudo o que a integração pode fazer e deixa o visitante definir o valor da cobrança. Quando o valor não pode ser alterado por quem está na página, crie o checkout no seu servidor e mande para o navegador só a `external_reference`.

## Criar um checkout

`POST /checkouts` cria a cobrança e devolve a `external_reference`. Nenhum valor é cobrado nesse momento, exceto quando `payment_method` é `PIX`: aí o QR code já é gerado.

requisição:

```bash
curl -s -X POST "https://painel.meurastreio.app/api/v1/checkouts" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"checkout":{"amount_in_cents":4990,"description":"Plano mensal","payer_address_required":false,"payer":{"name":"Cliente Exemplo","email":"cliente@exemplo.com.br"}}}'
```

### Checkout (`checkout`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `amount_in_cents` | integer | sim | Valor em centavos. Mínimo `100` (R$ 1,00). |
| `description` | string | sim | O que está sendo cobrado. Aparece no widget e na cobrança. Até 200 caracteres. |
| `payment_method` | string | não | `PIX` ou `CREDIT_CARD`. Sem ele, o pagador escolhe entre as formas que a filial aceita. |
| `payer_address_required` | boolean | não | `true` faz o widget pedir o endereço do pagador (para emitir nota, por exemplo). Padrão: `false`. |
| `payer` | object | sim | Quem paga (ver tabela). |

### Pagador (`checkout.payer`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `name` | string | sim | Nome ou razão social. |
| `email` | string | não | E-mail válido. |
| `phone` | string | não | Telefone. |
| `cpf_cnpj` | string | não | CPF ou CNPJ. Obrigatório quando `payment_method` vem preenchido; sem a forma de pagamento, o widget pede o documento. |
| `address` | object | não | Endereço (ver tabela). |

### Endereço (`checkout.payer.address`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `zipcode` | string | sim | CEP, com 8 dígitos (pode vir com máscara). |
| `street` | string | sim | Logradouro. |
| `number` | string | sim | Número. |
| `complement` | string | não | Complemento. |
| `neighborhood` | string | sim | Bairro. |
| `city` | string | sim | Município. |
| `state` | string | sim | UF, com 2 letras. |
| `ibge` | string | não | Código IBGE do município. |

A resposta é `201` com o checkout:

resposta 201:

```json
{
  "checkout": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "status": "CREATED",
    "payment_method": null,
    "amount_in_cents": 4990,
    "currency": "BRL",
    "description": "Plano mensal",
    "checkout_url": "https://painel.meurastreio.app/p/checkout/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "created_at": "2026-11-13T14:00:00.000Z",
    "paid_at": null,
    "expires_at": null,
    "pix": null,
    "card": null,
    "failure": null
  }
}
```

### Checkout na resposta (`checkout`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `external_reference` | string (UUID) | — | Identificador do checkout. |
| `status` | string | — | Ver Status. |
| `payment_method` | string ou null | — | `PIX`, `CREDIT_CARD` ou `null` enquanto o checkout está `CREATED` e o pagador não escolheu. |
| `amount_in_cents` | integer | — | Valor em centavos. |
| `currency` | string | — | Sempre `BRL`. |
| `description` | string | — | Descrição enviada na criação. |
| `checkout_url` | string | — | Página de pagamento hospedada pelo Meu Rastreio, para enviar por link quando não houver widget. Sem `payment_method` na criação, é a página do widget, onde o pagador escolhe a forma de pagamento. |
| `created_at, paid_at, expires_at` | string ou null | — | Datas em ISO 8601 (UTC). `expires_at` é o vencimento do Pix. |
| `pix` | object ou null | — | `{ qr_code_image, qr_code_data, expires_at }` enquanto o Pix aguarda pagamento. `qr_code_image` é um PNG em base64 e `qr_code_data` é o copia e cola. |
| `card` | object ou null | — | `{ last4 }` depois de uma cobrança no cartão. |
| `failure` | object ou null | — | `{ code, message }` do provedor quando o status é `FAILED`. |

> A resposta não traz dados do pagador: o mesmo formato serve para o navegador.

## Consultar o status

| chamada | devolve |
|---|---|
| `GET /checkouts/{external_reference}` | O checkout, no mesmo formato da criação. |
| `GET /checkouts?external_reference=` | O mesmo, pela query string. |

requisição:

```bash
curl -s "https://painel.meurastreio.app/api/v1/checkouts/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9" \
  -H "x-api-token: SEU_TOKEN"
```

resposta 200 (Pix aguardando pagamento):

```json
{
  "checkout": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "status": "PROCESSING",
    "payment_method": "PIX",
    "amount_in_cents": 4990,
    "currency": "BRL",
    "description": "Plano mensal",
    "checkout_url": "https://painel.meurastreio.app/p/checkout/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "created_at": "2026-11-13T14:00:00.000Z",
    "paid_at": null,
    "expires_at": "2026-11-13T15:00:00.000Z",
    "pix": {
      "qr_code_image": "iVBORw0KGgo...",
      "qr_code_data": "00020126580014br.gov.bcb.pix...",
      "expires_at": "2026-11-13T15:00:00.000Z"
    },
    "card": null,
    "failure": null
  }
}
```

- Checkout de outra filial, ou que não existe, responde `404 CHECKOUT_NOT_FOUND`.
- Para acompanhar um pagamento, prefira os webhooks. Se for consultar, espere alguns segundos entre uma consulta e outra.

## Widget de pagamento

O widget é um iframe do Meu Rastreio dentro da sua página. Ele mostra a descrição e o valor, deixa o pagador escolher a forma de pagamento, pede o CPF ou CNPJ (e o endereço, se `payer_address_required`), mostra o Pix ou o formulário do cartão, acompanha o pagamento e mostra o resultado. O pagador não sai do seu site, e os dados do cartão não passam pela sua página.

### Embutido na página

`MeuRastreioCheckout.mount(alvo, opções)` cria o iframe dentro do elemento e devolve `{ iframe, unmount }`. O iframe acompanha a altura do conteúdo sozinho.

HTML:

```html
<div id="pagamento"></div>
<script src="https://painel.meurastreio.app/checkout-widget.js"></script>
<script>
  MeuRastreioCheckout.mount("#pagamento", {
    externalReference: "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    theme: { primary: "#0f5132", accent: "#34c38f", text: "#1b1b1b" },
    onPaid: () => {
      // libere o pedido só depois de confirmar o status no seu servidor
    },
    onFailed: (status) => console.log("pagamento não concluído", status),
    onStatus: (status) => console.log("status", status),
  });
</script>
```

### Drawer lateral ou popup

`MeuRastreioCheckout.open(opções)` abre o widget por cima da página: um drawer lateral (`display: "drawer"`, o padrão) ou um popup central (`display: "modal"`, que vira folha inferior no celular). Fecha no X, no clique fora e no Esc, trava a rolagem da página enquanto está aberto e devolve `{ iframe, close }`.

JavaScript:

```js
const pagamento = MeuRastreioCheckout.open({
  externalReference: "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  display: "drawer", // ou "modal"
  title: "Plano mensal",
  closeLabel: "Fechar",
  onPaid: () => pagamento.close(),
  onClose: () => console.log("pagador fechou o widget"),
});
```

| opção | em | para quê |
|---|---|---|
| `externalReference` | `mount`, `open` | Obrigatória. O checkout a pagar. |
| `theme` | `mount`, `open` | Cores em hexadecimal: `primary` (cabeçalho, botões, abas ativas), `accent` (destaques e avisos) e `text` (texto). O que não for informado fica com a cor padrão. |
| `onStatus(status)` | `mount`, `open` | A cada mudança de status. |
| `onPaid()` | `mount`, `open` | Quando o status vira `PAID`. |
| `onFailed(status)` | `mount`, `open` | Quando termina sem pagamento: `FAILED`, `EXPIRED`, `CANCELED` ou `REFUNDED`. |
| `title` | `mount`, `open` | Título do iframe (acessibilidade) e, no `open`, o texto da barra. Padrão: "Pagamento". |
| `display` | `open` | `drawer` ou `modal`. |
| `closeLabel` | `open` | Rótulo acessível do botão de fechar. Padrão: "Fechar". |
| `onClose()` | `open` | Quando o pagador fecha o widget. |

> **Atenção:** Os eventos do widget servem para a interface. Antes de liberar o que foi vendido, confirme o status no seu servidor com `GET /checkouts/{external_reference}` ou pelo webhook.

- O widget conversa com a sua página por `postMessage`, só com a origem que o carregou. As mensagens não levam dados do pagador nem do cartão.
- Sem widget, você pode mandar o pagador para o `checkout_url`, a página de pagamento hospedada pelo Meu Rastreio.

## SDK em JavaScript

O mesmo script do widget cria e consulta checkouts direto do navegador, com o token da integração. Os nomes ficam em `camelCase` (`amountInCents`, `paymentMethod`, `payerAddressRequired`, `payer.cpfCnpj`), na ida e na volta.

| função | faz | devolve |
|---|---|---|
| `createCheckout({ token, checkout, onState })` | `POST /checkouts`. | Promise com o checkout. |
| `getCheckout({ token, externalReference, onState })` | `GET /checkouts/{external_reference}`. | Promise com o checkout. |
| `pay({ token, checkout, onState, ...opções do open })` | Cria o checkout e abre o widget. | Promise com `{ checkout, widget }`. |

pagar com um clique:

```html
<script src="https://painel.meurastreio.app/checkout-widget.js"></script>
<script>
  const botao = document.querySelector("#pagar");

  botao.addEventListener("click", async () => {
    const { checkout, widget } = await MeuRastreioCheckout.pay({
      token: "SEU_TOKEN",
      checkout: {
        amountInCents: 4990,
        description: "Plano mensal",
        payer: { name: "Cliente Exemplo", email: "cliente@exemplo.com.br" },
      },
      display: "modal",
      onState: ({ status, error }) => {
        botao.disabled = status === "loading";
        if (status === "error") console.error(error.code, error.errors);
      },
      onPaid: () => widget.close(),
    });

    console.log("checkout criado", checkout.externalReference);
  });
</script>
```

consultar:

```js
const checkout = await MeuRastreioCheckout.getCheckout({
  token: "SEU_TOKEN",
  externalReference: "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
  onState: ({ status }) => console.log(status), // "loading", "success" ou "error"
});

console.log(checkout.status, checkout.failure);
```

- `onState` recebe `{ status, checkout, error }`, com `status` igual a `loading`, `success` ou `error`. Serve para desabilitar o botão e mostrar erro.
- O erro é um `Error` com `status` (HTTP), `code` e `errors` (a lista da validação).
- O checkout devolvido tem `pix` (`qrCodeImage`, `qrCodeData`, `expiresAt`), `card` (`last4`) e `failure` (`code`, `message`).
- O SDK não paga sem o widget: no navegador, o pagamento é sempre feito dentro dele.

> **Atenção:** Leia o aviso de **Autenticação**: com o SDK, o token fica visível para quem abre a página. Use uma integração exclusiva, só com a permissão de checkout.

## Criar no servidor e pagar no widget

O caminho recomendado quando o valor não pode ser alterado pelo visitante: o token fica no seu servidor e o navegador só recebe a `external_reference`.

Node.js:

```js
const BASE_URL = "https://painel.meurastreio.app/api/v1";
const TOKEN = process.env.MEU_RASTREIO_TOKEN;

async function call(path, options = {}) {
  const response = await fetch(`${BASE_URL}${path}`, {
    ...options,
    headers: { "x-api-token": TOKEN, "Content-Type": "application/json" },
  });
  const body = await response.json();

  if (!response.ok) throw new Error(`${response.status} ${body.code ?? ""} ${body.message}`);

  return body.checkout;
}

// 1. o seu servidor cria o checkout com o valor que ele mesmo calculou
export async function createCheckout(order) {
  return call("/checkouts", {
    method: "POST",
    body: JSON.stringify({
      checkout: {
        amount_in_cents: order.totalInCents,
        description: `Pedido ${order.number}`,
        payer: { name: order.customerName, email: order.customerEmail },
      },
    }),
  });
}

// 2. o navegador recebe só a external_reference e abre o widget com MeuRastreioCheckout.open

// 3. antes de liberar o pedido, o servidor confirma o status
export async function isPaid(externalReference) {
  const checkout = await call(`/checkouts/${externalReference}`);

  return checkout.status === "PAID";
}
```

## Pagar pela API, sem widget

`POST /checkouts/{external_reference}/payments` paga um checkout a partir da sua própria tela: um app, um totem, um sistema de balcão. No Pix, a resposta traz o QR code para você mostrar; no cartão, o resultado da cobrança.

> **Atenção:** No cartão, o número e o código de segurança passam pelo seu servidor a caminho do Meu Rastreio. Isso coloca o seu sistema no escopo de segurança do PCI DSS. Se você não quer esse compromisso, use o widget.

requisição (Pix):

```bash
curl -s -X POST "https://painel.meurastreio.app/api/v1/checkouts/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9/payments" \
  -H "x-api-token: SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"payment":{"payment_method":"PIX","payer":{"cpf_cnpj":"00000000191"}}}'
```

requisição (cartão):

```json
{
  "payment": {
    "payment_method": "CREDIT_CARD",
    "payer": {
      "cpf_cnpj": "00000000191",
      "email": "cliente@exemplo.com.br",
      "phone": "11999990000",
      "address": {
        "zipcode": "01001000",
        "street": "Praça da Sé",
        "number": "100",
        "neighborhood": "Sé",
        "city": "São Paulo",
        "state": "SP"
      }
    },
    "card": {
      "holder_name": "CLIENTE EXEMPLO",
      "number": "0000000000000000",
      "expiration_month": 12,
      "expiration_year": 2030,
      "security_code": "000"
    }
  }
}
```

### Pagamento (`payment`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `payment_method` | string | sim | `PIX` ou `CREDIT_CARD`. Se o checkout foi criado com a forma definida, precisa ser a mesma. |
| `payer` | object | não | Completa o pagador da criação (ver tabela). |
| `card` | object | no cartão | Dados do cartão (ver tabela). Recusado no Pix. |

### Pagador (`payment.payer`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `name` | string | não | Substitui o nome da criação. |
| `cpf_cnpj` | string | condicional | CPF ou CNPJ. Obrigatório se não veio na criação. |
| `email` | string | não | Usado na cobrança do cartão. |
| `phone` | string | não | Usado na cobrança do cartão. |
| `address` | object | condicional | Mesmo formato da criação. Obrigatório quando o checkout foi criado com `payer_address_required`. No cartão, CEP e número vão para o provedor. |

### Cartão (`payment.card`)

| campo | tipo | obrigatório | regras |
|---|---|---|---|
| `holder_name` | string | sim | Nome impresso no cartão. |
| `number` | string | sim | Número, de 13 a 19 dígitos. Pode vir com espaços. |
| `expiration_month` | integer | sim | Mês de validade, de 1 a 12. |
| `expiration_year` | integer | sim | Ano de validade com 4 dígitos. |
| `security_code` | string | sim | Código de segurança, com 3 ou 4 dígitos. |

A resposta é `200` com o checkout atualizado e `redirect_uri`:

resposta 200 (cartão aprovado):

```json
{
  "checkout": {
    "external_reference": "0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "status": "PAID",
    "payment_method": "CREDIT_CARD",
    "amount_in_cents": 4990,
    "currency": "BRL",
    "description": "Plano mensal",
    "checkout_url": "https://painel.meurastreio.app/p/checkout/0b6f6a1e-5c1d-4a52-9f0e-3d2a7c41b8e9",
    "created_at": "2026-11-13T14:00:00.000Z",
    "paid_at": "2026-11-13T14:01:12.000Z",
    "expires_at": null,
    "pix": null,
    "card": {
      "last4": "0000"
    },
    "failure": null
  },
  "redirect_uri": null
}
```

- **Pix**: o status fica `PROCESSING` e `pix` traz o QR code e o copia e cola. Mostre os dois ao pagador e acompanhe pela consulta ou pelo webhook. Chamar de novo com `PIX` devolve o mesmo QR code enquanto ele não vencer.
- **Cartão aprovado**: `PAID`. **Recusado**: `FAILED`, com o motivo em `failure`. A recusa é uma resposta `200`, não um erro HTTP, e o checkout não aceita outra tentativa: crie um novo.
- **Cartão em análise**: `PROCESSING`. O resultado chega pela consulta ou pelo webhook.
- `redirect_uri` vem preenchido quando o provedor exige autenticação do pagador fora da sua tela (3DS). Abra o endereço para o pagador concluir. Nos outros casos é `null`.
- Bandeira não aceita (`CARD_BRAND_NOT_ACCEPTED`) é recusada antes da cobrança: o checkout continua `CREATED` e pode ser pago com outro cartão.
- Os dados do cartão não são gravados no Meu Rastreio.

## Status

| status | significado | final |
|---|---|---|
| `CREATED` | Criado e aguardando o pagamento. No checkout sem forma de pagamento definida, o pagador ainda vai escolher. | não |
| `PROCESSING` | Pix gerado aguardando o pagamento, ou cobrança no cartão em andamento. | não |
| `PAID` | Pago. | sim |
| `FAILED` | Cartão recusado ou falha no provedor. O motivo vem em `failure`. | sim |
| `EXPIRED` | O Pix venceu sem pagamento. | sim |
| `CANCELED` | Cancelado antes do pagamento. | sim |
| `REFUNDED` | Pago e depois estornado ou contestado. | sim |

Um pagamento confirmado nunca volta para trás, exceto por estorno (`PAID` → `REFUNDED`).

## Webhooks

Em vez de consultar o status em laço, o seu sistema pode ser avisado quando um checkout é criado ou muda de status. Os webhooks são **habilitados sob solicitação**: escreva para suporte@meurastreio.app informando a filial, a URL que vai receber as chamadas e quais eventos você quer.

| evento | quando é enviado |
|---|---|
| `CHECKOUT_CREATED` | Checkout criado. |
| `CHECKOUT_UPDATED` | Mudança de status: pago, recusado, vencido, cancelado ou estornado. |

- Cada evento habilitado gera uma chamada `POST` para a sua URL, com `Content-Type: application/json`.
- O corpo é o objeto do checkout, direto na raiz do JSON, com nomes em `camelCase` (`externalReference`, `status`, `paymentMethod`, `amountInCents`, `paidAt`…), diferentes dos da API.
- Responda com status `2xx`. Em caso de falha, o envio é tentado até **3 vezes**, com espera crescente entre as tentativas.

> **Atenção:** As chamadas **não têm cabeçalho de assinatura**. Peça ao suporte para configurar um cabeçalho personalizado com um segredo seu (por exemplo `x-webhook-secret`) e recuse chamadas sem ele. Use sempre uma URL HTTPS.

> Trate o webhook como aviso: o mesmo evento pode chegar mais de uma vez. Use `externalReference` e `status` para decidir o que fazer e, na dúvida, consulte o checkout pela API.

## Limites de uso

| limite | valor | como funciona |
|---|---|---|
| Requisições por minuto | 120 por IP | Vale para todas as rotas da API somadas, contadas pelo IP de origem. |
| Valor mínimo | R$ 1,00 | `amount_in_cents` a partir de `100`. |
| Vencimento do Pix | configurado na filial | O padrão é 1 hora. Vencido, o checkout vai para `EXPIRED`. |

Passou do limite de requisições, a resposta é `429` e o cabeçalho `Retry-After` diz quantos segundos esperar.

## Erros

O corpo de erro traz `code`, para o seu código decidir o que fazer, e `message`, para leitura de pessoas. A validação traz também `errors`, com cada problema encontrado.

resposta 422:

```json
{
  "code": "VALIDATION_ERROR",
  "message": "Dados inválidos",
  "errors": [
    "payment.card.number deve ter de 13 a 19 dígitos",
    "payment.card.expiration_month must be less than or equal to 12"
  ]
}
```

| status | code | quando acontece |
|---|---|---|
| 401 | — | Token ausente ou desconhecido. O corpo é `{"message":"Acesso negado"}`, sem `code`. |
| 401 | `INTEGRATION_DISABLED` | A integração do token foi desativada pelo administrador. |
| 401 | `CHECKOUT_NOT_ALLOWED` | A integração do token está sem a permissão **Permite criar checkouts?**. |
| 402 | `PLAN_WITHOUT_CHECKOUTS` | O plano da empresa não inclui o checkout. |
| 404 | `CHECKOUT_NOT_FOUND` | Checkout não encontrado na filial do token. |
| 405 | `METHOD_NOT_ALLOWED` | Método HTTP não aceito pela rota. |
| 409 | `CHECKOUT_ALREADY_PROCESSED` | O checkout já foi pago, recusado, cancelado ou está em processamento. |
| 409 | `CHECKOUT_EXPIRED` | O checkout venceu. |
| 422 | `VALIDATION_ERROR` | Corpo fora do formato. `errors` lista cada problema. |
| 422 | `INVALID_PAYER` | Pagador sem nome ou com CPF/CNPJ inválido, ou endereço incompleto quando ele é exigido. |
| 422 | `INVALID_PAYMENT_METHOD` | Forma de pagamento diferente da definida na criação, ou que a filial não aceita. |
| 422 | `CARD_BRAND_NOT_ACCEPTED` | A bandeira do cartão não é aceita pelo provedor da filial. Nada foi cobrado. |
| 422 | `NO_PAYMENT_PROVIDER_AVAILABLE` | A filial não tem extensão de pagamento que aceite essa forma. |
| 422 | `PAYMENT_PROCESSING_FAILED` | O provedor não gerou o Pix. O checkout fica `FAILED`. |
| 429 | — | Limite de requisições. O corpo é `{"message":"TOO_MANY_REQUESTS"}`, com o cabeçalho `Retry-After`. |

- **401 e 402**: pare e avise uma pessoa. O problema é de token ou plano; insistir não resolve.
- **409**: consulte o checkout para saber o status atual antes de qualquer outra ação.
- **422**: corrija o corpo ou o dado apontado em `message` e tente de novo.
- **429**: espere o `Retry-After`.

## Suporte

Dúvidas sobre a API, o widget, a ativação ou os webhooks: suporte@meurastreio.app. Para contratar: oi@meurastreio.app.
