# Checkto

> Checkto é uma plataforma brasileira de pagamentos via API. Permite receber por Pix, boleto, cartão de crédito e criptomoeda, criar assinaturas recorrentes (Pix, cartão e cripto), gerar links de Checkout hospedado, solicitar reembolsos, consultar transações, assinaturas, saldo e dados do produtor, gerar depósitos Pix e dividir valores entre contas (split). A API é REST + JSON, autenticada por duas chaves em header, e opera primariamente em BRL. Este arquivo contém a documentação completa: todos os endpoints, campos, enums, payloads de webhook e exemplos. Não é necessário consultar nenhuma outra fonte.

Base URL: `https://app.checkto.com.br/api/v1`
Suporte: suporte@app.checkto.com.br

## Regras essenciais (leia antes de integrar)

- **Autenticação por dois headers**, não Bearer token: `x-public-key: <chave-publica>` e `x-secret-key: <chave-secreta>`.
- **Valores em reais (decimal), nunca em centavos.** `100.50` significa R$ 100,50.
- **Rotas do gateway levam o prefixo `/gateway`.** Ex.: `POST https://app.checkto.com.br/api/v1/gateway/pix/receive`. Exceções sem o prefixo: `/ping` e `/utils/exchange-rates`.
- **`amount` é o total que o cliente paga**: `soma(products[n].price * products[n].quantity) + shippingFee + extraFee - discount`.
- **`identifier` é o ID do seu sistema**, gerado por você, único por transação. Volta na resposta e no webhook (`transaction.identifier`). Use-o para reconciliar.
- **`callbackUrl` deve ser uma URL fixa**, a mesma para todas as transações. URLs dinâmicas por pedido estouram o limite de 20 webhooks por integração.
- **Nunca faça polling.** Consultas repetidas retornam `TOO_MANY_REQUESTS`. Receba as atualizações por webhook; consulte apenas para reconciliação ou quando o webhook não chegar (após ~5 minutos).
- **Firewall geográfico**: requisições de origens não confiáveis recebem uma **página HTML 403**, não JSON. Origens aceitas: Brasil, Estados Unidos, Portugal e outros locais considerados seguros. Não existe whitelist de IP.
- **Erro 504 em saque não significa falha.** Aguarde o webhook antes de repetir, para não duplicar a operação.
- Seu endpoint de webhook deve responder **HTTP 2XX**; caso contrário a notificação é reenviada.
- Sempre HTTPS. Requisições HTTP sem criptografia não são suportadas.

---

# 1. Introdução

A API da Checkto permite recebimentos via Pix, boleto ou cartão, além de saques, transferências, consulta de saldos e históricos de pagamento. É construída sobre os princípios REST, utilizando HTTPS em todas as requisições.

URL base de todas as requisições:

```
https://app.checkto.com.br/api/v1
```

Códigos de resposta HTTP usados:

- `200 OK` — a requisição foi bem-sucedida.
- `201 Created` — a requisição foi bem-sucedida e um novo recurso foi criado.
- `400 Bad Request` — erros de validação ou dados inválidos.
- `401 Unauthorized` — falta de autenticação ou token inválido.
- `404 Not Found` — recurso não encontrado.
- `500 Internal Server Error` — erro interno no servidor.

**Como reportar um bug:** contate o suporte técnico pelo formulário do site ou por suporte@app.checkto.com.br, com passos para reproduzir o erro e as mensagens recebidas.

**Como garantir a segurança das requisições:** use sempre HTTPS, gere corretamente o token de autenticação a partir de suas chaves, nunca exponha as chaves publicamente e regenere-as no dashboard quando necessário.

---

# 2. Autenticação

Para usar a API você precisa de credenciais válidas: uma **chave pública** e uma **chave secreta**.

## Como obter as credenciais

1. Acesse o painel de controle: entre no seu perfil na dashboard da Checkto.
2. Navegue até a seção API, na aba de integrações do menu lateral.
3. Clique em **Gerar credenciais**.
4. Copie e guarde as chaves em local seguro. **As chaves não são exibidas novamente.**

## Como autenticar

Envie os dois headers em toda requisição autenticada:

```
x-public-key: SUA_CHAVE_PUBLICA
x-secret-key: SUA_CHAVE_SECRETA
```

Exemplo ilustrativo com Axios (a rota abaixo não é real, serve apenas para mostrar os headers):

```js
await axios.get('https://app.checkto.com.br/api/v1', {
  headers: {
    'x-public-key': 'SUA_CHAVE_PUBLICA_AQUI',
    'x-secret-key': 'SUA_CHAVE_PRIVADA_AQUI',
  },
});
```

## Boas práticas de segurança

- Nunca compartilhe suas chaves privadas; trate-as como senhas.
- Utilize sempre HTTPS.
- Monitore regularmente o acesso à sua API para detectar atividade suspeita.
- Armazene as chaves em gerenciadores de senhas ou armazenamento criptografado. Nunca as coloque no código-fonte ou em repositórios.

## Perguntas frequentes sobre credenciais

- **Perdi minha chave privada.** Contate o suporte técnico para gerar uma nova chave privada e substitua a antiga em todas as suas aplicações.
- **Suspeito que minhas credenciais foram comprometidas.** Contate o suporte técnico imediatamente para proteger a conta.
- **Existem limites de requisição?** Os limites dependem do plano contratado. Consulte a seção de gerenciamento de API no painel ou o suporte.

---

# 3. Tratamento de erros

Quando um erro ocorre, a resposta é um objeto JSON no formato:

```json
{
  "statusCode": 500,
  "errorCode": "GATEWAY_INTERNAL_SERVER_ERROR",
  "message": "Mensagem detalhada sobre o erro",
  "details": {
    "campo1": "Detalhes sobre o campo 1",
    "campo2": "Detalhes sobre o campo 2"
  }
}
```

Campos do objeto de erro:

- `statusCode` (number) — código HTTP do erro.
- `errorCode` (string) — código de erro da API, conforme a tabela abaixo.
- `message` (string) — mensagem de erro detalhada.
- `details` (any) — detalhes adicionais, opcional; pode conter qualquer tipo de dado.

## Códigos de erro

| Código de erro | Descrição |
|---|---|
| `GATEWAY_INTERNAL_SERVER_ERROR` | Erro genérico do servidor; algo deu errado no lado do servidor que não foi especificado mais detalhadamente. |
| `GATEWAY_ROUTE_NOT_FOUND` | O recurso solicitado não foi encontrado. |
| `GATEWAY_UNAUTHORIZED` | Falha na autenticação com as credenciais fornecidas. |
| `GATEWAY_COMPANY_NOT_FOUND` | A empresa não foi encontrada. |
| `NOT_FOUND` | O recurso requisitado não foi encontrado. |
| `GATEWAY_INVALID_CREDENTIALS` | As credenciais fornecidas são inválidas. |
| `GATEWAY_NO_CREDENTIALS` | As credenciais não foram fornecidas. |
| `GATEWAY_TRANSACTION_DENIED` | A transação foi negada. |
| `GATEWAY_TRANSACTION_NOT_FOUND` | A transação não foi encontrada. |
| `GATEWAY_INVALID_ARGUMENT` | Um ou mais argumentos da requisição são inválidos. |
| `GATEWAY_PERMISSION_DENIED` | O usuário não possui permissão para acessar o recurso. |
| `GATEWAY_FAILED_PRECONDITION` | A operação foi rejeitada porque o sistema não está no estado necessário para a execução. |
| `GATEWAY_ABORTED` | A operação foi abortada, geralmente por questão de concorrência. |
| `GATEWAY_OUT_OF_RANGE` | O valor de um argumento está fora do intervalo permitido. |
| `GATEWAY_UNIMPLEMENTED` | A operação não está implementada. |
| `GATEWAY_INTERNAL` | Erro interno ao executar a operação. |
| `GATEWAY_UNAVAILABLE` | O serviço não está disponível. |
| `GATEWAY_DATA_LOSS` | Dados críticos foram perdidos devido a um erro. |
| `GATEWAY_UNAUTHENTICATED` | A requisição requer autenticação, mas ela não foi fornecida. |
| `GATEWAY_INVALID_DATA` | Os dados fornecidos são inválidos. |
| `GATEWAY_NO_BODY` | O corpo da requisição não foi fornecido. |
| `GATEWAY_NO_SPLIT_ACCOUNT` | A conta de split não foi encontrada. |
| `GATEWAY_NOT_OWNER` | O usuário não é o proprietário dos recursos. |

## Timeout em saques (erro 504)

Ao receber `504 Gateway Timeout` em uma operação de saque, **não considere automaticamente que o saque falhou**. O 504 indica que a requisição excedeu o tempo limite de resposta, mas o processamento pode ter continuado nos servidores.

Como proceder:

1. **Aguarde os webhooks** — configure e monitore os webhooks para saber o status real da transação.
2. **Não refaça a operação imediatamente** — evite duplicatas; aguarde a confirmação via webhook.
3. **Implemente retry com backoff** — se precisar refazer, aguarde um tempo adequado e use um identificador diferente.
4. **Consulte o status** — use os endpoints de consulta antes de tomar qualquer ação.

---

# 4. Enums (tipos de dados)

## Status de transação (campo `status`)

- `COMPLETED` — Transação concluída
- `PENDING` — Transação pendente
- `FAILED` — Transação falhou
- `REFUNDED` — Transação estornada
- `CHARGED_BACK` — Transação com chargeback

## Status imediato na criação (campo `status` da resposta de criação)

`OK`, `FAILED`, `PENDING`, `REJECTED`, `CANCELED`

Nas respostas de criação, `transactionStatus` traz o status persistido no gateway: `PENDING`, `COMPLETED`, `FAILED`, `REFUNDED`, `CHARGED_BACK`.

## Métodos de pagamento (campo `paymentMethod`)

- `PIX` — Pix
- `BOLETO` — Boleto
- `CREDIT_CARD` — Cartão
- `SPLIT` — Divisão de pagamento
- `TED` — Transferência
- `DYNAMIC` — Dinâmico (outros métodos)
- `CRYPTO` — Criptomoeda
- `CASH_ON_DELIVERY` — Pagamento na entrega

No Checkout hospedado, `settings.paymentMethods` aceita: `PIX`, `CREDIT_CARD`, `BOLETO`, `CRYPTO`, `CASH_ON_DELIVERY`, `GOOGLE_PAY`, `APPLE_PAY`.

## Tipo de compra (campo `purchaseType`)

- `ONCE` — Compra única
- `RECURRING` — Assinatura

## Status de assinatura

`ACTIVE`, `INACTIVE`, `CANCELED`

## Periodicidade de assinatura (`periodicityType` / `intervalType`)

`DAYS`, `WEEKS`, `MONTHS`, `YEARS`

