# Nimbuu Pay

> Gateway de pagamento PIX dev-first, feito pra quem constrói com IA. Adicione PIX ao seu app em minutos — uma API limpa, SDK TypeScript, webhooks assinados e um MCP server pra que seu agente de IA integre sozinho. Comece em **sandbox** (PIX simulado, zero dinheiro real); quando estiver pronto, troque a chave `sk_test_` por `sk_live_` e o código não muda.

## Conceitos
- **Charge (cobrança):** uma cobrança PIX. Você cria, mostra o `pix.qr_code` (copia-e-cola) ou o `pix.qr_code_base64` (QR) pro cliente, e o pagamento confirma via webhook.
- **Valores em centavos:** `amount: 4990` = R$ 49,90.
- **Modos:** `sk_test_...` (sandbox, simulado) e `sk_live_...` (produção, dinheiro real). Mesma API.
- **Base URL:** `http://localhost:4242` (local). Produção: o domínio da sua instância.
- **Auth:** header `Authorization: Bearer <API_KEY>`. NUNCA exponha a chave no front-end — chame sempre do seu backend.

## Criar cobrança PIX
`POST /v1/charges`

Request:
```json
{
  "amount": 4990,
  "description": "Pedido #123",
  "customer": { "name": "Cliente", "document": "12345678909", "email": "cliente@email.com" },
  "expiresIn": 3600,
  "metadata": { "pedido_id": "123" }
}
```
- `amount` (int, centavos, mín. 100) e `customer.name` + `customer.document` (CPF/CNPJ) são obrigatórios.
- Header opcional `Idempotency-Key: <string>` evita cobrança duplicada (mesma key → mesma cobrança).

Response (201):
```json
{
  "id": "ch_test_...",
  "object": "charge",
  "status": "pending",
  "amount": 4990,
  "currency": "BRL",
  "customer": { "name": "Cliente", "document": "12345678909" },
  "pix": {
    "qr_code": "00020126...6304XXXX",
    "qr_code_base64": "data:image/png;base64,...",
    "expires_at": "2026-..."
  },
  "paid_at": null,
  "created_at": "2026-..."
}
```
`pix.qr_code` é o copia-e-cola (BR Code EMV). `pix.qr_code_base64` é a imagem do QR pronta pra `<img src>`.

## Consultar / listar
- `GET /v1/charges/{id}` → a cobrança. Campo `status` vira `paid` quando pago.
- `GET /v1/charges` → `{ "object": "list", "data": [ ...charges ] }`.

Status possíveis: `pending`, `paid`, `expired`, `failed`, `refunded`.

## Sandbox: simular pagamento
`POST /v1/charges/{id}/pay` → marca a cobrança como `paid` e dispara o webhook `charge.paid`. (Só existe em modo test; em produção isso vem do PSP.)

## Webhooks
Registre um endpoint pra ser notificado quando algo acontece (ex.: pagamento).

`POST /v1/webhooks`
```json
{ "url": "https://seuapp.com/webhooks/nimbuu", "events": ["charge.paid"] }
```
Response inclui `secret` (`whsec_...`) — **guarde-o**, só aparece na criação.
- `GET /v1/webhooks` lista. `DELETE /v1/webhooks/{id}` remove.
- Eventos: `charge.paid` (mais; use `["*"]` pra todos).

Quando o evento dispara, o Nimbuu faz `POST` no seu endpoint com:
- Header `Nimbuu-Signature: t=<unix_ts>,v1=<hmac_sha256_hex>`
- Body JSON: `{ "id": "evt_...", "type": "charge.paid", "created": <ts>, "data": { "object": { ...charge } } }`

### Validar a assinatura (importante)
O HMAC é `HMAC_SHA256(secret, "<t>.<rawBody>")`. Compare em tempo constante e rejeite se o `t` for muito antigo (anti-replay). Com o SDK:
```ts
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
```bash
npm i nimbuu-pay
```
```ts
import { NimbuuPay } from "nimbuu-pay";
const nimbuu = new NimbuuPay(process.env.NIMBUU_API_KEY!);

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

const paid = await nimbuu.charges.retrieve(charge.id); // checa status
```
Métodos: `charges.create`, `charges.retrieve`, `charges.list`, `webhooks.create/list/del`, e o helper `verifyWebhook`.

## MCP (pro seu agente de IA integrar sozinho)
O Nimbuu Pay tem um MCP server. Configure no Cursor/Claude Desktop:
```json
{
  "mcpServers": {
    "nimbuu-pay": {
      "command": "node",
      "args": ["/caminho/nimbuu-pay/mcp/dist/index.js"],
      "env": { "NIMBUU_API_KEY": "sk_test_..." }
    }
  }
}
```
Tools: `nimbuu_create_charge`, `nimbuu_get_charge`, `nimbuu_list_charges`, `nimbuu_simulate_payment`, `nimbuu_quickstart`. Peça ao agente: "adicione PIX com Nimbuu Pay no meu checkout".

## Erros
Sempre JSON: `{ "error": { "type": "...", "code": "...", "message": "..." } }`.
- 401 `no_api_key` / `invalid_api_key` — auth.
- 400 `invalid_request` — payload inválido (ex.: amount < 100).
- 404 `charge_not_found` / `webhook_not_found`.

## Boas práticas
- `amount` SEMPRE em centavos.
- Mande `Idempotency-Key` em criações pra evitar duplicidade.
- Confirme pagamento por **webhook**, não por polling.
- Valide a assinatura de todo webhook recebido.
- Nunca exponha a API key no cliente; toda chamada parte do seu backend.