Pagamentos

Criando cobranças

Uma cobrança é um pedido de pagamento feito a um comprador. Crie no seu servidor, envie o comprador para o checkout_url e acompanhe o status até ela ser paga, recusada ou expirar.

Nesta página

Todo pagamento na KrokoPay é uma cobrança (charge): um valor em BRL, uma descrição, os meios que o comprador pode usar e, se você quiser, o cliente a quem ela pertence. Você cria a cobrança com a sua chave secreta, a KrokoPay hospeda a página de pagamento e a cobrança passa por poucos status, que você consulta pela API ou recebe por webhooks.

Informação: Contrato provisório

Esta página descreve uma proposta de contrato. Endpoints, campos e comportamentos ainda podem mudar, e não existe SDK publicado: os exemplos usam cURL e fetch puro. Use apenas chaves de teste (kp_test_sk_…).

O objeto charge

Uma cobrança guarda o valor, o que já aconteceu com ela e o link do checkout hospedado. Os valores são inteiros em centavos: 49700 significa R$ 497,00.

Atributos

idstring: Identificador único, com o prefixo chg_.
objectstring: Sempre charge.
amountinteger: Valor a cobrar, em centavos.
currencystring: Código de moeda de três letras. Por enquanto, só BRL.
statusstring: Um entre pending, paid, failed, expired, refunded e partially_refunded. Veja Status.
methodstring | null: pix ou card depois que o comprador escolhe; null enquanto uma cobrança pendente ainda não tem meio definido.
cardobject | null: Só em pagamentos com cartão: brand (visa, mastercard, elo, amex) e last4. O número completo do cartão nunca é devolvido.
descriptionstring: Aparece para o comprador no checkout e no comprovante.
customer_idstring | null: O cliente a quem a cobrança pertence.
product_idstring | null: Produto do catálogo, quando a cobrança vem de um preço ou link de pagamento.
price_idstring | null: Preço do catálogo, quando a cobrança vem de um preço ou link de pagamento.
link_idstring | null: O link de pagamento que gerou a cobrança, se houver.
subscription_idstring | null: A assinatura que esta cobrança fatura, se houver.
feeinteger | null: Tarifa de processamento em centavos. As condições comerciais ainda serão anunciadas, então os exemplos deste site mostram null. No painel de demonstração (Desenvolvedores → Logs) o campo traz valores de demonstração.
netinteger | null: amount − fee − refunded_amount. Fica null nestes exemplos enquanto as tarifas não forem anunciadas.
refunded_amountinteger: Total já reembolsado, em centavos.
failure_codestring | null: Motivo da falha de uma tentativa com cartão: card_declined, insufficient_funds, expired_card, incorrect_cvc ou processing_error.
created_atstring: Data e hora em ISO 8601.
paid_atstring | null: Quando o pagamento foi confirmado.
expires_atstring | null: No Pix: o momento em que a cobrança não paga expira.
available_atstring | null: Quando o valor líquido passa do saldo pendente para o saldo disponível. Os prazos de liberação ainda serão anunciados, então os exemplos mostram null.
checkout_urlstring: O checkout hospedado desta cobrança. Veja Checkout.

Uma cobrança Pix pagaJSON

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

Criar uma cobrança

POST/v1/charges

Crie a cobrança no seu servidor quando o comprador estiver pronto para pagar, por exemplo ao confirmar um pedido. A resposta é uma cobrança pending com o respectivo checkout_url.

Parâmetros do corpo

amountintegerObrigatório: Inteiro positivo em centavos. 1000 é R$ 10,00.
currencystringObrigatório: BRL.
descriptionstringObrigatório: O que o comprador está pagando. Prefira algo curto e fácil de reconhecer: aparece no checkout e no comprovante.
customer_idstringOpcional: Vincula um cliente existente (cus_…). Se não for enviado, o checkout coleta os dados do comprador e encontra ou cria o cliente pelo e-mail.
methodsstring[]Opcional: Meios oferecidos no checkout: pix, card ou os dois. O comprador escolhe um.

Criar uma cobrança

curl -X POST https://api.krokopay.app/v1/charges \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -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"    ]  }'

Atenção: Envie sempre um Idempotency-Key

Um timeout não diz se a cobrança foi criada ou não. Envie o cabeçalho Idempotency-Key com um valor ligado ao seu pedido: assim, uma nova tentativa devolve a mesma cobrança em vez de criar outra. Veja Idempotência.

A proposta atual não tem campo metadata. Mantenha a relação entre pedido e cobrança do seu lado, guardando o id devolvido junto com o pedido. Quando o comprador escolhe Pix, a cobrança recebe um expires_at; no ambiente de teste, ele fica 15 minutos depois da geração do código Pix, e o prazo em produção ainda será definido.

Envie o comprador para o checkout

Devolva o checkout_url para o navegador e redirecione. A chave secreta fica no seu servidor; o navegador só recebe a URL.

Criar no servidor, redirecionar no navegadorTypeScript

