Documentação da API

Receba pagamentos Pix com QR Code e copia e cola direto na sua aplicação. A API NottiPay é REST, usa JSON e responde em português. Valores em reais (BRL).

Autenticação

Gere uma chave no painel em API & Webhooks. Ela é exibida uma única vez — guarde com segurança. Envie em todas as requisições no cabeçalho Authorization:

cabeçalho

Authorization: Bearer np_live_xxxxxxxxxxxxxxxx

URL base: https://nottipay.lovable.app

Endpoints

POST

/api/public/v1/charges

Cria uma cobrança Pix e retorna o QR Code (copia e cola) para o pagador.

curl — criar cobrança

curl -X POST https://nottipay.lovable.app/api/public/v1/charges \
  -H "Authorization: Bearer np_live_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 49.90,
    "description": "Pedido #1234",
    "external_id": "pedido-1234",
    "payer": {
      "name": "Maria Silva",
      "cpf": "12345678909",
      "email": "maria@email.com"
    }
  }'

resposta 201

{
  "id": "3f8a...c21",
  "status": "pending",
  "amount": 49.9,
  "paid_amount": null,
  "fee": null,
  "net_amount": null,
  "description": "Pedido #1234",
  "external_id": "pedido-1234",
  "pix_copy_paste": "00020126580014br.gov.bcb.pix...",
  "payer": { "name": "Maria Silva", "email": "maria@email.com" },
  "created_at": "2026-10-21T03:00:00.000Z",
  "paid_at": null
}

GET

/api/public/v1/charges/{id}

Consulta uma cobrança. O status é verificado em tempo real com a processadora Pix. Quando paga, status vira paid e os campos paid_amount, fee e net_amount são preenchidos.

curl — consultar cobrança

curl https://nottipay.lovable.app/api/public/v1/charges/3f8a...c21 \
  -H "Authorization: Bearer np_live_xxxxxxxxxxxxxxxx"

Node.js — exemplo completo

const res = await fetch("https://nottipay.lovable.app/api/public/v1/charges", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.NOTTIPAY_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 19.9,
    description: "Assinatura mensal",
    payer: { name: "João Souza", cpf: "98765432100" },
  }),
});
const charge = await res.json();
console.log(charge.pix_copy_paste); // mostre o QR ao cliente

Webhooks

Cadastre sua URL HTTPS no painel (API & Webhooks) e receba um POST assinado a cada evento:

charge.paid — cobrança confirmada
withdrawal.paid — saque concluído
withdrawal.rejected — saque recusado

Cada envio inclui os cabeçalhos X-NottiPay-Event e X-NottiPay-Signature (HMAC-SHA256 do corpo com o seu segredo de webhook). Valide sempre:

Node.js — validar assinatura

import crypto from "node:crypto";

app.post("/webhooks/nottipay", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto
    .createHmac("sha256", process.env.NOTTIPAY_WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");
  const sig = req.get("X-NottiPay-Signature");
  if (!sig || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return res.sendStatus(401);
  }
  const { event, data } = JSON.parse(req.body.toString());
  if (event === "charge.paid") console.log("Pago!", data.id, data.net_amount);
  res.sendStatus(200);
});

corpo do webhook

{
  "event": "charge.paid",
  "data": {
    "id": "3f8a...c21",
    "status": "paid",
    "amount": 49.9,
    "paid_amount": 49.9,
    "fee": 0.15,
    "net_amount": 49.75,
    "external_id": "pedido-1234",
    "paid_at": "2026-10-21T03:05:00.000Z"
  },
  "sent_at": "2026-10-21T03:05:01.000Z"
}

Regras e taxas

Pix recebido até R$ 200: R$ 0,15. Acima de R$ 200: 3% do valor pago, substituindo a taxa fixa. Desconto único na confirmação.
Taxa de R$ 1,00 por saque, descontada na conclusão.
Cobrança mínima de R$ 1,00 e máxima de R$ 100.000; saque mínimo de R$ 20,00, mais R$ 1,00 de taxa.
Status das cobranças: pending, paid, expired, failed, canceled, refunded.
Erros retornam { "error": "...", "message": "..." } com o HTTP status adequado (401, 404, 422...).