Criar checkout links

Use este endpoint para criar um checkout link hospedado a partir do seu back-end ou de uma ferramenta no-code/IA, do mesmo jeito que você cria transações. A API key seleciona a conta autenticada, e a resposta contém a URL final do checkout.

Caminho feliz

Chame POST /v2/checkout-links com sua API key.
Envie products[] (referenciados pelo seu próprio external_id) ou um amount só-valor.
A Pagou faz upsert de cada produto por external_id, monta o link e anexa automaticamente os métodos de pagamento ativos da conta e qualquer order bump ou upsell elegível.
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 desse identificador na conta autenticada:

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.

external_id é o único identificador de produto que sua integração precisa enviar.

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
      }
    ]
  }'

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.

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": "0190a2b4-18a7-7de0-9a43-69b7cf261201",
  "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):

{
  "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:

Leia https://developer.pagou.ai/llms-full.txt e https://developer.pagou.ai/api-reference/openapi-v2.json

Construa um fluxo de link de checkout hospedado pela Pagou, sem manipular cartão:
1. Apenas no back-end/server function: POST /v2/checkout-links com Authorization: Bearer <API key>
2. Body com produtos: { "currency": "BRL", "title": "<pedido>", "products": [{ "external_id": "<seu id>", "name": "<nome>", "price": <centavos>, "quantity": <n> }] }
3. Body só-valor: { "currency": "BRL", "amount": <centavos> }. Envie products OU amount, nunca ambos.
4. external_id é o seu identificador de produto; reenviar o mesmo id atualiza o produto sem duplicá-lo.
5. A resposta é { "data": { "url": "<url do checkout>" } }; redirecione o comprador para data.url.
6. Liberação: atualize o pedido somente quando o webhook de transação (event=transaction, data.event_type) confirmar o pagamento, nunca no redirecionamento.

Preços e valores são inteiros em centavos. Mantenha a API key no servidor em uma variável de ambiente, nunca no navegador. Valide todos os campos no OpenAPI.

Observações

Métodos de pagamento vêm dos métodos habilitados na conta — você não os passa.
Order bumps e upsells elegíveis para os produtos são anexados automaticamente.
Domínio personalizado é aplicado na URL retornada quando a conta 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

Exemplos executáveis

Veja código pronto e testável para este fluxo em Exemplos de Checkout Links — executável em sete linguagens no sandbox.

Pagamentos

Checkout Links

Pix

Vouchers

Cartão

Caminho feliz

Autenticação

Produtos por external_id (upsert)

Exemplo de requisição — produtos

Link só-valor

Exemplo de resposta

Campos da requisição

Erro comum

Usar com IA

Observações

Próximos passos

Exemplos executáveis

​Caminho feliz

​Autenticação

​Produtos por external_id (upsert)

​Exemplo de requisição — produtos

​Link só-valor

​Exemplo de resposta

​Campos da requisição

​Erro comum

​Usar com IA

​Observações

​Próximos passos

​Exemplos executáveis

Caminho feliz

Autenticação

Produtos por external_id (upsert)

Exemplo de requisição — produtos

Link só-valor

Exemplo de resposta

Campos da requisição

Erro comum

Usar com IA

Observações

Próximos passos

Exemplos executáveis