## Status de transferência/saque

`PENDING`, `PROCESSING`, `TRANSFERRING`, `COMPLETED`, `CANCELED`

Status de cada envio (`sents[].status`): `PROCESSING`, `COMPLETED`, `FAILED`

## Status de solicitação de reembolso

`PENDING`, `COMPLETED`, `CANCELED`

## Status de chargeback

`PENDING`, `SOLVED`, `DENIED`, `NOT_FOUND`, `DEFENDING`

Tipo do alerta: `CHARGEBACK`, `MED`. Origem: `NATIONAL`, `INTERNATIONAL`.

## Permissões de credencial de API (campo `permissions`)

- `PRODUCER_DATA` — Consultar dados da conta / ver saldo
- `PRODUCER_TRANSACTIONS` — Criar / consultar transações
- `PRODUCER_WITHDRAWS` — Criar / consultar saques
- `PRODUCER_CHECKOUT` — Criar checkouts

## Moedas aceitas (campo `currency`)

`AOA`, `ARS`, `BRL`, `CAD`, `COP`, `EUR`, `GBP`, `JPY`, `MXN`, `MZN`, `USD`, `CNY`, `SAR`, `AUD`, `NZD`, `ZAR`, `PHP`, `NGN`, `GHS`, `MYR`, `ZMW`, `MUR`, `JMD`, `KES`, `TZS`, `TTD`, `GYD`, `LKR`, `FJD`, `SEK`, `BBD`, `GTQ`, `SCR`, `AWG`, `SZL`, `AED`, `ILS`, `NAD`, `THB`, `XCD`, `TRY`, `HNL`, `PGK`, `CRC`, `PAB`, `WST`, `LSL`, `INR`, `BDM`, `BNB`, `BTC`, `ETH`, `USDC`, `USDT`

Valor padrão: `BRL`.

## Redes de criptomoeda (campo `crypto.network`)

`BDM_DIGITAL`, `BSC`, `ETH`, `BTC`, `POLYGON`, `TRON`, `BASE`, `TON`, `SOLANA`

## Tipo de oferta do Checkout (`offer.offerType`)

`INTERNATIONAL`, `NATIONAL`, `UNDEFINED`

## Idiomas do Checkout (`offer.lang`)

`pt-BR`, `en`, `es`, `pt`, `fr`, `ja`, `zh`, `ar`, `it`, `de`, `all` (padrão: `all`)

## Documentos aceitos no Checkout (`settings.acceptedDocs`)

`CPF`, `CNPJ` (padrão: `CPF`)

## Tipo de conta bancária (`payoutAccount.accountType`)

`CHECKING`, `SAVINGS`, `CRYPTO_WALLET`

---

# 5. Cálculo do valor da transação

O valor total de uma transação (`amount`) é composto por 4 partes:

- `shippingFee` — frete da transação, em reais
- `extraFee` — outras taxas (ex.: parcelamento), em reais
- `discount` — desconto da transação, em reais
- `products[n].price` — preço do produto, em reais
- `products[n].quantity` — quantidade do produto

Some o preço de cada produto multiplicado pela quantidade, adicione frete e taxas extras e subtraia o desconto:

```js
const products = [
  { price: 10, quantity: 2 },
  { price: 20, quantity: 1 }
]

const shippingFee = 5   // Taxa de frete
const extraFee = 20     // Taxa de parcelamento
const discount = 5      // Desconto

const totalProducts = products.reduce((acc, product) => {
  return acc + product.price * product.quantity
}, 0)
// Soma dos Produtos = 40

// Valor total da venda, que o cliente vai pagar.
// Esse é o valor que você deve enviar no campo 'amount'
const amount = totalProducts + shippingFee + extraFee - discount
// Resultado final: R$ 60.00
```

---

# 6. Split de pagamentos

Nas rotas de pagamento (Receber Pix, Receber Cartão e Receber Boleto) você pode incluir o campo opcional `splits` para dividir automaticamente o valor da transação entre contas:

```json
{
  "splits": [
    { "producerId": "cm1234", "amount": 30.00 },
    { "producerId": "cm9876", "amount": 20.00 }
  ]
}
```

Cada objeto do array contém:

- `producerId` (string, obrigatório) — ID da conta que receberá o split. Essa pessoa deve copiar o próprio ID no painel dela e repassar para quem está criando o split.
- `amount` (number, obrigatório) — valor em BRL a ser repassado para essa conta.

O somatório dos `amount` dentro de `splits` não pode exceder o valor total da transação. Sem `splits`, 100% do valor vai para a conta principal que está realizando o pagamento.

---

# 7. Webhooks

Webhooks notificam automaticamente o seu sistema sobre eventos. São enviados como requisições **HTTP POST** com JSON para as URLs configuradas.

## 7.1. Webhooks cadastrados no painel

Configurados diretamente no painel da Checkto. Indicados para produtores que usam a plataforma para gerenciar vendas e querem uma configuração simples e centralizada, sem integrar via API.

Como configurar:

1. Acesse o painel da Checkto.
2. Navegue até **Configurações > Webhooks**.
3. Clique em **Criar** e preencha:
   - **Título do Webhook** — nome para identificação interna.
   - **URL alvo do disparo** — URL que receberá as notificações.
   - **Produtos** — produtos para os quais o webhook deve disparar.
   - **Eventos** — eventos a monitorar (Transação criada, Transação paga, etc.).

Após a criação é gerado um **token exclusivo**, usado para validar que as notificações recebidas vieram da Checkto.

## 7.2. Webhooks via API

Configurados pelo produtor através de chamadas à API. Indicados para desenvolvedores e empresas com plataforma própria que precisam de integração robusta e notificações em tempo real.

Como configurar:

1. Faça uma requisição POST para a rota do método desejado enviando `callbackUrl` como parâmetro.
2. No retorno, além dos dados de pagamento, virá um `webhookToken` para validar as futuras notificações.

A Checkto cria um registro interno para manter o histórico das notificações. Sempre que houver atualização na transação (ex.: pagamento de um Pix), uma notificação é enviada para o `callbackUrl`.

## 7.3. Limite de webhooks

Existe um limite de **20 webhooks por integração** — uma trava de segurança para evitar uso incorreto do `callbackUrl`.

O erro `{"error": "Você pode criar no máximo 20 webhooks"}` ocorre quando se envia um `callbackUrl` diferente para cada transação:

```js
// ERRADO — cria um webhook novo por transação
{ "callbackUrl": "https://meusite.com/pedido/123", ... }
{ "callbackUrl": "https://meusite.com/pedido/456", ... }
{ "callbackUrl": "https://meusite.com/pedido/789", ... }
```

Incluir o ID interno na URL é desnecessário, porque ele já é devolvido no corpo do webhook e na resposta da API. Envie o campo `identifier` com o ID do seu sistema; ele retorna na resposta da criação e em `transaction.identifier` no webhook.

```js
// CORRETO — URL fixa + identifier
{ "callbackUrl": "https://meusite.com/integracao/checkto", "identifier": "pedido-123", ... }
{ "callbackUrl": "https://meusite.com/integracao/checkto", "identifier": "pedido-456", ... }
{ "callbackUrl": "https://meusite.com/integracao/checkto", "identifier": "pedido-789", ... }
```

No webhook recebido:

```json
{
  "event": "TRANSACTION_PAID",
  "transaction": {
    "id": "abc123",
    "identifier": "pedido-123",
    "status": "COMPLETED"
  }
}
```

## 7.4. Resposta aos webhooks

Após processar um webhook, seu endpoint deve retornar status HTTP **2XX**. Outros códigos indicam que o webhook não foi aceito e a notificação será reenviada.

## 7.5. Webhook de Transação (pagamentos)

Eventos disponíveis (campo `event`):

- `TRANSACTION_CREATED` — Transação criada
- `TRANSACTION_PAID` — Transação paga
- `TRANSACTION_CANCELED` — Transação cancelada
- `TRANSACTION_REFUNDED` — Transação estornada
- `TRANSACTION_CHARGED_BACK` — Transação contestada

Todos os eventos compartilham a mesma estrutura de payload:

**Campos de nível raiz**

- `event` (enum) — nome do evento disparado. Sempre retornado.
- `token` (string) — token para validar a autenticidade da notificação. Sempre retornado.
- `offerCode` (string | null) — código da oferta (vendas via checkout interno). Sempre retornado.
- `checkoutUrl` (string) — URL exata do checkout acessada pelo cliente, contendo todos os search params (sessão, oferta, afiliação e UTMs). Vazia quando não há sessão de checkout associada. Sempre retornado.
- `client` (object) — dados do cliente. Sempre retornado.
- `transaction` (object) — dados da transação. Sempre retornado.
- `trackProps` (object) — propriedades de rastreamento. Sempre retornado.

**`client`**

- `id` (string) — identificador do cliente
- `name` (string) — nome do cliente
- `email` (string) — e-mail do cliente
- `phone` (string | null) — telefone do cliente
- `cpf` (string | null) — CPF do cliente
- `cnpj` (string | null) — CNPJ do cliente
- `address` (object | null) — endereço do cliente (nulo para infoprodutos):
  - `country` (string) — código do país (ex.: BR)
  - `zipCode` (string) — CEP no formato 12345-678
  - `state` (string) — código do estado (ex.: SP)
  - `city` (string) — cidade
  - `neighborhood` (string) — bairro
  - `street` (string) — rua
  - `number` (string) — número
  - `complement` (string | null) — complemento

**`transaction`**

- `id` (string) — identificador da transação
- `identifier` (string | null) — seu identificador do cliente
- `status` (enum) — `COMPLETED`, `FAILED`, `PENDING`, `REFUNDED`, `CHARGED_BACK`
- `paymentMethod` (enum) — `CREDIT_CARD`, `PIX`, `BOLETO`, e demais métodos
- `originalAmount` (number) — valor na moeda original do cliente
- `amount` (number) — valor na moeda de recebimento do produtor
- `commissionAmount` (number) — valor líquido a ser recebido
- `originalCurrency` (string) — moeda original do cliente (ex.: USD, BRL)
- `currency` (string) — moeda de recebimento do produtor (ex.: BRL)
- `exchangeRate` (number | null) — taxa de câmbio (quando a moeda original não for BRL)
- `installments` (number) — número de parcelas
- `createdAt` (date) — data e hora de criação da cobrança (ISO 8601)
- `payedAt` (date | null) — data e hora do pagamento (ISO 8601)
- `pixInformation` (object | null) — apenas para pagamentos via Pix:
  - `id` (string) — id interno do pixInformation
  - `qrCode` (string) — QR Code do Pix
  - `endToEndId` (string | null) — ID end-to-end do Pix (preenchido quando pago)
