Documentação da API N7 Pay

Autenticação

Toda requisição deve incluir o header Authorization com sua chave de API:

Authorization: Bearer n7_sk_sand_SuaChaveAqui

Token JWT temporário

Troque sua API Key por um JWT de curta duração (útil para clientes públicos):

curl -X POST https://n7pay.com.br/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"api_key": "n7_sk_sand_SuaChaveAqui"}'

Ambiente Sandbox

O ambiente sandbox usa a infraestrutura de testes dos gateways. Nenhuma cobrança real é processada.

Erros

Erros retornam JSON com campo error (código) e message (descrição legível):

{
  "error": "unauthorized",
  "message": "API key inválida ou revogada."
}

Rate Limit

Limites aplicados por chave de API. Headers de resposta indicam o estado atual:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Reset: 1717852800

Links de Pagamento

Links são URLs que permitem cobranças sem integração de checkout customizado. Suportam PIX, boleto, cartão (BRL/USD). Podem ter URL personalizada com o slug da empresa: https://n7pay.com.br/c/sua-empresa/pay/:slug.

Parâmetros — POST /payment-links

curl -X POST https://n7pay.com.br/api/v1/payment-links \
  -H "Authorization: Bearer n7_sk_sand_SuaChaveAqui" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Plano Pro · Mensal",
    "amount": "99.90",
    "currency": "BRL",
    "methods": ["pix", "card_1x"],
    "fee_strategy": "absorb"
  }'

# Resposta 201
{
  "id": 42,
  "slug": "abc123def",
  "url": "https://n7pay.com.br/pay/abc123def",
  "branded_url": "https://n7pay.com.br/c/sua-empresa-a1b2c3/pay/abc123def",
  "title": "Plano Pro · Mensal",
  "amount": "99.90",
  "currency": "BRL",
  "status": "active",
  "methods": ["pix", "card_1x"],
  "created_at": "2026-06-08T12:00:00Z"
}

Transações

Transações são criadas automaticamente quando um pagador conclui o fluxo em um link de pagamento ou via API de cobrança direta.

Status de transação

Clientes

Clientes representam os pagadores da sua empresa. Ao criar um cliente, o N7 Pay sincroniza automaticamente com os gateways configurados (Asaas, Stripe), armazenando os IDs remotos para acelerar cobranças futuras e habilitar split de receita.

Parâmetros — POST /customers

# Criar cliente (PIX + cartão internacional)
curl -X POST https://n7pay.com.br/api/v1/customers \
  -H "Authorization: Bearer n7_sk_sand_SuaChaveAqui" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "João da Silva",
    "email": "joao@exemplo.com",
    "phone": "+5511999999999",
    "document_type": "cpf",
    "document": "123.456.789-00",
    "country": "BR",
    "address_line1": "Rua das Flores, 100",
    "city": "São Paulo",
    "state": "SP",
    "zip_code": "01310-100"
  }'

# Resposta 201
{
  "id": 7,
  "name": "João da Silva",
  "email": "joao@exemplo.com",
  "country": "BR",
  "gateway_customer_ids": {
    "asaas": "cus_000123abc",
    "stripe": "cus_Nxxx1234"
  },
  "created_at": "2026-06-08T15:00:00Z"
}

Webhooks — Saída (N7 → seu servidor)

Configure endpoints HTTPS no seu dashboard para receber notificações em tempo real. O N7 Pay assina cada payload com HMAC-SHA256.

Formato do payload

{
  "event": "payment_link.paid",
  "occurred_at": "2026-06-08T15:42:00Z",
  "data": {
    "transaction_id": 142,
    "payment_link_id": 42,
    "amount": "99.90",
    "currency": "BRL",
    "method": "pix",
    "gateway": "asaas",
    "status": "paid"
  }
}

A assinatura é enviada no header X-N7-Signature:

# Verificação em Elixir
def valid_signature?(raw_body, signature, secret) do
  expected = :crypto.mac(:hmac, :sha256, secret, raw_body)
             |> Base.encode16(case: :lower)
  Plug.Crypto.secure_compare(expected, signature)
end

# Verificação em Node.js
const crypto = require("crypto");
const expected = crypto.createHmac("sha256", secret)
  .update(rawBody).digest("hex");
const valid = crypto.timingSafeEqual(
  Buffer.from(expected), Buffer.from(signature)
);

Eventos disponíveis

Webhooks Incoming — Asaas → N7

O Asaas envia notificações para https://n7pay.com.br/webhooks/asaas. Configure este URL no painel do Asaas em Configurações → Integrações → Webhook.

Eventos tratados

Autenticação do webhook Asaas

Configure um token de webhook no campo Assis-Token dentro do Asaas. O N7 Pay valida o header asaas-access-token em cada requisição. O token é armazenado em company_gateway.config.webhook_token.

Webhooks Incoming — Stripe → N7

O Stripe envia notificações para https://n7pay.com.br/webhooks/stripe. Configure este URL no Stripe Dashboard → Developers → Webhooks.

Eventos tratados

Verificação de assinatura Stripe

O N7 Pay valida o header Stripe-Signature usando o webhook secret configurado em company_gateway.config.webhook_token. Nunca processe eventos sem validação de assinatura.

Smart Routing

O Smart Routing seleciona automaticamente o melhor gateway para cada transação com base em:

• Menor custo — taxa percentual + fixa combinada (peso 45%)
• Taxa de aprovação 24h — histórico recente de cada gateway (peso 35%)
• Latência p50 — tempo de resposta mediano (peso 15%)
• Failover automático — se um gateway falhar, tenta o próximo (peso 5%)

Critérios de roteamento por método

Split de Receita

Quando uma empresa usa o Asaas com split configurado, cada cobrança enviada via N7 Pay inclui automaticamente o parâmetro splits com o walletId da empresa. A N7 retém sua comissão e o restante vai direto para a carteira da empresa.

Asaas — configuração

No console N7, ao atribuir o gateway Asaas à empresa, preencha o campo Wallet ID com o ID da sub-carteira Asaas da empresa. O split será calculado automaticamente com base no fee plan configurado.

Stripe — configuração

Para Stripe, configure a conta Connect da empresa no campo Merchant ID (no formato acct_xxx). As cobranças usarão transfer_data[destination] para roteamento direto.

Suporte Internacional

O N7 Pay suporta clientes e cobranças globais. Cada gateway tem requisitos diferentes:

Exemplos cURL

Listar links

curl https://n7pay.com.br/api/v1/payment-links \
  -H "Authorization: Bearer n7_sk_sand_SuaChaveAqui"

Criar link USD (Stripe)

curl -X POST https://n7pay.com.br/api/v1/payment-links \
  -H "Authorization: Bearer n7_sk_sand_SuaChaveAqui" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "International Plan",
    "amount": "29.00",
    "currency": "USD",
    "methods": ["card_1x"]
  }'

Consultar transação

curl https://n7pay.com.br/api/v1/transactions/142 \
  -H "Authorization: Bearer n7_sk_sand_SuaChaveAqui"

Exemplos JavaScript / TypeScript

Criar link de pagamento

const res = await fetch("https://n7pay.com.br/api/v1/payment-links", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.N7_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Plano Mensal",
    amount: "99.90",
    currency: "BRL",
    methods: ["pix"],
  }),
});
const link = await res.json();
console.log(link.url); // https://n7pay.com.br/pay/abc123

Verificar assinatura de webhook

import crypto from "node:crypto";

function verifyWebhook(rawBody: Buffer, signature: string, secret: string): boolean {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected, "hex"),
    Buffer.from(signature, "hex")
  );
}