Checkout hospedado 🧾

O checkout hospedado é uma página de pagamento pronta, hospedada pela PagNow, que você abre para o seu cliente sem precisar construir tela nenhuma. Ele já vem com todos os métodos disponíveis para a moeda da cobrança, múltiplos idiomas e a identidade visual do seu modelo de checkout (ver Modelos de checkout).

É 100% opcional e aditivo: se você não enviar o campo checkout na criação da cobrança, nada muda — a API responde exatamente como sempre respondeu. O checkout hospedado é um plus que você ativa quando quiser.

Como funciona

Basta adicionar o campo opcional checkout no POST /v1/payments, apontando para o slug de um modelo de checkout que você configurou no painel. A resposta ganha um campo checkoutUrl — a URL da página hospedada, pronta para redirecionar o cliente.

curl -X POST 'https://v2.pagnow.com/v1/payments' \
  -H 'apikey: pnk_sua_chave_aqui' \
  -H 'content-type: application/json' \
  -d '{
    "amount": 1990,
    "currency": "BRL",
    "idempotencyKey": "pedido-123",
    "customerEmail": "joao@exemplo.com",
    "checkout": "meu-modelo",
    "metadata": { "orderId": "ORD-456" }
  }'

Resposta (campos relevantes):

{
  "id": "a1b2c3d4-....",
  "status": "PENDING",
  "amount": 1990,
  "currency": "BRL",
  "checkoutUrl": "https://checkout.v2.pagnow.com/a1b2c3d4-....",
  "paymentMethods": ["PIX", "CREDIT_CARD"]
}

Redirecione o cliente para checkoutUrl e a PagNow cuida do resto: exibição dos métodos, QR/copia-e-cola do PIX com contador, campos de contato/endereço (se o modelo pedir), tradução automática pelo idioma do navegador e confirmação.

Os métodos são resolvidos pela moeda

Você não precisa listar paymentMethods quando usa o checkout hospedado. O modelo resolve automaticamente os métodos disponíveis para a currency da cobrança (por exemplo, PIX para BRL; métodos locais europeus para EUR), respeitando qualquer preferência de ordem ou destaque configurada no modelo.

Se você enviar paymentMethods junto, ele continua valendo como filtro — a interseção entre o que você pediu e o que é roteável naquela moeda é o que aparece.

Sem o campo checkout

Sem checkout, o comportamento é idêntico ao de sempre: você controla os métodos por paymentMethods, recebe pixCopyPaste/pixQrCode (ou os artefatos do método escolhido) e monta o seu próprio fluxo. checkoutUrl só aparece na resposta quando a cobrança foi criada a partir de um modelo.

Idempotência

O campo checkout participa da idempotência: reenviar a mesma idempotencyKey com o mesmo slug retorna a cobrança original (e a mesma checkoutUrl). Reenviar a mesma chave com um slug diferente é tratado como conflito, como qualquer outra divergência de payload.

Próximos passos

• Modelos de checkout — como criar e customizar (visual, idiomas, campos, endereço, métodos, moedas) no painel.
• Links de pagamento — cobrar sem criar a transação você mesmo: um link compartilhável, com seletor de moeda embutido.