- `boletoInformation` (object | null) — apenas para pagamentos via boleto:
  - `transactionId` (string | null) — id da transação associada ao boleto
  - `id` (string)
  - `barcode` (string) — código de barras
  - `digitableLine` (string)
  - `pdfUrl` (string | null)
  - `instructions` (string | null)
  - `createdAt` (date | null) — ISO 8601
  - `updatedAt` (date | null) — ISO 8601
- `subscription` (object | null) — nulo quando não for cobrança recorrente:
  - `id` (string) — identificador da assinatura
  - `identifier` (string | null) — seu identificador da assinatura
  - `cycle` (number) — número sequencial da cobrança (1ª cobrança = 1, 2ª = 2, ...)
  - `startAt` (date) — data e hora de início da assinatura (ISO 8601)
  - `intervalType` (enum) — `DAYS`, `WEEKS`, `MONTHS`, `YEARS`
  - `intervalCount` (number) — frequência da cobrança
  - `status` (enum) — `ACTIVE`, `INACTIVE`, `CANCELED`
- `orderItems` (array) — itens do pedido:
  - `id` (string) — identificador do item
  - `price` (number) — valor total do item
  - `product` (object): `id` (string), `name` (string), `externalId` (string | null — seu identificador do produto em vendas via API)

**`trackProps`**

