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/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/c/sua-empresa/pay/:slug.

Parâmetros — POST /payment-links

curl -X POST https://n7pay.com/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
{
  "data": {
    "id": "9f1c2d3e-4b5a-6789-abcd-ef0123456789",
    "slug": "abc123def",
    "pay_url": "https://n7pay.com/pay/abc123def",
    "title": "Plano Pro · Mensal",
    "description": null,
    "amount": "99.90",
    "currency": "BRL",
    "status": "active",
    "methods": ["pix", "card_1x"],
    "fee_strategy": "absorb",
    "settlement_type": "d1",
    "max_installments": 1,
    "expires_at": null,
    "environment": "sandbox",
    "inserted_at": "2026-06-08T12:00:00"
  }
}

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

Cobranças Diretas — PIX e Cartão inline

Use cobranças diretas quando você quer cobrar dentro da sua própria UI, sem redirecionar o pagador para o checkout hospedado. O mesmo endpoint atende PIX e cartão — muda apenas o method.

Métodos aceitos e parcelamento

O número de parcelas está codificado no nome do método. Não existe card_12x — a faixa é que define o teto:

Parâmetros — POST /charges

curl -X POST https://n7pay.com/api/v1/charges \
  -H "Authorization: Bearer n7_sk_sand_SuaChaveAqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "49.90",
    "method": "pix",
    "description": "Pedido #1042",
    "external_reference": "order_1042",
    "customer": {
      "name": "João da Silva",
      "email": "joao@exemplo.com",
      "document": "123.456.789-00"
    }
  }'

# Resposta 201
{
  "data": {
    "id": 87,
    "status": "pending",
    "amount": "49.90",
    "currency": "BRL",
    "method": "pix",
    "external_id": "pay_8fHtX3kZq",
    "pix_qr_code": "00020126580014br.gov.bcb.pix0136...",
    "pix_qr_image": "data:image/png;base64,iVBORw0KGgo...",
    "expires_at": "2026-06-08T16:30:00",
    "inserted_at": "2026-06-08T16:00:00Z"
  }
}

Campos da resposta

Consultando o status da cobrança

Use o id retornado na criação para consultar o status em qualquer momento. A resposta de GET /transactions/:id inclui os mesmos campos de QR enquanto o PIX estiver pendente.

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

Cartão — Tokenização

Cobrança com cartão nunca recebe o número do cartão: ele é trocado antes por um card_token em POST /tokens. Você escolhe onde essa troca acontece, e a escolha tem consequência de compliance.

Dois caminhos

Caminho A — do navegador (recomendado)

1. Seu servidor cria (ou busca) o cliente em POST /customers e devolve o customer_id para a sua página.
2. O navegador do pagador chama POST /tokens com a chave publicável e os dados do cartão, e recebe card_token.
3. Sua página envia apenas o card_token ao seu servidor.
4. Seu servidor chama POST /charges com a chave secreta, o card_token, o method e as installments.

A chave publicável é gerada no dashboard em Chaves API → Tipo → Publicável. Ela pode ficar visível no código da sua página: só tokeniza cartão, não cria cobrança nem lê dados. O endpoint responde com CORS, então o fetch cross-origin funciona.

Caminho B — do seu servidor

Se o formulário de cartão já é processado no seu backend, chame POST /tokens de lá com a mesma chave secreta que você usa em /charges — não é preciso criar chave nem variável nova. O corpo é idêntico ao do caminho A.

Caminho C — cartão inline, sem tokenizar

A tokenização é um recurso liberado à parte pelo gateway. Enquanto ela não estiver habilitada na sua conta, envie o cartão direto no POST /charges, no objeto card, e omita o card_token:

curl -X POST https://n7pay.com/api/v1/charges \
  -H "Authorization: Bearer n7_sk_live_SuaChaveAqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "297.00",
    "method": "card_7_12x",
    "installments": 12,
    "ip": "189.10.20.30",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "document": "982.671.040-70",
      "phone": "61992746281",
      "postal_code": "71735103",
      "address_number": "17"
    },
    "card": {
      "holder_name": "MARIA S SOUZA",
      "number": "5162306219378829",
      "exp_month": "05",
      "exp_year": "2031",
      "cvv": "318"
    }
  }'

Os dados do portador saem do objeto customer; se o titular do cartão for outra pessoa, mande um objeto holder separado. Campos faltando voltam como 422 listando exatamente quais, antes de qualquer chamada ao gateway.

O efeito em compliance é o mesmo do caminho B — o cartão passa pelo seu servidor.

