Gere Pix pelo seu sistema

Uma chamada cria o Pix. Um aviso chega quando ele é pago. É só isso.

Comece em 3 passos

  1. 1. Pegue sua chave

    No painel, em API → Gerar chaves.

  2. 2. Gere o Pix

    POST /charges com o valor.

  3. 3. Receba o aviso

    Cadastre um webhook e espere charge.paid.

curl -X POST https://kurumapay.site/api/v1/charges \
  -H "Authorization: Bearer SUA_CHAVE_PRIVADA" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 9700 }'

Autenticação

Envie sua chave privada em todas as chamadas. Ela começa com sk_live_ e só deve ficar no seu servidor.

Authorization: Bearer sk_live_…

Endereço base: https://kurumapay.site/api/v1 · Valores sempre em centavos (9700 = R$ 97,00).

Gerar um Pix

POST/charges

amountnúmeroObrigatório. Valor em centavos.
descriptiontextoOpcional. Aparece no seu painel.
external_reftextoOpcional. O número do seu pedido; volta no webhook.
payerobjetoOpcional. { name, document } de quem vai pagar.
const res = await fetch("https://kurumapay.site/api/v1/charges", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.KURUMA_KEY,
    "Content-Type": "application/json",
    "Idempotency-Key": "pedido-123", // opcional: repetir não cria outro Pix
  },
  body: JSON.stringify({ amount: 9700, description: "Pedido 123" }),
});
const pix = await res.json();
// pix.pix_code → copia e cola    pix.qr_code → imagem do QR pronta

A resposta traz tudo para mostrar ao cliente:

{
  "id": "ch_3kF9aQ…",
  "status": "pending",
  "amount": 9700,
  "pix_code": "00020101021226…6304A1B2",
  "qr_code": "data:image/png;base64,iVBORw0…",
  "expires_at": "2026-11-17T15:30:00.000Z"
}
pix_codetextoO copia e cola.
qr_codeimagemO QR já pronto. Use direto em <img src="…">.
statustextopending → paid, expired ou refunded.
expires_atdataO Pix vale 30 minutos.

Vai tentar de novo após uma falha de rede? Envie o cabeçalho Idempotency-Key com o número do pedido: a mesma chave devolve o mesmo Pix.

Consultar

GET/charges/:id

Devolve a cobrança com o status atual. Quando paga, inclui fee (sua taxa), net (o que entrou no saldo) e payer.

GET/charges?status=paid&limit=20

As mais recentes primeiro, em { data: [...] }. status e limit (até 100) são opcionais.

Saldo

GET/balance

{ "available": 1848065, "held": 24990 }

available é o que você pode sacar. held está retido (saques pedidos ou infrações).

Webhooks

Cadastre a URL do seu sistema no painel, em API → Webhooks. Mandamos um POST a cada evento. Responda 200 em até 10 segundos.

charge.paidO Pix foi pago. É o que importa na maioria dos casos.
charge.createdUm Pix foi gerado.
charge.expiredPassou do prazo sem pagamento.
charge.refundedO Pix foi devolvido ao pagador.
payout.paidSeu saque foi pago.
payout.rejectedSeu saque foi recusado; o valor voltou ao saldo.
{
  "id": "evt_8sJ2…",
  "type": "charge.paid",
  "created_at": "2026-11-17T15:02:11.000Z",
  "data": {
    "id": "ch_3kF9aQ…",
    "status": "paid",
    "amount": 9700,
    "fee": 585,
    "net": 9115,
    "external_ref": "pedido-123",
    "payer": { "name": "Maria Gonçalves", "document": "***.482.917-**" }
  }
}

Confira a assinatura. Cada aviso traz o cabeçalho X-Kuruma-Signature. Compare com o segredo do seu webhook (copie no painel):

import crypto from "node:crypto";

// body = o texto cru que chegou (não o JSON já convertido)
function assinaturaValida(body, header, segredo) {
  const [t, v1] = header.split(",").map((p) => p.split("=")[1]);
  const esperado = crypto.createHmac("sha256", segredo).update(t + "." + body).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(esperado));
}

// header = req.headers["x-kuruma-signature"]

Se o seu sistema não responder 200, tentamos de novo em 1 min, 5 min, 30 min, 2 h e 12 h. O mesmo aviso pode chegar mais de uma vez: use o id do evento para não processar duas vezes.

Erros

Todo erro vem no mesmo formato: { "error": { "code": "…", "message": "…" } }

400invalid_bodyFaltou o amount, ou não é um inteiro em centavos.
401unauthorizedChave ausente, errada ou revogada.
403merchant_inactiveSua conta ainda não foi liberada.
404not_foundCobrança não existe (ou não é sua).
429rate_limitedMais de 120 chamadas por minuto.
502gateway_errorNão deu para gerar o Pix agora. Tente de novo.