Pular para o conteúdo principal
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): 
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.
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.

​
Exemplo de requisição — produtos

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
      }
    ]
  }'
Omita products e envie amount (em centavos) para gerar um link rápido, só-valor. O title é opcional — quando ausente, é gerado automaticamente. 
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

{
  "success": true,
  "requestId": "req_1201",
  "data": {
    "url": "https://checkout.pagou.ai/chk_01J8Z..."
  }
}

​
Campos da requisição

CampoTipoObrigatórioNotas
currencystringnãoMoeda do link. Default BRL.
titlestringnãoGerado automaticamente quando ausente.
amountinteiro (centavos)um dos doisLink só-valor. Mutuamente exclusivo com products.
products[]arrayum dos doisLink por produtos. Mutuamente exclusivo com amount.
products[].external_idstringsimSeu identificador; chave do upsert.
products[].namestringsimNome do produto.
products[].priceinteiro (centavos)simPreço unitário.
products[].quantityinteironãoDefault 1.
products[].currencystringnãoHerda a moeda do link.
products[].typestringnãophysical ou digital. Default physical.
products[].descriptionstringnão
products[].image_urlstring (url)não
products[].compare_priceinteiro (centavos)nãoPreço “de” para exibir desconto.

​
Erro comum

Status 422 — nem amount nem products foi enviado (ou os dois foram): 
{
  "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: 
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