`utm_id`, `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `fbc` (Facebook Click ID), `fbp` (Facebook Browser ID), `ip`, `country`, `user_agent`, `zip_code`, `city`, `state`.

**Exemplo de payload — Transação criada**

```json
{
  "event": "TRANSACTION_CREATED",
  "token": "91ln4vqfkr",
  "offerCode": "ABCK181",
  "checkoutUrl": "https://checkout.teste.com/checkout/ckxyz123?session=01890a5d-ac96-774b-bcce-b302099a8057&offer=ABCK181&code=AFILIADO123&utm_source=facebook&utm_medium=cpc",
  "client": {
    "id": "ovu1cb4iwl6oc0m5",
    "name": "John Doe",
    "email": "jondoe@gmail.com",
    "phone": "(11) 9 8888-7777",
    "cpf": "123.456.789-10",
    "cnpj": null,
    "address": {
      "country": "BR",
      "zipCode": "01304-000",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Consolação",
      "street": "Rua Augusta",
      "number": "6312",
      "complement": "6 andar"
    }
  },
  "transaction": {
    "id": "1pned18asp",
    "status": "COMPLETED",
    "paymentMethod": "CREDIT_CARD",
    "originalCurrency": "USD",
    "originalAmount": 20,
    "amount": 100,
    "currency": "BRL",
    "exchangeRate": 5,
    "installments": 3,
    "createdAt": "2026-09-07T14:31:21.390Z",
    "payedAt": null,
    "pixInformation": null,
    "subscription": null,
    "orderItems": [
      {
        "id": "wdod0abvdt",
        "price": 100,
        "product": {
          "id": "oigtz177jp",
          "name": "Curso de marketing",
          "externalId": "KSA912"
        }
      }
    ],
    "trackProps": {
      "utm_id": "12345",
      "utm_source": "facebook",
      "utm_medium": "cpc",
      "utm_campaign": "lancamento",
      "utm_content": "newsletter",
      "utm_term": "summer+venda",
      "fbc": "fb.1.1234567890.0987654321",
      "fbp": "fb.1.0987654321.1234567890",
      "ip": "179.241.195.127",
      "country": "BR",
      "user_agent": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/114.0.0.0 Mobile Safari/537.36",
      "zip_code": "01304-000",
      "city": "São Paulo",
      "state": "SP"
    }
  }
}
```

## 7.6. Webhook de Transferência

Eventos disponíveis:

- `TRANSFER_CREATED` — Transferência criada
- `TRANSFER_COMPLETED` — Transferência concluída
- `TRANSFER_FAILED` — Transferência falhou

**Campos de nível raiz**

- `event` (enum) — nome do evento disparado
- `token` (string) — token para validar a autenticidade da notificação
- `withdraw` (object) — dados da transferência solicitada
- `payoutAccount` (object) — dados da conta de pagamento cadastrada pelo produtor
- `sents` (array) — lista de envios realizados para esta transferência
- `pixMetadata` (object | null) — metadados do Pix

**`withdraw`**

- `id` (string) — identificador da transferência
- `clientIdentifier` (string | null) — seu identificador da transferência
- `amount` (number) — valor solicitado na moeda de recebimento
- `message` (string | null) — motivo de cancelamento (preenchido quando cancelada)
- `receivedAmount` (number) — valor efetivamente recebido após taxas (zero quando não concluída)
- `feeAmount` (number) — valor da taxa aplicada
- `currency` (string) — moeda de recebimento (ex.: BRL)
- `status` (enum) — `PENDING`, `PROCESSING`, `TRANSFERRING`, `COMPLETED`, `CANCELED`
- `createdAt` (date) — ISO 8601
- `updatedAt` (date) — ISO 8601

**`payoutAccount`**

- `id` (string) — identificador da conta
- `status` (enum) — `ACTIVE`, `INACTIVE`
- `ownerName` (string) — nome do titular
- `ownerDocument` (string) — documento do titular (CPF ou CNPJ)
- `pix` (string) — chave Pix
- `pixType` (string) — tipo da chave Pix (ex.: email, cpf, phone, random)
- `bank` (string) — código do banco (transferência TED)
- `agency` (string) — agência bancária (TED)
- `agencyDigit` (string) — dígito da agência (TED)
- `account` (string) — número da conta (TED)
- `accountDigit` (string) — dígito da conta (TED)
- `accountType` (enum) — `CHECKING`, `SAVINGS`, `CRYPTO_WALLET`
- `cryptoAddress` (string) — endereço de carteira cripto
- `cryptoNetwork` (string | null) — rede da carteira cripto
- `createdAt` / `updatedAt` / `deletedAt` (date | null) — ISO 8601

**`sents[]`**

- `id` (string) — identificador do envio
- `amount` (number) — valor do envio
- `status` (enum) — `PROCESSING`, `COMPLETED`, `FAILED`
- `endToEndId` (string | null) — ID end-to-end do Pix (preenchido quando concluído)
- `createdAt` (date) — ISO 8601
- `pixMetadata` (object | null) — preenchido quando disponível pelo adquirente:
  `payerDocument`, `payerName`, `payerBankName`, `payerBankAccount`, `payerBankBranch`, `receiverDocument`, `receiverName`, `receiverPixKey`, `receiverBankName`, `receiverBankAccount`, `receiverBankBranch` (todos string | null)

**Exemplo de payload — Transferência criada**

```json
{
  "event": "TRANSFER_CREATED",
  "token": "f0xh4wptag",
  "withdraw": {
    "id": "mg8vee9rxyeuvlk0",
    "clientIdentifier": "123456",
    "amount": 100,
    "receivedAmount": 0,
    "feeAmount": 10,
    "currency": "BRL",
    "status": "PENDING",
    "createdAt": "2026-09-07T14:31:23.458Z",
    "updatedAt": "2026-09-07T14:31:23.458Z"
  },
  "payoutAccount": {
    "id": "vqsf6vrcshygqnly",
    "status": "ACTIVE",
    "ownerName": "João da Silva",
    "ownerDocument": "123.456.789-00",
    "pix": "cliente@gmail.com",
    "pixType": "email",
    "bank": "001",
    "agency": "0001",
    "agencyDigit": "",
    "account": "000001",
    "accountDigit": "1",
    "createdAt": "2026-09-07T14:31:23.458Z",
    "updatedAt": "2026-09-07T14:31:23.458Z",
    "deletedAt": null
  },
  "sents": [],
  "pixMetadata": null
}
```

## 7.7. Webhook de Chargeback / Disputas

Eventos disponíveis:

- `CHARGEBACK_CREATED` — Chargeback recebido
- `MED_CREATED` — MED recebido
- `CHARGEBACK_UPDATED` — Chargeback atualizado
- `MED_UPDATED` — MED atualizado

**Campos de nível raiz**

- `event` (enum), `token` (string), `chargeback` (object), `transaction` (object), `client` (object | null)

**`chargeback`**

- `id` (string) — identificador único do alerta
- `externalAlertId` (string | null) — identificador do alerta no provedor externo
- `type` (enum) — `CHARGEBACK`, `MED`
- `status` (enum) — `PENDING`, `SOLVED`, `DENIED`, `NOT_FOUND`, `DEFENDING`
- `origin` (enum) — `NATIONAL`, `INTERNATIONAL`
- `amount` (number | null) — valor do chargeback na moeda informada
- `currency` (string | null) — moeda do valor (ex.: BRL, USD)
- `transactionDate` (date | null) — data e hora da transação original (ISO 8601)
- `cardBrand` (string | null) — bandeira do cartão (ex.: visa, mastercard)
- `cardLastFour` (string | null) — últimos 4 dígitos do cartão
- `descriptor` (string | null) — descriptor que aparece na fatura do cliente
- `issuer` (string | null) — nome do banco emissor
- `details` (string | null) — detalhes adicionais
- `producerFineAmount` (number) — valor da multa aplicada ao produtor
- `createdAt` / `updatedAt` (date) — ISO 8601

**`transaction`**

- `id`, `identifier` (string | null), `status` (enum), `acquirer` (string — adquirente que processou), `paymentMethod` (enum), `originalAmount`, `originalCurrency`, `exchangeRate`, `currency`, `amount`, `chargeAmount` (valor cobrado incluindo taxas), `commissionAmount` (valor líquido), `installments`, `createdAt`, `payedAt` (date | null), `pixInformation` (object | null: `qrCode`, `endToEndId`), `boletoInformation` (object | null: `id`, `barcode`, `digitableLine`, `pdfUrl`, `instructions`)

**`client`** — mesma estrutura do webhook de pagamentos (nulo quando não identificado).

**Exemplo de payload — Chargeback criado**

```json
{
  "event": "CHARGEBACK_CREATED",
  "token": "1omd7y74wg",
  "chargeback": {
    "id": "scmopggj326mfkzx",
    "externalAlertId": "alert_abc123xyz",
    "type": "CHARGEBACK",
    "status": "PENDING",
    "origin": "INTERNATIONAL",
    "amount": 150,
    "currency": "BRL",
    "transactionDate": "2026-09-07T14:31:25.191Z",
    "cardBrand": "visa",
    "cardLastFour": "4242",
    "descriptor": "CHARGEBACK OBJECT",
    "issuer": "Banco do Brasil",
    "details": "Customer claims unauthorized transaction",
    "producerFineAmount": 50,
    "createdAt": "2026-09-07T14:31:25.191Z",
    "updatedAt": "2026-09-07T14:31:25.191Z"
  },
  "transaction": {
    "id": "1pned18asp",
    "identifier": null,
    "status": "CHARGED_BACK",
    "paymentMethod": "CREDIT_CARD",
    "originalAmount": 100,
    "originalCurrency": "BRL",
    "exchangeRate": 1,
    "currency": "BRL",
    "amount": 150,
    "installments": 3,
    "createdAt": "2026-09-07T14:31:25.191Z",
    "payedAt": "2026-09-07T14:31:25.191Z",
    "pixInformation": null,
    "boletoInformation": null
  },
  "client": {
    "id": "scmopggj326mfkzx",
    "name": "John Doe",
    "email": "johndoe@gmail.com",
    "phone": "(11) 9 8888-7777",
    "cpf": "123.456.789-10",
    "cnpj": null,
    "address": {
      "country": "BR",
      "zipCode": "01304-000",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Consolação",
      "street": "Rua Augusta",
      "number": "6312",
      "complement": "6 andar"
    }
  }
}
```

---

# 8. Endpoints

## 8.1. GET /ping — Status da API

Verificação rápida de status, útil para monitoramento e health check. **Não requer autenticação.**

```
GET https://app.checkto.com.br/api/v1/ping
```

Retorno `200 OK`:

- `message` (string) — string de confirmação de que o servidor está online. Sempre retornado.

```json
{ "message": "pong" }
```

## 8.2. GET /gateway/producer — Meus dados

Obtém informações do produtor: nome, e-mail, telefone e endereço. **Requer autenticação.**

```
GET https://app.checkto.com.br/api/v1/gateway/producer
```

Retorno `200 OK`:

- `name` (string) — nome do produtor. Sempre retornado.
- `email` (string) — e-mail do produtor. Sempre retornado.
- `phone` (string) — telefone, formatado como (99) 99999-9999. Sempre retornado.
- `document` (string) — CPF ou CNPJ, formatado com pontos e traços. **Não é retornado se o produtor não passou pelo KYC.**
- `address` (object) — endereço do produtor/empresa. Não é retornado antes do KYC. Se o cadastro é CPF, refere-se ao endereço do produtor; se CNPJ, ao endereço da empresa:
  - `zipCode` (string) — CEP, formatado com hífen
  - `country` (string) — país no padrão ISO 3166-1
  - `state` (string) — estado no padrão ISO 3166-2:BR
  - `city` (string) — cidade
  - `neighborhood` (string) — bairro
  - `street` (string) — rua
  - `number` (string) — número
  - `complement` (string) — complemento
- `legalRepresentative` (object) — informações do representante legal. **Retornado apenas para produtores com CNPJ:**
  - `name` (string) — nome do representante legal
  - `phone` (string) — telefone, formatado como (99) 99999-9999
  - `document` (string) — CPF ou CNPJ, formatado
  - `address` (object) — mesma estrutura de endereço acima

```json
{
  "name": "John Doe",
  "email": "john@mail.com",
  "phone": "(11) 99999-9999",
  "document": "123.456.789-00",
  "address": {
    "zipCode": "12345-000",
    "country": "BR",
    "state": "SP",
    "city": "São Paulo",
    "neighborhood": "Alphaville",
    "street": "Rua das Flores",
    "number": "12",
    "complement": "Casa azul"
  }
}
```

## 8.3. GET /gateway/producer/balance — Meu saldo

Obtém o saldo atual da conta, calculado com base nas transações realizadas. **Requer autenticação.**

```
GET https://app.checkto.com.br/api/v1/gateway/producer/balance
```

Retorno `200 OK`:

- `available` (number) — saldo disponível para saque. Sempre retornado.
- `pending` (number) — saldo pendente. Sempre retornado.
- `fundLock` (number) — saldo retido. Sempre retornado.

```json
{
  "available": 12345.67,
  "pending": 999.99,
  "fundLock": 0
}
```

## 8.4. GET /gateway/producer/credentials — Testar credenciais

Testa as credenciais e retorna informações sobre a credencial atual. **Requer autenticação.**

```
GET https://app.checkto.com.br/api/v1/gateway/producer/credentials
```

Retorno `200 OK`:

- `name` (string) — nome da credencial. Sempre retornado.
- `permissions` (enum array) — lista de permissões: `PRODUCER_DATA`, `PRODUCER_TRANSACTIONS`, `PRODUCER_WITHDRAWS`, `PRODUCER_CHECKOUT`. Sempre retornado.
- `grantAllPermissions` (boolean) — se `true`, a credencial tem acesso total e o array `permissions` pode estar vazio. Sempre retornado.
- `expiresAt` (string) — data de expiração no formato ISO 8601, ou `null` se não expirar.

```json
{
  "name": "Credencial de produção",
  "permissions": ["PRODUCER_TRANSACTIONS", "PRODUCER_DATA"],
  "grantAllPermissions": false,
  "expiresAt": "2026-09-07T15:00:29.885Z"
}
```

Retornos `401 Unauthorized` (campos `statusCode`, `errorCode`, `message`):

```json
{ "statusCode": 401, "errorCode": "GATEWAY_NO_CREDENTIALS", "message": "Credenciais não fornecidas" }
```
```json
{ "statusCode": 401, "errorCode": "GATEWAY_INVALID_CREDENTIALS", "message": "Credenciais inválidas" }
```
```json
{ "statusCode": 401, "errorCode": "GATEWAY_NO_CREDENTIALS", "message": "Sua chave de API expirou" }
```
```json
{ "statusCode": 401, "errorCode": "GATEWAY_NO_CREDENTIALS", "message": "Sua conta está desativada. Entre em contato com o suporte para mais informações." }
```

## 8.5. GET /gateway/transactions — Buscar transação

Busca uma transação específica. **Requer autenticação. Não use para polling frequente** — para atualização em tempo real, use webhooks.

```
GET https://app.checkto.com.br/api/v1/gateway/transactions?id=string&clientIdentifier=string
```

Query parameters:

- `id` (string) — ID da transação retornado pela API ao criá-la.
- `clientIdentifier` (string) — identificador que você enviou ao criar a transação.

Retorno `200 OK`:

- `id` (string) — ID da transação. Sempre retornado.
- `clientIdentifier` (string) — corresponde ao valor enviado por você na criação. Sempre retornado.
- `currency` (enum) — moeda da transação. Padrão `BRL`. Sempre retornado.
- `amount` (number) — valor total da transação; é o valor que você vai receber, sem contar as taxas. Sempre retornado.
- `chargeAmount` (number) — valor pago pelo cliente. Pode diferir de `amount` por taxas de parcelamento (venda via checkout interno). Sempre retornado.
- `exchangeRate` (number) — taxa de câmbio utilizada. Padrão `1`. Para transações em moeda diferente de BRL, multiplique por `amount` para obter o valor em BRL. Sempre retornado.
- `producerExtraAmount` (number) — taxa extra cobrada pelo produtor, apenas no checkout interno. Padrão `0`. Sempre retornado.
- `status` (enum) — `PENDING`, `COMPLETED`, `FAILED`, `REFUNDED`, `CHARGED_BACK`. Sempre retornado.
- `statusDescription` (string) — descrição do status; mostra o retorno da adquirente.
- `purchaseType` (enum) — `ONCE` (compra única) ou `RECURRING` (assinatura). Padrão `ONCE`. Sempre retornado.
- `paymentMethod` (enum) — `PIX`, `CREDIT_CARD`, `BOLETO`, `TED`, `SPLIT`, `DYNAMIC`, `CRYPTO`, `CASH_ON_DELIVERY`. Sempre retornado.
- `details` (string) — detalhes da transação; pode ser um JSON com informações adicionais.
- `errorDescription` (string) — descrição do erro, caso a transação tenha falhado.
- `webhookUrl` (string) — URL do webhook configurado para essa transação.
- `createdAt` (string) — data de criação. Sempre retornado.
- `availableAt` (string) — data em que a transação estará disponível para saque. Sempre retornado.
- `payedAt` (string) — data em que a transação foi paga pelo cliente.
- `refundedAt` (string) — data em que a transação foi estornada.
- `boletoInformation` (object) — informações do boleto gerado:
  - `barcode` (string) — código de barras. Sempre retornado.
  - `digitableLine` (string) — linha digitável. Sempre retornado.
  - `pdfUrl` (string) — URL para download do boleto em PDF.
- `pixInformation` (object) — informações do Pix gerado:
  - `qrCode` (string) — QR Code do Pix. Sempre retornado.
  - `image` (string) — URL para download da imagem do QR Code.
- `pixMetadata` (object) — informações adicionais sobre o Pix:
  - `payerDocument`, `payerName`, `payerBankName`, `payerBankAccount`, `payerBankBranch` (string)
  - `receiverDocument`, `receiverName`, `receiverPixKey`, `receiverBankName`, `receiverBankAccount`, `receiverBankBranch` (string)

```json
{
  "id": "cmry2h8332sgs3ub44fh7",
  "clientIdentifier": "5286-412312-asd-123",
  "currency": "BRL",
  "amount": 49.8,
  "chargeAmount": 49.8,
  "exchangeRate": 1,
  "producerExtraAmount": 0,
  "status": "FAILED",
  "statusDescription": null,
  "purchaseType": "ONCE",
  "paymentMethod": "PIX",
  "details": null,
  "errorDescription": "Transaction denied by anti-fraud",
  "webhookUrl": null,
  "availableAt": null,
  "createdAt": "2026-09-07T15:01:11.442Z",
  "refundedAt": null,
  "payedAt": null,
  "boletoInformation": null,
  "pixInformation": {
    "qrCode": "00020101065465468949845BR.GOV.BCB.PIX...",
    "image": "https://exemplo.com/qrcode.svg"
  },
  "pixMetadata": {
    "payerBankName": "Caixa Economica Federal",
    "payerDocument": "123.456.789-00",
    "payerName": "João da Silva",
    "receiverBankName": "Banco do Brasil",
    "receiverDocument": "987.654.321-00",
    "receiverName": "Maria da Silva",
    "receiverPixKey": "98765432100"
  }
}
```

## 8.6. POST /gateway/producer/refunds — Solicitar reembolso

Solicita reembolso de uma transação do produtor autenticado. **Requer autenticação.**

```
POST https://app.checkto.com.br/api/v1/gateway/producer/refunds
```

Headers obrigatórios: `x-public-key`, `x-secret-key`.

Body (`application/json`):

- `transactionId` (string, **obrigatório**) — ID da transação a ser reembolsada. Deve pertencer ao produtor autenticado.
- `reason` (string, **obrigatório**) — motivo da solicitação de reembolso.
- `description` (string | null) — descrição opcional com detalhes adicionais.

Retorno `200 OK`:

- `id` (string) — ID da solicitação de reembolso criada. Sempre retornado.
- `transactionId` (string) — ID da transação vinculada. Sempre retornado.
- `producerId` (string) — ID do produtor dono da transação. Sempre retornado.
- `status` (enum) — `PENDING`, `COMPLETED`, `CANCELED`. Sempre retornado.
- `amount` (number) — valor solicitado para reembolso. Sempre retornado.
- `reason` (string) — motivo informado. Sempre retornado.
- `description` (string | null) — descrição adicional informada.

Erros possíveis: `400 Bad Request`, `401 Unauthorized`, `404 Not Found`, `422 Unprocessable Entity` (todos com `statusCode`, `errorCode`, `message`).

Exemplo de requisição:

```json
{
  "transactionId": "cmry2h8332sgs3ub44fh7",
  "reason": "Cliente solicitou cancelamento",
  "description": "Solicitacao recebida pelo atendimento."
}
```

Exemplo de retorno `200 OK`:

```json
{
  "id": "cmrefund123",
  "transactionId": "cmry2h8332sgs3ub44fh7",
  "producerId": "cmproducer123",
  "status": "PENDING",
  "amount": 49.8,
  "reason": "Cliente solicitou cancelamento",
  "description": "Solicitacao recebida pelo atendimento."
}
```

Exemplo de retorno `422` (reembolso existente):

```json
{
  "statusCode": 422,
  "errorCode": "GATEWAY_INVALID_ARGUMENT",
  "message": "Ja existe uma solicitacao de reembolso para esta transacao"
}
```

## 8.7. GET /gateway/subscriptions — Buscar assinaturas

Busca uma lista de assinaturas com base nos filtros informados. **Requer autenticação. Não use para polling frequente** — use webhooks.

```
GET https://app.checkto.com.br/api/v1/gateway/subscriptions?transactionId=string&subscriptionId=string&orderId=string&clientIdentifier=string&clientEmail=string
```

Query parameters:

- `transactionId` (string) — ID da transação retornado pela API ao criar uma assinatura.
- `subscriptionId` (string) — ID da assinatura retornado pelo webhook ao criar uma assinatura.
- `orderId` (string) — ID do pedido; é o ID da compra do cliente enviado via e-mail.
- `clientIdentifier` (string) — identificador que você enviou ao criar a transação.
- `clientEmail` (string) — e-mail do cliente enviado na criação da assinatura.

Retorno `200 OK`:

- `subscriptions` (array) — sempre retornado:
  - `id` (string) — ID da assinatura. Sempre retornado.
  - `startAt` (string) — data de início. Sempre retornado.
  - `intervalType` (enum) — `DAYS`, `WEEKS`, `MONTHS`, `YEARS`. Sempre retornado.
  - `intervalCount` (number) — número de intervalos para renovação. Sempre retornado.
  - `status` (enum) — `ACTIVE`, `INACTIVE`, `CANCELED`. Sempre retornado.
  - `cycle` (number) — número do ciclo atual. Sempre retornado.
  - `items` (array) — sempre retornado:
    - `id` (string) — ID do item
    - `isBump` (boolean) — indica se o item é um bump
    - `productId` (string) — ID do produto
    - `productName` (string) — nome do produto

```json
{
  "subscriptions": [
    {
      "id": "cm8xja4ab000k6q62wpwv5722",
      "startAt": "2025-03-31T20:40:37.426Z",
      "intervalType": "MONTHS",
      "intervalCount": 1,
      "status": "ACTIVE",
      "cycle": 1,
      "items": [
        {
          "id": "cm8tgm0lj002w6n8sdx7ko4pq",
          "isBump": false,
          "productId": "clz02cs9j0001miylmwcvnjjp",
          "productName": "Newsletter"
        }
      ]
    }
  ]
}
```

## 8.8. POST /gateway/pix/deposit — Depósito Pix

Realiza depósitos via Pix na própria conta. **Requer autenticação.**

```
POST https://app.checkto.com.br/api/v1/gateway/pix/deposit
```

Body (`application/json`):

- `amount` (number, **obrigatório**) — valor da transação, em reais.
- `identifier` (string) — identificador único da transação, criado pela sua aplicação.
- `callbackUrl` (string) — URL para notificação de alteração de status.

Retorno `201 OK`:

- `transactionId` (string) — ID único da transação criado pela Checkto. Guarde para consultas futuras. Sempre retornado.
- `status` (enum) — `OK`, `FAILED`, `PENDING`, `REJECTED`, `CANCELED`. Sempre retornado.
- `order` (object) — sempre retornado:
  - `id` (string) — ID do pedido para consulta interna. Sempre retornado.
  - `url` (string) — URL do pedido no checkout interno.
- `pix` (object) — sempre retornado:
  - `code` (string) — código copia e cola. Sempre retornado.
  - `image` (string) — URL da imagem do QR Code.
  - `base64` (string) — **DEPRECATED**: o servidor não gera mais o base64 do QR Code. Mantido por retrocompatibilidade, sempre retorna string vazia; será removido em versão futura. Renderize o QR Code a partir do campo `code`.

Retorno `400 Bad Request`: `statusCode`, `errorCode`, `message`, `details` (`field`, `value`, `issue`).

Exemplo de requisição:

```json
{
  "identifier": "4s1bbs2kyu",
  "amount": 100.5,
  "callbackUrl": "https://minha.api.com/pix/callback/9y18v2hlym"
}
```

Exemplo de retorno `201`:

```json
{
  "transactionId": "clwuwmn4i0007emp9lgn66u1h",
  "status": "OK",
  "order": {
    "id": "cm92389asdaskdjkasjdka",
    "url": "https://api-de-pagamentos.com/order/cm92389asdaskdjkasjdka"
  },
  "pix": {
    "code": "00020101021126530014BR.GOV.BCB.PIX...",
    "image": "https://api.gateway.com/pix/qr/00020101021126530014BR.GOV.BCB.PIX...",
    "base64": ""
  }
}
```

Exemplo de retorno `400`:

```json
{
  "statusCode": 400,
  "errorCode": "INVALID_INPUT",
  "message": "O valor fornecido para o campo 'amount' é inválido.",
  "details": {
    "field": "amount",
    "value": -20,
    "issue": "O valor deve ser positivo e maior que zero."
  }
}
```

## 8.9. POST /gateway/pix/receive — Receber Pix

Recebe pagamentos avulsos via Pix. **Requer autenticação.**

```
POST https://app.checkto.com.br/api/v1/gateway/pix/receive
```

Body (`application/json`):

- `identifier` (string, **obrigatório**) — identificador único da transação, criado pela sua aplicação, único por transação.
- `amount` (number, **obrigatório**) — valor da transação, em reais.
- `shippingFee` (number) — frete da transação, em reais.
- `extraFee` (number) — outras taxas, em reais.
- `discount` (number) — desconto da transação, em reais.
- `client` (object, **obrigatório**) — dados do cliente:
  - `name` (string, obrigatório) — nome do cliente
  - `email` (string, obrigatório) — e-mail do cliente
  - `phone` (string, obrigatório) — vendas nacionais: formato brasileiro `(11) 99999-9999` (com ou sem formatação); vendas internacionais: formato internacional (ex.: `+1 555 555 5555`)
  - `document` (string, obrigatório) — vendas nacionais: CPF ou CNPJ, com ou sem formatação; vendas internacionais: documento de identificação conforme o país (pode ser omitido, mas é recomendado enviar)
- `products` (array) — lista de produtos:
  - `id` (string, obrigatório) — ID único do produto **na sua aplicação**, gerado por você. Não confunda com o ID do produto no painel da Checkto.
  - `name` (string, obrigatório) — nome do produto
  - `quantity` (number) — quantidade, padrão `1`
  - `price` (number, obrigatório) — preço unitário, em reais
  - `physical` (boolean) — se o produto é físico
- `splits` (array) — divisão do valor:
  - `producerId` (string, obrigatório) — ID da conta que receberá o split
  - `amount` (number, obrigatório) — valor em reais a repassar
- `dueDate` (string) — data de vencimento da cobrança, formato `YYYY-MM-DD`.
- `metadata` (object) — metadados da transação. Pode ser objeto chave-valor ou string. Ex.: `{ "provider": "Checkout", "orderId": "1234" }`.
- `callbackUrl` (string) — URL para notificação de alteração de status.

Retorno `200 OK`:

- `transactionId` (string) — ID único da transação. Sempre retornado.
- `status` (enum) — `OK`, `FAILED`, `PENDING`, `REJECTED`, `CANCELED`. Sempre retornado.
- `transactionStatus` (enum) — status persistido no gateway: `PENDING`, `COMPLETED`, `FAILED`, `REFUNDED`, `CHARGED_BACK`.
- `webhookToken` (string) — token para validar as notificações; retornado quando `callbackUrl` é informado.
- `fee` (number) — valor da taxa cobrada. Sempre retornado.
- `order` (object) — `id` (string, sempre retornado), `url` (string). Sempre retornado.
- `pix` (object) — `code` (copia e cola, sempre retornado), `image` (URL do QR Code), `base64` (DEPRECATED, sempre vazio). Sempre retornado.
- `details` (string) — detalhes adicionais sobre a transação.
- `errorDescription` (string) — descrição do erro, se a transação falhou.

Retorno `400 Bad Request`: `statusCode`, `errorCode`, `message`, `details` (`field`, `value`, `issue`).

Exemplo de requisição:

```json
{
  "identifier": "ju0ehmmbc0",
  "amount": 100.5,
  "client": {
    "name": "João da Silva",
    "email": "joao@gmail.com",
    "phone": "(11) 99999-9999",
    "document": "123.456.789-00"
  },
  "products": [
    { "id": "wjwvc1ocbzme", "name": "Produto 1", "quantity": 1, "price": 80 },
    { "id": "uxhgy6a4bqfe", "name": "Produto 2", "quantity": 2, "price": 10.25 }
  ],
  "dueDate": "2026-09-08",
  "metadata": { "key1": "value1", "key2": "value2" },
  "callbackUrl": "https://minha.api.com/pix/callback/8q8bjtj23b"
}
```

Exemplo de retorno `200 OK`:

```json
{
  "transactionId": "clwuwmn4i0007emp9lgn66u1h",
  "status": "OK",
  "webhookToken": "webhookToken123",
  "order": {
    "id": "cm92389asdaskdjkasjdka",
    "url": "https://api-de-pagamentos.com/order/cm92389asdaskdjkasjdka",
    "receiptUrl": "https://api-de-pagamentos.com/order/cm92389asdaskdjkasjdka/receipt"
  },
  "pix": {
    "code": "00020101021126530014BR.GOV.BCB.PIX...",
    "image": "https://api.gateway.com/pix/qr/00020101021126530014BR.GOV.BCB.PIX...",
    "base64": ""
  }
}
```

## 8.10. POST /gateway/boleto/receive — Receber boleto

Recebe pagamentos avulsos via boleto. **Requer autenticação.**

```
POST https://app.checkto.com.br/api/v1/gateway/boleto/receive
```

Body: os mesmos campos de `/gateway/pix/receive`, com uma diferença — o objeto `client` exige também o endereço:

- `client.address` (object, **obrigatório**):
  - `country` (string, obrigatório) — país no formato ISO 3166-1 alpha-2
  - `zipCode` (string, obrigatório) — CEP no padrão internacional (GeoPostcodes)
  - `state` (string, obrigatório) — estado no formato ISO 3166-2 (ex.: SP)
  - `city` (string, obrigatório) — cidade
  - `street` (string, obrigatório) — rua
  - `neighborhood` (string, obrigatório) — bairro
  - `number` (string, obrigatório) — número
  - `complement` (string) — complemento

Retorno `200 OK`: os mesmos campos de `/gateway/pix/receive`, exceto o objeto `pix`, que é substituído por:

- `boleto` (object) — sempre retornado:
  - `barcode` (string) — código de barras. Sempre retornado.
  - `digitableLine` (string) — linha digitável. Sempre retornado.
  - `pdfUrl` (string) — URL para download do boleto em PDF.

Exemplo de requisição:

```json
{
  "identifier": "tf99mgx8d1",
  "amount": 100.5,
  "client": {
    "name": "João da Silva",
    "email": "joao@gmail.com",
    "phone": "(11) 99999-9999",
    "document": "123.456.789-00",
    "address": {
      "country": "BR",
      "zipCode": "12345-678",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Centro",
      "street": "Rua dos Bobos",
      "number": "0",
      "complement": ""
    }
  },
  "products": [
    { "id": "vc7c3p0rab9f", "name": "Produto 1", "quantity": 1, "price": 80 },
    { "id": "4y3yd4zhq8uh", "name": "Produto 2", "quantity": 2, "price": 10.25 }
  ],
  "metadata": { "key1": "value1", "key2": "value2" },
  "callbackUrl": "https://minha.api.com/boleto/callback/zj53b2upmc"
}
```

Exemplo de retorno `200 OK`:

```json
{
  "transactionId": "clwuwmn4i0007emp9lgn66u1h",
  "status": "OK",
  "webhookToken": "webhookToken123",
  "order": {
    "id": "cm92389asdaskdjkasjdka",
    "url": "https://api-de-pagamentos.com/order/cm92389asdaskdjkasjdka",
    "receiptUrl": "https://api-de-pagamentos.com/order/cm92389asdaskdjkasjdka/receipt"
  },
  "boleto": {
    "barcode": "001 9 337370000000100 05009 401448 16060680935031",
    "digitableLine": "00190500954014481606906809350314337370000000100",
    "pdfUrl": "https://api.gateway.com/boleto/pdf/00190500954014481606906809350314337370000000100"
  }
}
```

## 8.11. POST /gateway/card/receive — Receber cartão

Recebe pagamentos avulsos via cartão de crédito. **Requer autenticação.**

```
POST https://app.checkto.com.br/api/v1/gateway/card/receive
```

Body: os mesmos campos de `/gateway/pix/receive`, mais:

- `clientIp` (string, **obrigatório**) — IPv4 do cliente que está realizando a transação.
- `card` (object, **obrigatório**):
  - `number` (string, obrigatório) — número do cartão
  - `owner` (string, obrigatório) — nome do titular
  - `expiresAt` (string, obrigatório) — data de expiração no formato `YYYY-MM`
  - `cvv` (string, obrigatório) — código de segurança
  - `statementDescriptor` (string) — nome exibido na fatura; quando enviado, é usado como descriptor da transação
- `installments` (number) — número de parcelas.

O objeto `client` aceita `address` (usado em vendas internacionais).

Retorno `200 OK`: `transactionId`, `status`, `transactionStatus`, `webhookToken`, `fee`, `order`, `details`, `errorDescription` — sem objeto de pagamento adicional.

Exemplo de requisição (venda nacional):

```json
{
  "identifier": "a12uv5ses2",
  "amount": 100.5,
  "client": {
    "name": "João da Silva",
    "email": "joao@gmail.com",
    "phone": "(11) 99999-9999",
    "document": "123.456.789-00",
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Centro",
      "zipCode": "12345-678",
      "street": "Rua do Centro",
      "number": "123",
      "complement": "Sala 1"
    }
  },
  "clientIp": "127.0.0.1",
  "card": {
    "number": "4111111111111111",
    "owner": "João da Silva",
    "expiresAt": "2026-09",
    "cvv": "123",
    "statementDescriptor": "MINHA LOJA"
  },
  "installments": 3,
  "products": [
    { "id": "1hxo5u549jpg", "name": "Produto 1", "quantity": 1, "price": 80 },
    { "id": "4wnky1j9vvmh", "name": "Produto 2", "quantity": 2, "price": 10.25 }
  ],
  "metadata": { "key1": "value1", "key2": "value2" },
  "callbackUrl": "https://minha.api.com/card/callback/oln7us7dzp"
}
```

Exemplo de requisição (venda internacional):

```json
{
  "identifier": "5ines6l4l8",
  "amount": 100.5,
  "client": {
    "name": "John Doe",
    "email": "john@icloud.com",
    "phone": "+1 (555) 555-5555",
    "document": "123-45-6789",
    "address": {
      "country": "US",
      "state": "CA",
      "city": "Los Angeles",
      "neighborhood": "Downtown",
      "zipCode": "90001",
      "street": "Downtown Street",
      "number": "123",
      "complement": "Apt 1"
    }
  },
  "clientIp": "127.0.0.1",
  "card": {
    "number": "4111111111111111",
    "owner": "John Doe",
    "expiresAt": "2026-09",
    "cvv": "123",
    "statementDescriptor": "MY STORE"
  },
  "installments": 3,
  "products": [
    { "id": "snec2m13tve8", "name": "Produto 1", "quantity": 1, "price": 80 },
    { "id": "71141hbqf3og", "name": "Produto 2", "quantity": 2, "price": 10.25 }
  ],
  "metadata": { "key1": "value1", "key2": "value2" },
  "callbackUrl": "https://minha.api.com/card/callback/..."
}
```

Exemplo de retorno `200 OK`:

```json
{
  "transactionId": "clwuwmn4i0007emp9lgn66u1h",
  "status": "OK",
  "webhookToken": "webhookToken123",
  "order": {
    "id": "cm92389asdaskdjkasjdka",
    "url": "https://api-de-pagamentos.com/order/cm92389asdaskdjkasjdka",
    "receiptUrl": "https://api-de-pagamentos.com/order/cm92389asdaskdjkasjdka/receipt"
  }
}
```

Exemplo de retorno `200` com reprovação antifraude:

```json
{
  "transactionId": "clwuwmn4i0007emp9lgn66u1h",
  "status": "PENDING",
  "details": "ACQUIRER_ANTIFRAUD_REPROVED"
}
```

## 8.12. POST /gateway/crypto/receive — Receber cripto

Recebe pagamentos avulsos via criptomoeda. **Requer autenticação.**

```
POST https://app.checkto.com.br/api/v1/gateway/crypto/receive
```

Body: os mesmos campos de `/gateway/pix/receive`, mais:

- `crypto` (object, **obrigatório**):
  - `currency` (enum, obrigatório) — moeda utilizada na transação
  - `network` (enum, obrigatório) — rede blockchain pela qual a transação será realizada: `BDM_DIGITAL`, `BSC`, `ETH`, `BTC`, `POLYGON`, `TRON`, `BASE`, `TON`, `SOLANA`

Retorno `200 OK`: os mesmos campos de `/gateway/pix/receive`, exceto o objeto `pix`, substituído por:

- `qr` (object) — dados do pagamento em criptomoeda. Sempre retornado:
  - `code` (string) — código copia e cola gerado para a transação. Sempre retornado.
  - `image` (string) — URL da imagem do QR Code.

Exemplo de requisição:

```json
{
  "identifier": "4sb5y062aq",
  "amount": 100.5,
  "client": {
    "name": "João da Silva",
    "email": "joao@gmail.com",
    "phone": "(11) 99999-9999",
    "document": "123.456.789-00"
  },
  "products": [
    { "id": "6qqv53zyfcuf", "name": "Produto 1", "quantity": 1, "price": 80 },
    { "id": "obh79npfmrjf", "name": "Produto 2", "quantity": 2, "price": 10.25 }
  ],
  "dueDate": "2026-09-08",
  "metadata": { "key1": "value1", "key2": "value2" },
  "crypto": { "currency": "BDM", "network": "BDM_DIGITAL" },
  "callbackUrl": "https://minha.api.com/crypto/callback/j1stwz9buy"
}
```

## 8.13. POST /gateway/pix/subscription — Assinatura Pix

Recebe pagamentos recorrentes via Pix. **Requer autenticação.**

```
POST https://app.checkto.com.br/api/v1/gateway/pix/subscription
```

Body (`application/json`):

- `identifier` (string, **obrigatório**) — identificador único da transação, criado pela sua aplicação.
- `amount` (number, **obrigatório**) — valor da transação, em reais.
- `product` (object, **obrigatório**) — produto de assinatura:
  - `id` (string, obrigatório) — ID único do produto na sua aplicação
  - `name` (string, obrigatório) — nome do produto
  - `price` (number, obrigatório) — preço unitário, em reais
- `subscription` (object, **obrigatório**) — configurações da assinatura:
  - `periodicityType` (enum, obrigatório) — `DAYS`, `WEEKS`, `MONTHS`, `YEARS`
  - `periodicity` (number, obrigatório) — quantidade de períodos. Ex.: `2` com `MONTHS` = uma cobrança a cada 2 meses
  - `firstChargeIn` (number, obrigatório) — em quantos dias após a criação a primeira cobrança será realizada
- `client` (object, **obrigatório**) — mesma estrutura das rotas de pagamento.
- `dueDate` (string) — data de vencimento, formato `YYYY-MM-DD`.
- `metadata` (object) — metadados da transação.
- `callbackUrl` (string) — URL para notificação de alteração de status.

Retorno `200 OK`:

- `transactionId` (string) — sempre retornado.
- `status` (enum) — `OK`, `FAILED`, `PENDING`, `REJECTED`, `CANCELED`. Sempre retornado.
- `transactionStatus` (enum) — status persistido no gateway.
- `webhookToken` (string) — retornado quando `callbackUrl` é informado.
- `fee` (number) — valor da taxa cobrada. Sempre retornado.
- `order` (object) — sempre retornado.
- `subscription` (object) — sempre retornado:
  - `id` (string) — ID único da assinatura. Guarde para consultas futuras.
  - `periodicityType` (enum) — `DAYS`, `WEEKS`, `MONTHS`, `YEARS`
  - `periodicity` (number) — quantidade de períodos
  - `nextChargeAt` — próxima cobrança
  - `startAt` — data de início
  - `status` (enum) — `ACTIVE`, `INACTIVE`, `CANCELED`
- `pix` (object) — `code`, `image`, `base64` (DEPRECATED). Sempre retornado.
- `details` (string), `errorDescription` (string).

Exemplo de requisição:

```json
{
  "identifier": "dhcnkqzh10",
  "amount": 80,
  "client": {
    "name": "João da Silva",
    "email": "joao@gmail.com",
    "phone": "(11) 99999-9999",
    "document": "123.456.789-00"
  },
  "product": { "id": "8p5a13m4mlli", "name": "Produto 1", "quantity": 1, "price": 80 },
  "dueDate": "2026-09-08",
  "metadata": { "key1": "value1", "key2": "value2" },
  "subscription": { "periodicityType": "MONTHS", "periodicity": 1, "firstChargeIn": 0 },
  "callbackUrl": "https://minha.api.com/pix/callback/b8jwfod1tv"
}
```

Exemplo de retorno `200 OK`:

```json
{
  "transactionId": "clwuwmn4i0007emp9lgn66u1h",
  "status": "OK",
  "webhookToken": "webhookToken123",
  "pix": {
    "code": "00020101021126530014BR.GOV.BCB.PIX...",
    "base64": "",
    "image": "https://api.gateway.com/pix/qr/00020101021126530014BR.GOV.BCB.PIX..."
  },
  "subscription": {
    "id": "cm9hf2cly0004xwvpl5mt1yj7",
    "periodicity": 1,
    "periodicityType": "MONTHS",
    "nextChargeAt": "2025-05-14T18:38:00.021Z",
    "startAt": "2025-04-14T18:38:00.021Z",
    "status": "INACTIVE"
  }
}
```

## 8.14. POST /gateway/card/subscription — Assinatura cartão

Recebe pagamentos recorrentes via cartão. **Requer autenticação.**

```
POST https://app.checkto.com.br/api/v1/gateway/card/subscription
```

Body: os mesmos campos de `/gateway/pix/subscription`, mais `clientIp` (string, **obrigatório** — IPv4 do cliente) e `card` (object, **obrigatório** — `number`, `owner`, `expiresAt` no formato `YYYY-MM`, `cvv`, `statementDescriptor`).

Retorno `200 OK`: `transactionId`, `status`, `transactionStatus`, `webhookToken`, `fee`, `order`, `subscription`, `details`, `errorDescription` — sem objeto `pix`.

Exemplo de requisição:

```json
{
  "identifier": "2x5ky8hyt7",
  "amount": 80,
  "client": {
    "name": "João da Silva",
    "email": "joao@gmail.com",
    "phone": "(11) 99999-9999",
    "document": "123.456.789-00",
    "address": {
      "country": "BR",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Centro",
      "zipCode": "12345-678",
      "street": "Rua do Centro",
      "number": "123",
      "complement": "Sala 1"
    }
  },
  "clientIp": "127.0.0.1",
  "card": {
    "number": "4111111111111111",
    "owner": "João da Silva",
    "expiresAt": "2026-09",
    "cvv": "123",
    "statementDescriptor": "MINHA LOJA"
  },
  "product": { "id": "zetbcbtqowce", "name": "Produto 1", "quantity": 1, "price": 80 },
  "metadata": { "key1": "value1", "key2": "value2" },
  "subscription": { "periodicityType": "MONTHS", "periodicity": 1, "firstChargeIn": 0 },
  "callbackUrl": "https://minha.api.com/card/callback/4oqk7vdvdj"
}
```

Exemplo de retorno `200 OK`:

```json
{
  "transactionId": "clwuwmn4i0007emp9lgn66u1h",
  "status": "OK",
  "webhookToken": "webhookToken123",
  "subscription": {
    "id": "cm9hf2cly0004xwvpl5mt1yj7",
    "periodicity": 1,
    "periodicityType": "MONTHS",
    "nextChargeAt": "2025-05-14T18:38:00.021Z",
    "startAt": "2025-04-14T18:38:00.021Z",
    "status": "INACTIVE"
  }
}
```

## 8.15. POST /gateway/crypto/subscription — Assinatura cripto

Recebe pagamentos recorrentes via criptomoeda. **Requer autenticação.**

```
POST https://app.checkto.com.br/api/v1/gateway/crypto/subscription
```

Body: os mesmos campos de `/gateway/pix/subscription`, mais:

- `crypto` (object, **obrigatório**):
  - `currency` (enum, obrigatório) — moeda que deseja realizar a transação
  - `network` (enum, obrigatório) — `BDM_DIGITAL`, `BSC`, `ETH`, `BTC`, `POLYGON`, `TRON`, `BASE`, `TON`, `SOLANA`

Retorno: mesma estrutura da assinatura Pix, com os dados do pagamento em cripto no lugar do objeto `pix`.

## 8.16. POST /gateway/checkout — Criar checkout

Cria uma oferta e um link de Checkout hospedado. **Requer autenticação.** É necessário que a empresa tenha a opção de criação de checkout via API ativada — solicite ao suporte a ativação do módulo na sua conta.

```
POST https://app.checkto.com.br/api/v1/gateway/checkout
```

Body (`application/json`):

- `product` (object, **obrigatório**) — detalhes do produto:
  - `externalId` (string, obrigatório) — ID do produto na plataforma externa
  - `name` (string, obrigatório) — nome do produto
  - `photos` (array de string) — URLs de fotos do produto
  - `offer` (object, obrigatório) — detalhes da oferta:
    - `name` (string, obrigatório) — nome da oferta
    - `price` (number, obrigatório) — preço da oferta
    - `offerType` (enum, obrigatório) — `INTERNATIONAL`, `NATIONAL`, `UNDEFINED`
    - `currency` (enum) — moeda aceita (ex.: BRL, USD) ou `all`. Padrão: `all`
    - `lang` (enum) — idioma/localização: `pt-BR`, `en`, `es`, `pt`, `fr`, `ja`, `zh`, `ar`, `it`, `de`, `all`. Padrão: `all`
    - `warranty` (string) — prazo de garantia da oferta. Padrão: `7_days`
    - `type` (string) — tipo livre da oferta
    - `category` (string) — categoria livre da oferta
- `settings` (object, **obrigatório**) — configurações do checkout:
  - `paymentMethods` (enum array) — métodos aceitos: `PIX`, `CREDIT_CARD`, `BOLETO`, `CRYPTO`, `CASH_ON_DELIVERY`, `GOOGLE_PAY`, `APPLE_PAY`. Padrão: todos
  - `acceptedDocs` (enum array) — `CPF`, `CNPJ`. Padrão: `CPF`
  - `thankYouPage` (string) — URL de redirecionamento pós-compra. Padrão: vazio
  - `askForAddress` (boolean, obrigatório) — solicitar endereço
  - `colors` (object) — cores do checkout em hexadecimal (ex.: `#FF9900`):
    - `primaryColor` — cor primária
    - `text` — cor do texto
    - `background` — cor de fundo
    - `purchaseButtonBackground` — fundo do botão de compra
    - `purchaseButtonText` — texto do botão de compra
    - `widgets` — todos os elementos que ficam por cima do background
    - `inputBackground` — fundo dos inputs
    - `inputText` — texto dos inputs
