API REST · v1

API NataPay

Crie cobranças Pix, consulte pagamentos e receba webhooks assinados — direto do seu backend. Respostas em JSON, autenticação por API key.

URL base:

https://natapayments.com.br/api/v1

Autenticação

Todas as requisições exigem sua Secret Key no header Authorization. Gere a chave em Dashboard → Integração & API. A secret é exibida uma única vez — guarde com segurança e nunca a exponha no client.

Authorization: Bearer sk_live_sua_chave_secreta

Limites: 60 requisições por minuto por chave e 120 por minuto por IP. Ao estourar, a API responde 429 rate_limited.

Cobranças

POST/v1/charges

Cria uma cobrança para um produto do seu catálogo — em Pix, boleto ou cartão de crédito.

Parâmetros

product_id obrigatório — UUID de um produto seu.
method — pix (padrão), boleto ou card.
customer.name obrigatório
customer.document obrigatório — CPF (11 dígitos) ou CNPJ (14), com ou sem máscara. O banco exige para registrar o pagador em qualquer método.
customer.email — opcional, mas recomendado: sem ele o comprador não recebe o e-mail de confirmação e de entrega do produto.
installments — cartão, 1 a 12 (padrão 1).
card — cartão: token (recomendado) ou number, holder, exp_month, exp_year, cvv.

Order bumps e cupons são exclusivos do checkout hospedado (/checkout/:product_id).

curl -X POST https://natapayments.com.br/api/v1/charges \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "7de648d3-0007-47d5-8fae-04b188c9e2dc",
    "customer": { "name": "João Silva", "document": "12345678909" }
  }'

Resposta 201

{
  "id": "bca162fc-2419-42ac-a57f-2b548138038a",
  "status": "pending",
  "method": "pix",
  "amount_cents": 9700,
  "product": "Pack Criativos Premium",
  "pix": {
    "copy_paste": "00020126580014br.gov.bcb.pix...",
    "qr_base64": "data:image/png;base64,iVBORw0KG...",
    "expires_at": "2026-08-22T01:00:00.000Z"
  }
}

Boleto

curl -X POST https://natapayments.com.br/api/v1/charges \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "7de648d3-0007-47d5-8fae-04b188c9e2dc",
    "method": "boleto",
    "customer": { "name": "João Silva", "document": "12345678909" }
  }'

{
  "id": "3f1c...",
  "status": "pending",
  "method": "boleto",
  "amount_cents": 9700,
  "product": "Pack Criativos Premium",
  "boleto": {
    "line": "34191.79001 01043.510047 91020.150008 1 96610000009700",
    "url": "https://.../boleto",
    "due_date": "2026-09-08"
  }
}

Cartão de crédito

Cobrança síncrona: a resposta já traz status: "paid" (aprovada) ou 402 (recusada). Prefira enviar card.token — mandar o número do cartão cru coloca o seu servidor no escopo PCI-DSS.

curl -X POST https://natapayments.com.br/api/v1/charges \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "7de648d3-0007-47d5-8fae-04b188c9e2dc",
    "method": "card",
    "installments": 3,
    "customer": { "name": "João Silva", "document": "12345678909" },
    "card": {
      "number": "4111111111111111",
      "holder": "JOAO SILVA",
      "exp_month": "12",
      "exp_year": "2030",
      "cvv": "123"
    }
  }'

{
  "id": "9b2e...",
  "status": "paid",
  "method": "card",
  "amount_cents": 9700,
  "net_cents": 9394,
  "product": "Pack Criativos Premium",
  "customer": { "name": "João Silva", "email": null },
  "paid_at": "2026-09-05T12:31:08.000Z",
  "created_at": "2026-09-05T12:31:06.000Z"
}

Recusado → 402 { "error": "card_declined", "detail": "..." }. O cartão tem limite próprio de 10 requisições por minuto por chave.

GET/v1/charges/:id

Consulta o status e os detalhes de uma cobrança. Faça polling aqui ou receba o webhook charge.paid.

curl https://natapayments.com.br/api/v1/charges/bca162fc-2419-42ac-a57f-2b548138038a \
  -H "Authorization: Bearer sk_live_..."

{
  "id": "bca162fc-2419-42ac-a57f-2b548138038a",
  "status": "paid",
  "method": "pix",
  "amount_cents": 9700,
  "net_cents": 9394,
  "product": "Pack Criativos Premium",
  "customer": { "name": "João Silva", "email": null },
  "paid_at": "2026-08-22T00:47:10.000Z",
  "created_at": "2026-08-22T00:45:02.000Z"
}

GET/v1/charges

Lista suas cobranças, das mais recentes. Query: limit (1–100, padrão 20) e status (opcional: paid, pending…).

curl "https://natapayments.com.br/api/v1/charges?limit=20&status=paid" \
  -H "Authorization: Bearer sk_live_..."

{ "data": [ { "id": "...", "status": "paid", ... } ] }

Webhooks

Cadastre um endpoint em Integração. Quando uma cobrança é paga, a NataPay faz um POST no seu endpoint com o evento charge.paid, assinado com HMAC-SHA256 no header X-NataPay-Signature (até 3 tentativas).

Payload

{
  "id": "evt_9f2c...",
  "type": "charge.paid",
  "created": 1755830830,
  "data": {
    "id": "bca162fc-...",
    "amount_cents": 9700,
    "net_cents": 9394,
    "method": "pix",
    "product": "Pack Criativos Premium",
    "customer": { "name": "João Silva", "email": null }
  }
}

Validar a assinatura (Node.js)

Use o corpo cru (raw body) da requisição, exatamente como chegou. Se o seu framework já fez parse do JSON (ex.: express.json()), a assinatura não vai bater — guarde o raw body antes.

import crypto from "node:crypto";

const received = req.headers["x-natapay-signature"] ?? ""; // "sha256=..."
const expected =
  "sha256=" +
  crypto.createHmac("sha256", WEBHOOK_SECRET).update(rawBody).digest("hex");

// timingSafeEqual exige buffers do MESMO tamanho — compare antes.
const a = Buffer.from(received);
const b = Buffer.from(expected);
const valid = a.length === b.length && crypto.timingSafeEqual(a, b);

if (!valid) return res.status(401).end();
res.status(200).end(); // responda 2xx rápido: reenviamos até 3x

Erros

Erros retornam JSON { "error": "..." } com o status HTTP correspondente.

Status	error	Significado
401	missing_api_key / invalid_api_key	Chave ausente ou inválida.
404	product_not_found / not_found	Recurso não encontrado ou de outro seller.
400	invalid_body / invalid_params	Corpo ou parâmetros inválidos.
400	charge_failed	Falha ao gerar a cobrança.
402	card_declined	Cartão recusado pelo emissor.
429	rate_limited	Muitas requisições. Aguarde.
503	service_unavailable	Pagamentos não configurados.

Pronto para integrar?

Crie sua conta, gere uma API key em Integração e faça sua primeira cobrança em minutos.

Pegar minha API key