Introduction

KrokoPay is a payments platform with its own checkout. You create a charge on your server, send the buyer to the hosted checkout, and learn the outcome from the API or from a webhook. The buyer pays with Pix or card on a page KrokoPay hosts, so card data never touches your servers.

This documentation describes a provisional contract proposal. The endpoints are not operational yet and no SDK is published: every example is plain cURL or fetch, and field names may still change before launch.

1. 1

   Step 1: Create a charge

   Your server calls POST /v1/charges with the amount in centavos and the accepted methods. The response carries a checkout_url.

2. 2

   Step 2: Send the buyer to the checkout

   Redirect the buyer to checkout_url. They pick Pix or card and pay on the hosted page.

3. 3

   Step 3: Receive the outcome

   KrokoPay sends charge.paid (or charge.failed, charge.expired) to your webhook endpoint. You can also read the charge with GET /v1/charges/{id}.

4. 4

   Step 4: Fulfill the order

   Deliver the product only after the charge reaches paid. Never trust the redirect alone.

A charge is one attempt to collect an amount from a buyer. It starts as pending and moves to paid, failed or expired; a paid charge can later become refunded or partially_refunded. See Creating charges.

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

The hosted payment page at https://krokopay.app/pay/{id}. It shows the amount, lets the buyer choose Pix or card, and shows the result of the payment. A Pix code is valid for a limited time (15 minutes in the demo; the production value is to be announced). See Checkout.

A reusable checkout address for a price. Share it in a message or a bio and every visit creates its own charge, with no code on your side. See payment links.

The buyer's record: name, email, and an optional phone and CPF/CNPJ (document). Attach customer_id to charges and subscriptions to keep the history together. See Customers.

A product is what you sell; a price is how much and how often (one time, or monthly or yearly for subscriptions). Payment links and subscriptions point at a price_id.

Recurring billing of a customer on a recurring price. Each period creates a charge; the subscription can be paused, resumed or canceled. See Subscriptions.

HTTPS notifications sent to your endpoint when something changes, such as charge.paid or subscription.renewed. Every delivery is signed in the KrokoPay-Signature header. See Webhooks.

Only the test environment exists today. Test keys start with kp_test_, nothing moves real money, and the dashboard simulates every outcome. Live keys and live mode are not available yet; when they are, the contract will say so here.

Every endpoint lives under https://api.krokopay.app/v1. Requests and responses are JSON over HTTPS, field names are snake_case, and every request is authenticated with your secret key as a Bearer token (see Authentication).

POST /v1/charges HTTP/1.1Host: api.krokopay.appAuthorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7bIdempotency-Key: order_1042Content-Type: application/json​{  "amount": 49700,  "currency": "BRL",  "description": "Curso Identidade Visual do Zero",  "customer_id": "cus_8Hq2LmZr4TxN1a",  "methods": [    "pix",    "card"  ]}

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

Every object has an id with a short prefix that tells you its type, and an object field with the type name.

Amounts are integers in the smallest currency unit: 49700 means R$497.00. The only currency in the proposal is BRL.

Times are ISO 8601 strings in UTC, such as 2026-11-03T14:23:41.000Z, in fields ending with _at. Fields that do not apply yet are null.

The current proposal is version 2026-11-01, shown as api_version on every webhook event. How versions will be pinned and upgraded is to be announced.

• Quickstart: from a test key to a paid test charge in five steps.
• Authentication: the Bearer header and which key to use.
• Errors: the error object and every code you can receive.