- `customer` (object) — dados do cliente para auto-preenchimento:
  - `name`, `email`, `phone`, `document` (string)
  - `address` (object) — `street`, `number`, `city`, `state`, `zipCode`, `neighborhood`, `complement`
- `trackProps` (record) — propriedades adicionais de rastreamento (chave-valor).

Retorno `200 OK`:

- `productId` (string) — ID do produto criado ou reutilizado. Sempre retornado.
- `offerCode` (string) — código da oferta aplicado ao checkout. Sempre retornado.
- `checkoutUrl` (string) — URL para redirecionar o cliente ao checkout. Sempre retornado.

Exemplo de requisição:

```json
{
  "product": {
    "name": "Produto de Teste",
    "externalId": "A-10",
    "photos": ["https://example.com/image.jpg"],
    "offer": {
      "name": "Oferta Padrão",
      "price": 40000,
      "offerType": "NATIONAL",
      "currency": "all",
      "lang": "pt-BR"
    }
  },
  "settings": {
    "paymentMethods": ["BOLETO", "PIX", "CREDIT_CARD"],
    "acceptedDocs": ["CPF"],
    "thankYouPage": "",
    "askForAddress": false,
    "colors": {
      "primaryColor": "#03FF1C",
      "text": "#FFFFFF",
      "background": "#000000",
      "purchaseButtonBackground": "#03FF1C",
      "purchaseButtonText": "#000000",
      "widgets": "#111111",
      "inputBackground": "#444444",
      "inputText": "#EEEEEE"
    }
  },
  "customer": {
    "name": "Joao dos santos",
    "email": "joao@gmail.com",
    "phone": "7399999-9999",
    "document": "098.232.664-43",
    "address": {
      "street": "Rua das Flores",
      "number": "123",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01234-567",
      "neighborhood": "Centro",
      "complement": "Apto 45"
    }
  },
  "trackProps": {
    "utm_source": "asdaczx123",
    "utm_content": "cndasd1231",
    "external_id": "meu-id-aqui"
  }
}
```

