Gere Pix pelo seu sistema
Uma chamada cria o Pix. Um aviso chega quando ele é pago. É só isso.
Comece em 3 passos
1. Pegue sua chave
No painel, em API → Gerar chaves.
2. Gere o Pix
POST /charges com o valor.
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
| amount | número | Obrigatório. Valor em centavos. |
| description | texto | Opcional. Aparece no seu painel. |
| external_ref | texto | Opcional. O número do seu pedido; volta no webhook. |
| payer | objeto | Opcional. { 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 prontaA 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_code | texto | O copia e cola. |
| qr_code | imagem | O QR já pronto. Use direto em <img src="…">. |
| status | texto | pending → paid, expired ou refunded. |
| expires_at | data | O 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.paid | O Pix foi pago. É o que importa na maioria dos casos. | |
| charge.created | Um Pix foi gerado. | |
| charge.expired | Passou do prazo sem pagamento. | |
| charge.refunded | O Pix foi devolvido ao pagador. | |
| payout.paid | Seu saque foi pago. | |
| payout.rejected | Seu 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": "…" } }
| 400 | invalid_body | Faltou o amount, ou não é um inteiro em centavos. |
| 401 | unauthorized | Chave ausente, errada ou revogada. |
| 403 | merchant_inactive | Sua conta ainda não foi liberada. |
| 404 | not_found | Cobrança não existe (ou não é sua). |
| 429 | rate_limited | Mais de 120 chamadas por minuto. |
| 502 | gateway_error | Não deu para gerar o Pix agora. Tente de novo. |
Pronto para testar?