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

Cobranças

POST/v1/charges

Cria uma cobrança Pix para um produto do seu catálogo.

Parâmetros

product_id obrigatório — UUID de um produto seu.
customer.name obrigatório
customer.document — CPF do comprador (recomendado).
customer.email — opcional.

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"
  }
}

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)

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");

const valid =
  received &&
  crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

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.
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