Exemplo de retorno `200 OK`:

```json
{
  "productId": "cmar9fp6700176uvcmjh6gjkd",
  "offerCode": "4a222a1f",
  "checkoutUrl": "https://apidaminhagateway.com.br/checkout/cmar9fp6700176uvcmjh6gjkd?offer=4a222a1f&name=Joao+dos+santos&email=joao%40gmail.com&phone=7399999-9999&document=098.232.664-43&street=Rua+das+Flores&number=123&city=São+Paulo&state=SP&zipCode=01234-567&neighborhood=Centro&complement=Apto+101"
}
```

Os dados de `customer` e `trackProps` são anexados como search params na `checkoutUrl` para auto-preencher o formulário.

## 8.17. GET /utils/exchange-rates — Taxas de câmbio

Calcula taxas de câmbio entre moedas. Informe a moeda de origem, a de destino e o valor a converter.

```
GET https://app.checkto.com.br/api/v1/utils/exchange-rates?from=string&to=string&amount=string
```

Query parameters:

- `from` (enum, **obrigatório**) — moeda de origem para conversão.
- `to` (enum, **obrigatório**) — moeda de destino para conversão.
- `amount` (number, **obrigatório**) — quantidade a ser convertida da moeda de origem.

Retorno `200 OK`:

- `convertedAmount` (number) — valor convertido da moeda de origem para a de destino. Sempre retornado.
- `exchangeRate` (number) — taxa de câmbio atual entre as moedas. Sempre retornado.

