Quickstart

1. 1

   Step 1: Get your test keys

   Copy the test secret key from the developer area of the dashboard.

2. 2

   Step 2: Store the secret key

   Keep it in an environment variable on your server, never in the browser.

3. 3

   Step 3: Create a charge

   Call POST /v1/charges with an amount, a description and the accepted methods.

4. 4

   Step 4: Pay in the test checkout

   Open the checkout_url and pay with a test card or the Pix simulation.

5. 5

   Step 5: Confirm the payment

   Receive charge.paid on your webhook, or read the charge and check status.

• A terminal with curl, or any JavaScript runtime with a global fetch (Node.js 18 or later, Deno, Bun).
• Access to the demo dashboard. Everything in it is test data.

Open Developers → API keys. You will find two keys: the secret key (kp_test_sk_…), used by your server for every API call, and the publishable key (kp_test_pk_…), reserved for future client-side use. This guide only needs the secret key.

Put the key in an environment variable called KROKOPAY_SECRET_KEY. The rest of the documentation reads it from there, so no example contains a key you could commit by accident.

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

Send the amount in centavos, the currency, a description the buyer will see and the methods you accept. The Idempotency-Key header makes the call safe to retry: sending it again with the same key never creates a second charge (see Idempotency).

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

The charge comes back as pending with method: null, because the buyer has not chosen Pix or card yet. Keep the id with your order.

Redirect the buyer to checkout_url (https://krokopay.app/pay/{id}). In the test environment you are the buyer:

// 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

• Card: use 4242 4242 4242 4242 with any future expiry date and any CVC. The payment is approved.
• Pix: choose Pix to get a fictional QR code, then open Demo controls and press Confirm Pix payment.

To try this today, create a charge in Payments → New payment and open its checkout link: the flow is the same one your buyers will see.

When the buyer pays, KrokoPay sends a charge.paid event to your webhook endpoint. Fulfill the order there, after verifying the signature (see 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"    }  }}

Without a webhook you can read the charge and check that status is paid:

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

• Try a declined card and the other outcomes in test cards.
• Handle charge.failed and charge.expired as well: see Errors.
• Sell without code using payment links.