Parâmetros — POST /tokens

// Caminho A — no navegador do pagador, com a chave publicável.
// No caminho B, a mesma chamada sai do seu servidor com a chave n7_sk_.
const res = await fetch("https://n7pay.com/api/v1/tokens", {
  method: "POST",
  headers: {
    "Authorization": "Bearer n7_pk_sand_SuaChavePublicavel",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    customer_id: "44dcf7a7-ebc3-4ad7-b122-01f404cda545",
    card: {
      holder_name: "MARIA S SOUZA",
      number: "5162306219378829",
      exp_month: "05",
      exp_year: "2031",
      cvv: "318"
    },
    holder: {
      document: "982.671.040-70",
      postal_code: "71735103",
      address_number: "17",
      phone: "61992746281"
    }
  })
});

// Resposta 201
{
  "data": {
    "card_token": "8a1b2c3d-...",
    "brand": "MASTERCARD",
    "last4": "8829",
    "customer_id": "44dcf7a7-ebc3-4ad7-b122-01f404cda545"
  }
}

Cobrando o cartão tokenizado

# No seu servidor — chave secreta
curl -X POST https://n7pay.com/api/v1/charges \
  -H "Authorization: Bearer n7_sk_sand_SuaChaveAqui" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "297.00",
    "method": "card_7_12x",
    "installments": 12,
    "card_token": "8a1b2c3d-...",
    "external_reference": "payment_123",
    "ip": "189.10.20.30",
    "customer": {
      "name": "Maria Souza",
      "email": "maria@example.com",
      "document": "982.671.040-70"
    }
  }'

# Resposta 201 — cartão é síncrono, o status já é final
{
  "data": {
    "id": "uuid",
    "status": "paid",
    "method": "card_7_12x",
    "installments": 12,
    "amount": "297.00",
    "external_id": "pay_yxvvt5xg2tlzaong",
    "gateway_status": "CONFIRMED",
    "card_brand": "MASTERCARD",
    "card_last4": "8829",
    "authorization_url": null,
    "environment": "sandbox"
  }
}

Aprovação e recusa

Recusa não é 201. Quando o emissor nega, a resposta é 422 com o motivo dele — não um 201 com status negado. Trate os dois caminhos separadamente:

# 422 — recusado
{
  "error": "charge_declined",
  "details": [
    { "code": "invalid_credit_card", "message": "Cartão recusado pelo emissor." }
  ]
}

Os status possíveis num 201:

Quando authorization_url vier preenchido, o emissor exigiu autenticação 3DS: redirecione o pagador para essa URL e aguarde o webhook payment.paid.

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.

Isolamento entre empresas

Seus pagadores são seus. Mesmo com várias empresas usando a plataforma, o cadastro de um CPF que compra de você é separado do cadastro do mesmo CPF comprando de outra empresa — não há reuso de cliente entre contas, nem no N7 nem no gateway.

O identificador remoto fica em gateway_customer_ids e é reaproveitado nas cobranças seguintes, o que deixa a segunda compra do mesmo pagador mais rápida. Você não precisa gerenciar esse campo: ele é preenchido sozinho.

Parâmetros — POST /customers

# Criar cliente (PIX + cartão internacional)
curl -X POST https://n7pay.com/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

Gateways — o que você não precisa fazer

Você não abre conta, não configura webhook e não guarda credencial em gateway nenhum. A N7 Pay opera as contas de adquirência e cuida de toda essa camada; a sua integração termina na API do N7.

Quando o pagamento é confirmado na ponta, o N7 normaliza o evento e entrega para você num formato único — o mesmo payload independente de qual gateway processou. É o que está descrito em Webhooks de saída, e é o único que você precisa consumir.

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

Com o split ativo, o valor líquido de cada cobrança — o total menos a taxa N7, conforme o seu plano de tarifas — cai direto na sua carteira, e só a taxa fica retida pela N7. Não há repasse manual nem espera por transferência.

Nada muda na sua integração: você não envia parâmetro nenhum a mais. O net_amount devolvido em cada cobrança é exatamente o que vai para você.

O provisionamento da sua carteira é feito pela N7 durante o onboarding, a partir dos dados cadastrais da sua empresa. Se o split ainda não estiver ativo na sua conta, fale com o time N7 — não há nada a configurar por API.

Suporte Internacional

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

Exemplos cURL

Listar links

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

Criar link USD (Stripe)

curl -X POST https://n7pay.com/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/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/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/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")
  );
}