Exemplo de requisição:

```json
{ "from": "BRL", "to": "USD", "amount": 100 }
```

Exemplo de retorno:

```json
{ "convertedAmount": 19.99, "exchangeRate": 5.00 }
```

## 8.18. Buscar transferência

Consulta uma transferência/saque. A página existe na documentação mas não está listada no menu lateral, e o path da rota não é exibido.

Retorno:

- `id` (string) — identificador da transferência
- `clientIdentifier` (string) — seu identificador
- `amount` (number) — valor
- `currency` (string) — moeda
- `status` (enum) — status da transferência
- `withdrawSent` (array) — envios realizados:
  - `id` (string), `amount` (number), `status` (enum), `message` (string), `endToEndId` (string)
  - `pixMetadata` (object) — `payerBankName`, `payerDocument`, `payerName`, `receiverBankName`, `receiverDocument`, `receiverName`, `receiverPixKey`
  - `createdAt`, `updatedAt` (ISO 8601)
- `createdAt`, `updatedAt` (ISO 8601)

```json
{
  "id": "xyz123abc456def789ghi012j",
  "clientIdentifier": "abcdefg123456",
  "amount": 50,
  "currency": "BRL",
  "status": "PENDING",
  "withdrawSent": [
    {
      "id": "klm456nop789qrs012tuv345w",
      "amount": 50,
      "status": "PENDING",
      "message": "Transação em análise pelo provedor de pagamento.",
      "endToEndId": "12345",
      "pixMetadata": {
        "payerBankName": "Banco do Brasil",
        "payerDocument": "123.456.789-00",
        "payerName": "João da Silva",
        "receiverBankName": "Caixa Econômica Federal",
        "receiverDocument": "987.654.321-00",
        "receiverName": "Maria da Silva",
        "receiverPixKey": "98765432100"
      },
      "createdAt": "2025-06-15T09:45:12.123Z",
      "updatedAt": "2025-06-15T09:45:12.456Z"
    },
    {
      "id": "def789ghi012jkl345mno678p",
      "amount": 50,
      "status": "FAILED",
      "message": "Saldo insuficiente para realizar a transação.",
      "endToEndId": "12345",
      "createdAt": "2025-06-16T14:20:30.789Z",
      "updatedAt": "2025-06-16T14:20:31.012Z"
    }
  ],
  "createdAt": "2025-06-10T08:15:25.678Z",
  "updatedAt": "2025-06-16T14:20:45.234Z"
}
```

