Guia rápido

1. 1

   Passo 1: Pegue suas chaves de teste

   Copie a chave secreta de teste na área de desenvolvedores do painel.

2. 2

   Passo 2: Guarde a chave secreta

   Deixe-a numa variável de ambiente do seu servidor, nunca no navegador.

3. 3

   Passo 3: Crie uma cobrança

   Chame POST /v1/charges com um valor, uma descrição e os métodos aceitos.

4. 4

   Passo 4: Pague no checkout de teste

   Abra o checkout_url e pague com um cartão de teste ou com a simulação de Pix.

5. 5

   Passo 5: Confirme o pagamento

   Receba charge.paid no seu webhook, ou consulte a cobrança e confira o status.

• Um terminal com curl, ou qualquer ambiente JavaScript com fetch global (Node.js 18 ou mais recente, Deno, Bun).
• Acesso ao painel de demonstração. Tudo nele são dados de teste.

Abra Desenvolvedores → Chaves de API. Lá estão duas chaves: a chave secreta (kp_test_sk_…), que o seu servidor usa em toda chamada à API, e a chave publicável (kp_test_pk_…), reservada para uso futuro no navegador. Este guia só precisa da chave secreta.

Coloque a chave numa variável de ambiente chamada KROKOPAY_SECRET_KEY. O resto da documentação lê a chave dali, então nenhum exemplo contém uma chave que você possa versionar por engano.

# Current terminal session only. Paste the test secret key from the dashboard.export KROKOPAY_SECRET_KEY="kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b"

Envie o valor em centavos, a moeda, uma descrição que o comprador vai ver e os métodos que você aceita. O cabeçalho Idempotency-Key torna a chamada segura para repetir: reenviar com a mesma chave nunca cria uma segunda cobrança (veja Idempotência).

curl -X POST https://api.krokopay.app/v1/charges \  -H "Authorization: Bearer $KROKOPAY_SECRET_KEY" \  -H "Idempotency-Key: order_1042" \  -H "Content-Type: application/json" \  -d '{    "amount": 49700,    "currency": "BRL",    "description": "Curso Identidade Visual do Zero",    "customer_id": "cus_8Hq2LmZr4TxN1a",    "methods": [      "pix",      "card"    ]  }'

A cobrança volta como pending e com method: null, porque o comprador ainda não escolheu entre Pix e cartão. Guarde o id junto com o seu pedido.

Redirecione o comprador para o checkout_url (https://krokopay.app/pay/{id}). No ambiente de teste, o comprador é você:

// After creating the charge on your server, send the buyer to its hosted checkout.const charge = await response.json();​// Express-style handler: redirect the browser.res.redirect(303, charge.checkout_url);// → https://krokopay.app/pay/chg_9Qs5MbT2kXn8Vd

• Cartão: use 4242 4242 4242 4242 com qualquer validade futura e qualquer CVC. O pagamento é aprovado.
• Pix: escolha Pix para receber um QR Code fictício, abra os Controles de demonstração e toque em Confirmar pagamento Pix.

Para testar hoje, crie uma cobrança em Pagamentos → Novo pagamento e abra o link do checkout: o fluxo é o mesmo que os seus compradores vão ver.

Quando o comprador paga, a KrokoPay envia um evento charge.paid para o seu endpoint de webhook. Libere o pedido ali, depois de verificar a assinatura (veja Webhooks).

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

Sem webhook, você pode consultar a cobrança e conferir se o status é paid:

curl https://api.krokopay.app/v1/charges/chg_4Fp9KzW1xQm7Rt \  -H "Authorization: Bearer $KROKOPAY_SECRET_KEY"

• Teste um cartão recusado e os outros resultados nos cartões de teste.
• Trate também charge.failed e charge.expired: veja Erros.
• Venda sem código com links de pagamento.