// A fetch-style route handler on your server (Request in, Response out).// The secret key never reaches the browser.export async function POST(request: Request): Promise<Response> {  const order = (await request.json()) as { id: string; amount: number; customerId: string };  const response = await fetch("https://api.krokopay.app/v1/charges", {    method: "POST",    headers: {      Authorization: `Bearer ${process.env.KROKOPAY_SECRET_KEY}`, // kp_test_sk_…      "Idempotency-Key": `order_${order.id}`,      "Content-Type": "application/json",    },    body: JSON.stringify({      amount: order.amount, // centavos      currency: "BRL",      description: `Order ${order.id}`,      customer_id: order.customerId,      methods: ["pix", "card"],    }),  });  if (!response.ok) return new Response("Could not create the charge", { status: 502 });  const charge = (await response.json()) as { id: string; checkout_url: string };  // Store charge.id with the order, then hand the URL to the browser.  return Response.json({ checkout_url: charge.checkout_url });}

Consultar uma cobrança

GET/v1/charges/{id}

Busca o estado atual de uma cobrança pelo id. Use para confirmar um status depois de um webhook ou quando o comprador volta ao seu site e você precisa mostrar a página certa.

Consultar uma cobrança

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

Um id desconhecido responde 404. Uma chave ausente ou inválida responde 401. Os dois casos estão em Erros.

Listar cobranças

GET/v1/charges

Devolve as suas cobranças, da mais recente para a mais antiga, dentro de um objeto de lista.

Parâmetros de consulta

limitintegerOpcional: Quantas cobranças devolver. O máximo ainda será definido.

Listar as últimas cobranças

curl https://api.krokopay.app/v1/charges?limit=20 \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b"

Informação: Filtros e paginação

Filtros por status, cliente ou data e a paginação por cursor fazem parte da proposta e ainda serão definidos. Até lá, use webhooks para manter seus registros atualizados em vez de consultar a lista repetidamente.

Status e transições

Toda cobrança começa como pending e termina em um único resultado. Só uma cobrança paga pode ser reembolsada depois.

De	Para	Quando	Evento
—	`pending`	A cobrança é criada.	`charge.created`
`pending`	`paid`	O comprador paga com Pix ou o cartão é aprovado.	`charge.paid`
`pending`	`failed`	Uma tentativa com cartão é recusada. O `failure_code` diz o motivo.	`charge.failed`
`pending`	`expired`	Uma cobrança Pix não é paga antes do `expires_at`.	`charge.expired`
`paid`	`partially_refunded`	Parte do valor é reembolsada.	`charge.refunded`
`paid` / `partially_refunded`	`refunded`	Os reembolsos chegam ao valor total.	`charge.refunded`

Atenção: Cobranças recusadas ou expiradas ficam encerradas

Uma cobrança que falhou ou expirou não aceita nova tentativa. Para o comprador tentar de novo, crie outra cobrança (com uma nova chave de idempotência) ou mande-o de volta ao link de pagamento de origem.

Uma cobrança com cartão recusadoJSON

{  "id": "chg_7Lc3PvN8yHd2Ws",  "object": "charge",  "amount": 49700,  "currency": "BRL",  "status": "failed",  "method": "card",  "card": {    "brand": "visa",    "last4": "0002"  },  "description": "Curso Identidade Visual do Zero",  "customer_id": "cus_8Hq2LmZr4TxN1a",  "product_id": "prod_3Vb7QpK9sWd2Ee",  "price_id": "price_5Kd1NcR8vYq3Hm",  "link_id": null,  "subscription_id": null,  "fee": null,  "net": null,  "refunded_amount": 0,  "failure_code": "card_declined",  "created_at": "2026-11-03T16:02:19.000Z",  "paid_at": null,  "expires_at": null,  "available_at": null,  "checkout_url": "https://krokopay.app/pay/chg_7Lc3PvN8yHd2Ws"}

Para reproduzir cada resultado sem dinheiro de verdade, use os cartões de teste listados em Ambiente de teste.

Reembolsos

POST/v1/charges/{id}/refunds

Reembolsa total ou parcialmente uma cobrança paga. Você pode reembolsar várias vezes, até o total reembolsado chegar ao valor da cobrança. A resposta é a cobrança atualizada.

Parâmetros do corpo

amountintegerObrigatório: Centavos a reembolsar. Positivo e no máximo amount − refunded_amount.

Reembolsar R$ 99,00 de uma cobrança

curl -X POST https://api.krokopay.app/v1/charges/chg_4Fp9KzW1xQm7Rt/refunds \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Idempotency-Key: refund_1042" \  -H "Content-Type: application/json" \  -d '{    "amount": 9900  }'

Reembolsar o valor total

curl -X POST https://api.krokopay.app/v1/charges/chg_4Fp9KzW1xQm7Rt/refunds \  -H "Authorization: Bearer kp_test_sk_4f9a2c7e1b8d4a6f9c3e5d7b" \  -H "Idempotency-Key: refund_1042_full" \  -H "Content-Type: application/json" \  -d '{    "amount": 49700  }'

Só cobranças paid e partially_refunded podem ser reembolsadas.
Cada reembolso reduz o net e emite charge.refunded. Os reembolsos saem do seu saldo disponível; se ele não for suficiente, o reembolso é recusado.
Use um Idempotency-Key diferente para cada operação de reembolso, para que uma requisição repetida não reembolse duas vezes.

Próximos passos

Checkout: o que o comprador vê no checkout_url e como funcionam os links de pagamento.
Webhooks: receba charge.paid em vez de ficar consultando.
Clientes: vincule as cobranças a quem paga.
Erros: códigos de status e como tratá-los.