Introdução

A KrokoPay é uma plataforma de pagamentos com checkout próprio. Você cria uma cobrança no seu servidor, envia o comprador ao checkout hospedado e fica sabendo do resultado pela API ou por um webhook. O comprador paga com Pix ou cartão numa página hospedada pela KrokoPay, então os dados do cartão nunca passam pelos seus servidores.

Esta documentação descreve uma proposta provisória de contrato. Os endpoints ainda não estão em operação e nenhum SDK foi publicado: todos os exemplos são cURL ou fetch puros, e os nomes dos campos ainda podem mudar antes do lançamento.

1. 1

   Passo 1: Crie uma cobrança

   Seu servidor chama POST /v1/charges com o valor em centavos e os métodos aceitos. A resposta traz um checkout_url.

2. 2

   Passo 2: Envie o comprador ao checkout

   Redirecione o comprador para o checkout_url. Ele escolhe Pix ou cartão e paga na página hospedada.

3. 3

   Passo 3: Receba o resultado

   A KrokoPay envia charge.paid (ou charge.failed, charge.expired) para o seu endpoint de webhook. Você também pode consultar a cobrança com GET /v1/charges/{id}.

4. 4

   Passo 4: Entregue o pedido

   Libere o produto só depois que a cobrança chegar a paid. Nunca confie apenas no redirecionamento.

Uma cobrança é uma tentativa de receber um valor de um comprador. Ela começa como pending e passa para paid, failed ou expired; uma cobrança paga pode depois virar refunded ou partially_refunded. Veja Criando cobranças.

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

A página de pagamento hospedada em https://krokopay.app/pay/{id}. Ela mostra o valor, deixa o comprador escolher Pix ou cartão e exibe o resultado do pagamento. Um código Pix vale por tempo limitado (15 minutos na demonstração; o valor de produção ainda será anunciado). Veja Checkout.

Um endereço de checkout reutilizável para um preço. Compartilhe numa mensagem ou na bio, e cada visita cria a própria cobrança, sem nenhum código do seu lado. Veja links de pagamento.

O cadastro do comprador: nome, e-mail e, opcionalmente, telefone e CPF/CNPJ (document). Informe o customer_id nas cobranças e assinaturas para manter o histórico junto. Veja Clientes.

Um produto é o que você vende; um preço é quanto e com que frequência (pagamento único, ou mensal ou anual para assinaturas). Links de pagamento e assinaturas apontam para um price_id.

A cobrança recorrente de um cliente num preço recorrente. Cada período gera uma cobrança; a assinatura pode ser pausada, retomada ou cancelada. Veja Assinaturas.

Notificações HTTPS enviadas ao seu endpoint quando algo muda, como charge.paid ou subscription.renewed. Toda entrega é assinada no cabeçalho KrokoPay-Signature. Veja Webhooks.

Hoje existe apenas o ambiente de teste. As chaves de teste começam com kp_test_, nenhum dinheiro de verdade circula e o painel simula todos os resultados. Chaves de produção e o modo de produção ainda não estão disponíveis; quando estiverem, o contrato vai dizer aqui.

Todos os endpoints ficam em https://api.krokopay.app/v1. Requisições e respostas são JSON sobre HTTPS, os nomes dos campos são snake_case e toda requisição é autenticada com a sua chave secreta como token Bearer (veja Autenticação).

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"

Todo objeto tem um id com um prefixo curto que indica o tipo, e um campo object com o nome do tipo.

Os valores são inteiros na menor unidade da moeda: 49700 significa R$ 497,00. A única moeda da proposta é BRL.

Datas e horas são strings ISO 8601 em UTC, como 2026-11-03T14:23:41.000Z, em campos terminados em _at. Campos que ainda não se aplicam vêm como null.

A proposta atual é a versão 2026-11-01, informada como api_version em todo evento de webhook. A forma de fixar e atualizar versões ainda será anunciada.

• Guia rápido: de uma chave de teste a uma cobrança de teste paga em cinco passos.
• Autenticação: o cabeçalho Bearer e qual chave usar.
• Erros: o objeto de erro e todos os códigos que você pode receber.