Checkout

O checkout é a página onde o comprador paga. Ele é hospedado pela KrokoPay, leva a sua marca e funciona com dois tipos de id: uma cobrança criada pela API ou um link de pagamento que você compartilha quantas vezes quiser. Você nunca renderiza campos de cartão, então os números de cartão nunca passam pelos seus servidores.

Todo checkout fica em https://krokopay.app/pay/{id}. O id define o que o comprador vê:

• chg_…: uma cobrança criada com POST /v1/charges. O checkout_url dela já aponta para cá. Uma cobrança, um pagamento.
• plink_…: um link de pagamento. O url dele aponta para cá. Cada comprador que envia o formulário gera uma nova cobrança, com o link_id preenchido.

# A charge created through the API (returned as checkout_url)https://krokopay.app/pay/chg_9Qs5MbT2kXn8Vd​# A payment link (returned as url): reusable, one charge per buyerhttps://krokopay.app/pay/plink_2Wn6HsT9cVb4Lq

// In the browser. Your own endpoint creates the charge with the secret key// and returns only its checkout_url.const response = await fetch("/api/orders/1042/checkout", { method: "POST" });if (!response.ok) throw new Error("Could not start the checkout");const { checkout_url } = (await response.json()) as { checkout_url: string };window.location.assign(checkout_url);

1. 1

   Passo 1: Sua marca e o pedido

   No topo, o nome de exibição, o quadro com as suas iniciais e o slogan; logo abaixo, a descrição e o valor em BRL.

2. 2

   Passo 2: Um meio de pagamento

   Só os meios permitidos pela cobrança ou pelo link (methods).

3. 3

   Passo 3: Pix

   Um QR Code e um código copia e cola, com contagem regressiva até o expires_at (15 minutos no ambiente de teste; o prazo em produção ainda será definido).

4. 4

   Passo 4: Cartão

   Número, validade, CVC e nome do titular, validados no navegador antes do envio. Só a bandeira e os quatro últimos dígitos são guardados.

5. 5

   Passo 5: Dados do pagador

   Nome e e-mail, usados para encontrar um cliente existente pelo e-mail ou criar um novo.

6. 6

   Passo 6: O resultado

   Um comprovante quando o pagamento é aprovado, ou uma mensagem clara com o próximo passo quando ele não pode ser concluído.

O checkout lê a sua marca nas configurações da conta, não na requisição. Altere uma vez em Configurações e todas as cobranças e links passam a usá-la.

A mesma URL mostra telas diferentes conforme o estado da cobrança ou do link por trás dela.

Reproduza todos os estados com os cartões de teste abaixo (qualquer validade futura e qualquer CVC funcionam) ou deixando a contagem do Pix terminar. Mais detalhes em Ambiente de teste.

O checkout está disponível em inglês e em português do Brasil. O padrão vem da preferência de idioma do checkout em Configurações: auto segue o navegador do comprador, ou você pode fixar em en ou pt-br. Os valores aparecem sempre na moeda da cobrança (BRL), seja qual for o idioma.

Quando o pagamento é confirmado, a cobrança passa para paid e a KrokoPay envia charge.paid para os seus endpoints de webhook. Libere o pedido a partir do webhook, não do navegador: o comprador pode fechar a aba antes de chegar a qualquer página sua.

{  "id": "evt_6Ff7Gg8Hh9Ii0J",  "object": "event",  "type": "charge.paid",  "api_version": "2026-11-01",  "created_at": "2026-11-03T14:23:41.000Z",  "data": {    "object": {      "id": "chg_4Fp9KzW1xQm7Rt",      "object": "charge",      "amount": 49700,      "currency": "BRL",      "status": "paid",      "method": "pix",      "card": null,      "description": "Curso Identidade Visual do Zero",      "customer_id": "cus_8Hq2LmZr4TxN1a",      "product_id": "prod_3Vb7QpK9sWd2Ee",      "price_id": "price_5Kd1NcR8vYq3Hm",      "link_id": "plink_2Wn6HsT9cVb4Lq",      "subscription_id": null,      "fee": null,      "net": null,      "refunded_amount": 0,      "failure_code": null,      "created_at": "2026-11-03T14:22:05.000Z",      "paid_at": "2026-11-03T14:23:41.000Z",      "expires_at": "2026-11-03T14:37:05.000Z",      "available_at": null,      "checkout_url": "https://krokopay.app/pay/chg_4Fp9KzW1xQm7Rt"    }  }}

• Tentativa recusada: charge.failed, com o failure_code na cobrança.
• Pix não pago a tempo: charge.expired.
• Pagar um link com preço recorrente também emite subscription.created. Veja Assinaturas.

Um link de pagamento é um checkout reutilizável: compartilhe o url dele por e-mail, em uma conversa ou num botão. Ele cobra um preço do catálogo (price_id) ou um valor fixo (amount).

curl -X POST https://api.krokopay.app/v1/payment_links \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Content-Type: application/json" \  -d '{    "name": "Curso Identidade Visual do Zero",    "price_id": "price_5Kd1NcR8vYq3Hm",    "methods": [      "pix",      "card"    ]  }'

curl -X POST https://api.krokopay.app/v1/payment_links \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Content-Type: application/json" \  -d '{    "name": "Consultoria — 1 hora",    "description": "Sessão online de uma hora.",    "amount": 25000,    "methods": [      "pix"    ]  }'

curl https://api.krokopay.app/v1/payment_links \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b"

Atualiza name, description, methods ou active. As mudanças valem para o próximo comprador; cobranças já criadas mantêm o valor original.

Remove um link. Se ele já tiver cobranças, o link é desativado (active: false) em vez de removido, para preservar o histórico, e a URL passa a mostrar o estado indisponível.

curl -X DELETE https://api.krokopay.app/v1/payment_links/plink_2Wn6HsT9cVb4Lq \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b"

• Criando cobranças: a cobrança por trás de cada checkout.
• Webhooks: verifique e trate o charge.paid.
• Ambiente de teste: cartões de teste e Pix simulado.