---

# 9. Limitações e erros comuns

## 9.1. API bloqueada por localização

**Sintoma:** a API responde uma página HTML de erro 403 em vez de JSON.

```html
<body data-page="error" data-status="403">
  <div class="status-code">HTTP <span id="code">403</span></div>
  ...
</body>
```

**Causa:** medida de segurança da plataforma. A API tem um firewall que monitora a origem das requisições e bloqueia as que vêm de locais incomuns ou considerados suspeitos, protegendo a plataforma e os integradores contra ataques. A infraestrutura usa **CloudFront** (CDN da AWS) e **AWS WAF** (Web Application Firewall).

**Locais aceitos:** Brasil, Estados Unidos, Portugal e outros locais considerados seguros.

**Solução:** alterar a origem das requisições para um dos locais aceitos —

- usar um servidor localizado em um dos países aceitos;
- usar uma VPN com servidor em um país aceito;
- usar serviços de cloud (AWS, Google Cloud, Azure) com data centers nos países aceitos.

**Não é possível solicitar exceção ou whitelist de IPs para esse tipo de bloqueio.**

## 9.2. Bucket de vendas pendentes

**Sintoma:**

```json
{
  "success": false,
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Sua conta atingiu o limite de vendas pendentes para este metodo de pagamento. Aguarde a liberacao do limite ou a atualizacao das vendas pendentes."
  }
}
```

**Causa:** proteção operacional para contas com limite de vendas pendentes configurado. Evita que a conta acumule muitas transações aguardando pagamento em um curto intervalo. O funcionamento é parecido com mecanismos de segurança do Pix, como o DICT: ao atingir um limite de risco ou volume, novas operações são restringidas temporariamente.

**Nem todas as contas são bloqueadas.** Depende da configuração operacional, do perfil da conta e do método de pagamento.

**Como o bucket funciona:**

- Cada venda pendente consome uma unidade do limite configurado para aquele método de pagamento.
- Enquanto a transação estiver `PENDING`, a unidade continua ocupada.
- Se a venda for paga, cancelada, recusada ou reembolsada, a unidade é liberada.
- Se a janela de tempo expirar, o limite é renovado automaticamente.
- O controle é **separado por método de pagamento** (`PIX`, `CREDIT_CARD`, `BOLETO`).

**Exemplo:** conta configurada para 100 vendas Pix pendentes numa janela de 10 minutos — as 100 primeiras são criadas normalmente; a 101ª pode receber `TOO_MANY_REQUESTS`; quando uma pendente for paga/cancelada ou a janela expirar, uma nova venda pode ser criada.

**Como reduzir a ocorrência:**

- Evite criar múltiplas transações para o mesmo pedido ou cliente sem necessidade.
- Aguarde a atualização do status via webhook antes de gerar nova cobrança para a mesma intenção de compra.
- Use o campo `identifier` para reaproveitar a referência do seu pedido e evitar duplicidade.
- Implemente retentativas com espera progressiva ao receber `TOO_MANY_REQUESTS`.

## 9.3. Polling bloqueado

**Sintoma:**

```json
{
  "success": false,
  "error": {
    "code": "TOO_MANY_REQUESTS",
    "message": "Tentativa de polling bloqueada. Receba atualizações via webhook."
  }
}
```

**Causa:** múltiplas requisições de consulta em curto período sobrecarregam os servidores e afetam a performance de outros produtores. A Checkto foi projetada para funcionar de forma assíncrona: você cria a transação e recebe um ID, aguarda o pagamento e recebe as notificações via webhook.

**Fluxo correto:**

1. Ao criar a transação, envie `callbackUrl` com a URL do seu servidor.
2. Quando o status mudar (ex.: de `PENDING` para pago), a Checkto envia um webhook para o `callbackUrl`.
3. Seu servidor processa o webhook e atualiza o status do pedido internamente.

**Quando usar as rotas de consulta:**

- Quando o webhook não chegou após um tempo razoável (mais de 5 minutos).
- Para reconciliação (verificar transações que não foram notificadas).
- Verificação pontual para tickets de suporte.

**Exemplo de implementação correta:**

```js
// Ao criar a transação, passe o callbackUrl
const transaction = await createTransaction({
  amount: 100.00,
  callbackUrl: "https://seu-servidor.com/webhook/transaction"
})

// Não faz mais polling! Agora é só esperar o webhook chegar

// Seu endpoint de webhook
app.post("/webhook/transaction", async (req, res) => {
  const { id, status } = req.body
  await updateOrderStatus(id, status)   // Atualiza o pedido no seu banco
  res.status(200).send("OK")
})
```

---

# 10. Propagação de parâmetros até o checkout

Ferramenta para manter UTMs, códigos de afiliado e outros parâmetros da campanha quando a página de vendas está em um domínio externo e o visitante segue para o checkout.

**Quando usar:** quando os visitantes precisam chegar ao checkout sem perder informações recebidas no link da campanha:

- UTMs de mídia, como `utm_source`, `utm_medium` e `utm_campaign`
- Códigos de afiliado, como `code`
- Parâmetros personalizados das suas ferramentas de rastreamento

**Como instalar:** na ferramenta usada para criar sua página de vendas, abra a área que permite inserir código no HTML e cole o trecho abaixo antes de fechar a tag `</body>`:

```html
<script src="https://app.checkto.com.br/scripts/url-params-propagation.js"></script>
```

Use o mesmo código em todas as páginas da oferta que tenham links para o checkout, incluindo pré-venda, upsell e downsell.

**Como funciona:** ao carregar a página, o script localiza os links cujo endereço contém `/checkout` e adiciona a eles todos os parâmetros da URL atual. Nenhum parâmetro precisa ser listado ou configurado individualmente. Exemplo: ao acessar a página com `?utm_source=instagram&code=afiliado123`, o link para o checkout passará a incluir esses mesmos parâmetros.

**Como validar a instalação:**

1. Publique ou atualize sua página de vendas com o script instalado.
2. Abra a página usando um link com parâmetros de teste.
3. Clique no botão de checkout.
4. Confirme que os mesmos parâmetros aparecem na URL do checkout.

**Limitações:**

- Não use encurtadores de link que removam os parâmetros da URL original.
- Se os botões de checkout forem criados depois do carregamento da página, execute o script novamente após criá-los.

---

# 11. Integração com ferramentas de IA

A documentação da Checkto tem um botão **"Integrar com IA"** em cada página de endpoint e em cada evento de webhook. Ao clicar, as instruções completas da integração são copiadas para a área de transferência em formato otimizado para IAs (Claude, ChatGPT, Cursor, Lovable, Bolt e outras).

**Informações incluídas ao copiar:**

- Método e URL do endpoint
- Autenticação com os headers `x-public-key` e `x-secret-key`
- Campos do body, com tipo, obrigatoriedade e descrição
- Query parameters, quando aplicável
- Estrutura das respostas de sucesso e erro
- Exemplos de requisição e resposta em JSON

**Dicas para melhores resultados:**

- Seja específico sobre seu stack (linguagem, frameworks e bibliotecas).
- Peça tratamento adequado para os códigos de erro da API.
- Solicite tipagem (interfaces/types) se estiver usando TypeScript.
- Itere sobre o código gerado, pedindo ajustes e melhorias.

**Credenciais:** nunca compartilhe suas credenciais com a IA. Use placeholders como `SUA_CHAVE_PUBLICA` e `SUA_CHAVE_SECRETA` e substitua-os depois de gerar o código.

**Perguntas frequentes:**

- **As instruções funcionam com qualquer IA?** Sim. O formato é texto estruturado em Markdown, compatível com qualquer ferramenta que aceite texto como entrada, incluindo Claude, ChatGPT, Gemini, Copilot, Cursor, Lovable e Bolt.
- **Preciso copiar as instruções toda vez?** Para múltiplas integrações, copie as instruções de cada endpoint separadamente. Para um mesmo endpoint, reutilize enquanto não houver atualizações na API.
- **A IA sempre gera código correto?** Não. O código gerado deve ser revisado e testado: verifique credenciais, campos obrigatórios e o tratamento de erros.
- **Posso usar em produção?** As instruções fornecem a estrutura correta da API, mas o código gerado pela IA deve passar por revisão, testes e adequação às práticas de segurança do seu projeto.