> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Criar checkout links

> Crie um checkout link hospedado com API key — referencie seus produtos por external_id ou gere um link só-valor.

Use este endpoint para criar um checkout link hospedado a partir do seu backend ou de uma ferramenta
no-code/IA, do mesmo jeito que você cria transações. A autenticação é por API key; o tenant e a
company são resolvidos pelo token. A resposta é só a URL final do checkout.

## Caminho feliz

1. Chame `POST /v2/checkout-links` com sua API key.
2. Envie `products[]` (referenciados pelo seu próprio `external_id`) **ou** um `amount` só-valor.
3. A Pagou faz upsert de cada produto por `external_id`, monta o link e anexa automaticamente os
   métodos de pagamento ativos da company e qualquer order bump / upsell elegível.
4. Use a `data.url` retornada — ela já vem com o domínio custom quando há um ativo.

## Autenticação

Envie sua API key secreta como Bearer token (a mesma usada em [transações](/pt/api-reference/transactions/create)):

```
Authorization: Bearer SUA_API_KEY
```

O header `x-api-key: SUA_API_KEY` também é aceito.

## Produtos por external\_id (upsert)

Cada item de `products[]` é identificado pelo **`external_id`** — o seu próprio identificador do
produto. A cada chamada a Pagou faz **upsert** por `(company, external_id)`:

* **Primeira vez:** cria o produto no seu catálogo (`origin = api`).
* **Próximas vezes:** reutiliza o mesmo produto e **atualiza** nome/preço/campos a partir do payload
  (revivendo se estava arquivado). Nunca duplica.

Você não precisa saber os ids internos da Pagou — `external_id` é o único identificador que você passa.

<Note>
  Preços são inteiros em **centavos** (`7990` = R\$ 79,90). Reenviar o mesmo `external_id` sobrescreve
  nome, preço, descrição e imagem do produto a partir do payload, então envie sempre o estado completo
  do produto que você quer.
</Note>

### Exemplo de requisição — produtos

```bash theme={null}
curl --request POST \
  --url https://api.pagou.ai/v2/checkout-links \
  --header "Authorization: Bearer SUA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "BRL",
    "title": "Pedido #1042",
    "products": [
      {
        "external_id": "SKU-CAMISETA-PRETA-M",
        "name": "Camiseta Preta M",
        "price": 7990,
        "quantity": 2,
        "type": "physical",
        "image_url": "https://cdn.example.com/camiseta.jpg",
        "compare_price": 9990
      }
    ]
  }'
```

## Link só-valor

Omita `products` e envie `amount` (em centavos) para gerar um link rápido, só-valor. O `title` é
opcional — quando ausente, é gerado automaticamente.

```bash theme={null}
curl --request POST \
  --url https://api.pagou.ai/v2/checkout-links \
  --header "Authorization: Bearer SUA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{ "currency": "BRL", "amount": 15000 }'
```

Envie **ou** `products` **ou** `amount` — nunca os dois, nunca nenhum.

## Exemplo de resposta

```json theme={null}
{
  "success": true,
  "requestId": "req_1201",
  "data": {
    "url": "https://checkout.pagou.ai/chk_01J8Z..."
  }
}
```

## Campos da requisição

| Campo                      | Tipo               | Obrigatório | Notas                                                 |
| -------------------------- | ------------------ | ----------- | ----------------------------------------------------- |
| `currency`                 | string             | não         | Moeda do link. Default `BRL`.                         |
| `title`                    | string             | não         | Gerado automaticamente quando ausente.                |
| `amount`                   | inteiro (centavos) | um dos dois | Link só-valor. Mutuamente exclusivo com `products`.   |
| `products[]`               | array              | um dos dois | Link por produtos. Mutuamente exclusivo com `amount`. |
| `products[].external_id`   | string             | sim         | Seu identificador; chave do upsert.                   |
| `products[].name`          | string             | sim         | Nome do produto.                                      |
| `products[].price`         | inteiro (centavos) | sim         | Preço unitário.                                       |
| `products[].quantity`      | inteiro            | não         | Default `1`.                                          |
| `products[].currency`      | string             | não         | Herda a moeda do link.                                |
| `products[].type`          | string             | não         | `physical` ou `digital`. Default `physical`.          |
| `products[].description`   | string             | não         |                                                       |
| `products[].image_url`     | string (url)       | não         |                                                       |
| `products[].compare_price` | inteiro (centavos) | não         | Preço "de" para exibir desconto.                      |

## Erro comum

Status `422` — nem `amount` nem `products` foi enviado (ou os dois foram):

```json theme={null}
{
  "type": "https://api.pagou.ai/problems/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request contains invalid data.",
  "errors": [
    {
      "field": "amount",
      "message": "Either amount or products must be provided.",
      "code": "custom"
    }
  ]
}
```

## Usar com IA

Cole isto no Claude Code, Cursor, Codex, Copilot, Lovable, Bolt, ou qualquer agente de IA:

```text theme={null}
Read https://developer.pagou.ai/llms-full.txt and https://developer.pagou.ai/api-reference/openapi-v2.json

Build a checkout link flow (Pagou-hosted checkout — no card handling on your side):
1. Backend/server function only: POST /v2/checkout-links with an Authorization: Bearer <API key>
2. Body — products: { "currency": "BRL", "title": "<order>", "products": [{ "external_id": "<your id>", "name": "<name>", "price": <cents>, "quantity": <n> }] }
3. Body — value-only: { "currency": "BRL", "amount": <cents> }. Send EITHER products OR amount, never both.
4. external_id is your own product id; re-sending the same id updates that product (no duplicates).
5. Response is { "data": { "url": "<checkout url>" } } — redirect the buyer to data.url.
6. Fulfillment: update the order only after the transaction webhook (event=transaction, data.event_type) confirms payment — not on redirect.

Prices/amount are integers in cents. Keep the API key server-side (env var), never in the browser. Validate all fields against OpenAPI.
```

## Observações

* **Métodos de pagamento** são sempre derivados das permissões ativas da company — você não os passa.
* **Order bumps e upsells** elegíveis para os produtos são anexados automaticamente.
* **Domínio custom** é aplicado na URL retornada quando a company tem um ativo.
* **Fora de escopo (v1):** variantes de produto por `external_id`, assinaturas/recorrência, e editar
  ou listar links pela API.

## Próximos passos

* [Referência de Checkout Links](/pt/api-reference/checkout-links/create)
* [Autenticação](/pt/start-here/authentication)
* [Eventos de pagamento](/pt/webhooks/payment-events)