Documentação

PIX no seu app, em 1 request.

API limpa, SDK TypeScript, webhooks assinados e um MCP pro seu agente integrar sozinho. Comece no sandbox — zero dinheiro real.

Introdução

O Nimbuu Pay é um gateway PIX dev-first. Você cria uma cobrança, mostra o copia-e-cola (pix.qr_code) ou o QR (pix.qr_code_base64) pro cliente, e o pagamento confirma via webhook. Valores sempre em centavos (4990 = R$ 49,90).

Autenticação

Toda chamada usa o header Authorization: Bearer <API_KEY>. A chave sk_test_ é o sandbox (PIX simulado); sk_live_ é produção — mesma API, só troca a chave. Nunca exponha a chave no front-end; chame sempre do seu backend.

curl https://api-sandbox.nimbuupay.com/v1/charges \
  -H "Authorization: Bearer sk_test_..."

Quickstart

Crie sua primeira cobrança PIX:

curl -X POST https://api-sandbox.nimbuupay.com/v1/charges \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4990,
    "description": "Pedido #123",
    "customer": { "name": "Ana", "document": "12345678909" }
  }'

Cobranças

POST /v1/charges — amount (centavos, mín. 100), customer.name e customer.document são obrigatórios. Header opcional Idempotency-Key evita duplicidade.

{
  "id": "ch_test_...",
  "object": "charge",
  "status": "pending",
  "amount": 4990,
  "currency": "BRL",
  "pix": {
    "qr_code": "00020126...6304XXXX",
    "qr_code_base64": "data:image/png;base64,...",
    "expires_at": "2026-..."
  },
  "paid_at": null
}

GET /v1/charges/{id} consulta · GET /v1/charges lista. Status: pending, paid, expired, failed, refunded. No sandbox, POST /v1/charges/{id}/pay simula o pagamento e dispara o webhook.

Webhooks

Registre um endpoint pra ser notificado (ex.: charge.paid). O secret só aparece na criação — guarde-o.

POST /v1/webhooks
{ "url": "https://seuapp.com/webhooks/nimbuu", "events": ["charge.paid"] }

A entrega vem com header Nimbuu-Signature: t=<ts>,v1=<hmac>. Valide o HMAC SHA256(secret, "<t>.<rawBody>") em tempo constante (anti-replay pelo t):

import { verifyWebhook } from "nimbuu-pay";

const ok = verifyWebhook(rawBody, req.headers["nimbuu-signature"], process.env.NIMBUU_WEBHOOK_SECRET!);
if (!ok) return res.status(400).end();

SDK TypeScript

npm i nimbuu-pay

import { NimbuuPay } from "nimbuu-pay";
const nimbuu = new NimbuuPay(process.env.NIMBUU_API_KEY!);

const charge = await nimbuu.charges.create({
  amount: 4990,
  customer: { name: "Ana", document: "12345678909" },
});
console.log(charge.pix.qr_code); // copia-e-cola

MCP — seu agente integra sozinho

O diferencial AI-native: adicione o Nimbuu Pay ao Cursor / Claude e peça “adicione PIX no meu checkout”. O agente cria cobranças e configura webhooks por você.

{
  "mcpServers": {
    "nimbuu-pay": {
      "command": "npx",
      "args": ["-y", "nimbuu-pay-mcp"],
      "env": { "NIMBUU_API_KEY": "sk_test_..." }
    }
  }
}

Tools: nimbuu_create_charge, nimbuu_get_charge, nimbuu_list_charges, nimbuu_simulate_payment, nimbuu_quickstart.

Erros

Sempre JSON: { "error": { "type", "code", "message" } }

• · 401 no_api_key / invalid_api_key — autenticação
• · 400 invalid_request — payload inválido (ex.: amount < 100)
• · 404 charge_not_found / webhook_not_found