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

Idempotency-Key

Envie o header Idempotency-Key em POST /charges e POST /charges/international para que uma requisição repetida devolva a mesma cobrança em vez de criar outra. É opcional, e sem ele o comportamento é o de sempre.

Idempotency-Key: 8f14e45f-ea0c-4b2e-9f5a-1c3d7b920a11

Use um valor por tentativa de pagamento, estável entre recargas da página: se o pagador recarregar enquanto a cobrança está sendo criada, é isso que impede a segunda cobrança. Gere um novo valor só quando for de fato um novo pedido.

Uma cobrança que falha devolve a chave: você pode repetir a mesma requisição com a mesma chave. A chave vale por 24 horas e é escopada por empresa e por ambiente, então o mesmo valor pode ser usado uma vez em sandbox e uma vez em produção.

A base URL é a mesma nos dois ambientes. Quem decide o ambiente é a chave, e tudo o que ela cria fica naquele ambiente: um cliente, uma cobrança ou um token criados com a chave sandbox não existem para a chave live, e vice-versa. Consultar com a chave de um ambiente o id criado no outro responde 404.

Ambiente Sandbox

O sandbox usa a infraestrutura de testes dos gateways. Nenhuma cobrança real é processada, e o formato de toda resposta e de todo webhook é o mesmo de produção.

Cartões de teste

No sandbox o resultado depende do número do cartão. Verificado contra o sandbox do Asaas em outubro de 2026, pelo mesmo caminho da API da N7:

Simulando pago, recusado e contestado

No sandbox ninguém paga um Pix, nenhum banco abre contestação e a análise de risco não reprova cartão. Para o seu sistema receber esses eventos antes de produção, a N7 aplica o desfecho que você pedir numa cobrança sandbox, pelo mesmo caminho de um desfecho real: o status muda, o paid_at é gravado quando for o caso, e o webhook sai para os seus endpoints sandbox com o formato e a assinatura de produção.

curl -X POST https://n7pay.com/api/v1/sandbox/charges/5fac4bcb-4e84-4a90-babf-195419aca231/simulate \
  -H "Authorization: Bearer n7_sk_sand_SuaChaveAqui" \
  -H "Content-Type: application/json" \
  -d '{"event": "payment.paid"}'

# Resposta 200: a transação, como em GET /transactions/:id, mais
# "simulated_event": "payment.paid" e "gateway_synced": true

Estorno não passa pelo simulador: use o endpoint real, POST /charges/:id/refund, que funciona no sandbox e dispara payment.refunded. Com a chave live o simulador responde 403 sandbox_only; um evento fora da tabela, 422 invalid_event; e uma cobrança fora do status de partida, 422 invalid_transition.

Roteiro de testes

A mesma sequência serve para os dois ambientes, trocando a chave. No sandbox ela não move dinheiro; em produção, use um cartão seu e um valor baixo, e estorne no fim.

1. No painel, com o ambiente certo selecionado, crie a chave secreta e cadastre o endpoint de webhook em API & Webhooks. O segredo de assinatura é gerado pela N7, ou você cola o que o seu servidor já usa. Clique em Testar e confira que o seu servidor validou a assinatura do test.ping e respondeu 2xx.
2. POST /customers com nome, CPF, e-mail, telefone, postal_code e address_number. Guarde o id.
3. POST /tokens com esse customer_id e o cartão. Guarde o card_token.
4. POST /charges com method: "card_1x", o card_token, o mesmo customer_id, amount: "5.00" e uma Idempotency-Key. Espere 201 com status: "paid" e, em seguida, o webhook payment.paid.
5. Repita a cobrança sem ip, que é o caso da cobrança feita sem o pagador presente.
6. POST /charges/:id/refund em cada cobrança. Espere 201 e o webhook payment.refunded.
7. Pix: POST /charges com method: "pix". No sandbox, pague pelo simulador; em produção, pague o QR. Espere payment.paid.
8. Só no sandbox: um cartão de recusa para ver o 422, e o simulador com payment.denied e payment.chargeback para ver os webhooks que produção só manda quando acontecem.
9. Concilie por GET /transactions, filtrando por external_reference ou status.

Erros

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

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

O campo description em cobrança no Brasil

Numa cobrança em BRL, a descrição não pode conter emoji nem qualquer outro caractere acima de U+FFFF, que em UTF-8 são as sequências de quatro bytes. É uma restrição do Asaas, e a N7 recusa antes de chamar o gateway para você receber um erro que nomeia o caractere em vez de um parse_error que fala em "caracteres especiais" sem dizer quais.

Acento, cedilha, travessão, cifrão, pontuação e ideograma passam. Só a faixa acima de U+FFFF é recusada. Em cobrança USD pelo Stripe a restrição não existe: ela é do gateway, e a N7 não a impõe a quem não a tem.

// recusado
{ "amount": "50.00", "currency": "BRL", "method": "pix",
  "description": "Ingresso Arena 🎟" }

// resposta 422
{
  "error": "invalid_params",
  "details": {
    "description": "não pode conter 🎟. O Asaas recusa emoji e outros caracteres acima de U+FFFF. Acento, cedilha e pontuação são aceitos."
  }
}

// aceito
{ "amount": "50.00", "currency": "BRL", "method": "pix",
  "description": "Ingresso Arena · São Paulo · lote 1" }

Rate Limit

Limites por chave de API: 1000 requisições por minuto em live e 100 em sandbox, em janela deslizante.

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

# Pagas de um pedido
curl "https://n7pay.com/api/v1/transactions?external_reference=order_1042&status=paid" \
  -H "Authorization: Bearer n7_sk_live_SuaChaveAqui"

# Resposta 200
{
  "data": [ { "id": "5fac4bcb-...", "status": "paid", "paid_at": "2026-10-07T14:03:11Z", ... } ],
  "has_more": false
}

Para percorrer tudo, repita a chamada com starting_after igual ao id do último item enquanto has_more for true. A página segue a ordem de criação, então uma venda nova entrando no meio da leitura não faz nenhuma transação aparecer duas vezes nem sumir.

Datas da transação

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, mudando 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, porque a faixa é que define o teto:

A moeda decide o gateway

Você não escolhe o gateway. Envia currency e a N7 roteia. O mesmo endpoint serve real e dólar, e a forma da resposta muda conforme quem atendeu.

Se nenhum gateway ativo da sua conta declarar a moeda pedida, a resposta é 503 no_gateway_available. Se um gateway for roteado mas ainda não atender cobrança direta, é 422 gateway_not_supported, que é diferente de unsupported_method: o método estava certo, o gateway é que não atende.

Parâmetros de 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": "5fac4bcb-4e84-4a90-babf-195419aca231",
    "status": "pending",
    "amount": "49.90",
    "currency": "BRL",
    "method": "pix",
    "external_id": "pay_8fHtX3kZq",
    "pix_qr_code": "00020126580014br.gov.bcb.pix0136...",
    "pix_qr_image": "iVBORw0KGgoAAAANSUhEUgAAAcIAAAHCAQ...",
    "pix_qr_image_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAcIAAAHCAQ...",
    "pix_qr_status": "ready",
    "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/5fac4bcb-4e84-4a90-babf-195419aca231 \
  -H "Authorization: Bearer n7_sk_sand_SuaChaveAqui"

Confirmando uma cobrança do Stripe no navegador

Fora de BRL quem atende é o Stripe, e existem dois caminhos. Eles são exclusivos: escolha um. Em POST /charges/international o card_token é opcional, então não enviá-lo coloca você no segundo caminho.

// 1. Monte o campo de cartão com a chave que veio na cobrança
const stripe = Stripe(cobranca.stripe_publishable_key);
const cardElement = stripe.elements().create("card");
cardElement.mount("#card-element");

// 2. Confirme passando o client_secret E o cartão
const { error, paymentIntent } = await stripe.confirmCardPayment(
  cobranca.client_secret,
  {
    payment_method: {
      card: cardElement,
      billing_details: { name: "Maria Silva", email: "maria@email.com" }
    }
  }
);

if (error) {
  // cartão recusado, ou 3DS cancelado pelo pagador
  mostrarErro(error.message);
} else if (paymentIntent.status === "succeeded") {
  // autorizado. O status na N7 chega pelo webhook payment.paid
  aguardarConfirmacao(cobranca.id);
}

Tokenização de cartão

Cobrança com cartão nunca precisa trafegar o número do cartão pelo seu servidor: ele pode ser 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. Isso é imposto pela API, não é convenção: usar uma chave publicável em qualquer outro endpoint devolve 403 publishable_key_not_allowed. 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, sem precisar criar chave nem variável nova. O corpo é idêntico ao do caminho A.

Caminho C: cartão inline, roteamento livre

Envie o cartão direto no POST /charges, no objeto card, e omita o card_token. É o único caminho em que a N7 escolhe o gateway pelo custo no momento da cobrança, porque nada foi decidido antes. Também é o caminho a usar quando a tokenização ainda não estiver liberada na sua conta pelo gateway.

Em troca, o número do cartão passa pelo seu servidor, e isso coloca você no escopo de PCI DSS. Se esse escopo for um problema, use o caminho A e aceite a restrição de roteamento.

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, porque o cartão passa pelo seu servidor.

Parâmetros de 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": "n7tok_asaas_8a1b2c3d-...",
    "gateway": "asaas",
    "brand": "MASTERCARD",
    "last4": "8829",
    "customer_id": "44dcf7a7-ebc3-4ad7-b122-01f404cda545"
  }
}

Guarde o card_token inteiro, com o prefixo: ele diz a que gateway o token pertence. É ele que permite cobrar de novo sem pedir o cartão ao pagador.

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" \
  -H "Idempotency-Key: pedido-1042-tentativa-1" \
  -d '{
    "amount": "297.00",
    "method": "card_7_12x",
    "installments": 12,
    "customer_id": "44dcf7a7-ebc3-4ad7-b122-01f404cda545",
    "card_token": "n7tok_asaas_8a1b2c3d-...",
    "external_reference": "payment_123",
    "ip": "189.10.20.30"
  }'

# 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",
    "customer_id": "44dcf7a7-ebc3-4ad7-b122-01f404cda545",
    "external_reference": "payment_123",
    "paid_at": "2026-10-07T14:03:11Z",
    "authorization_url": null,
    "environment": "sandbox"
  }
}

Aprovação e recusa

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

# 422 · recusado
{
  "error": "charge_declined",
  "details": [
    {
      "code": "invalid_action",
      "message": "Transação não autorizada. Verifique os dados do cartão de crédito e tente novamente."
    }
  ]
}

A recusa na chamada não cria transação nem dispara webhook: a cobrança não chegou a existir, e o 422 é o único aviso. charge_declined cobre toda recusa do gateway, a do emissor e a de dado que ele não aceitou, como um token usado em outro cliente; a diferença está em details. Mostre ao pagador a message, e ofereça outro cartão.

Os status possíveis num 201:

payment.denied existe só para esse caso, a recusa que chega depois. Em sandbox, exercite os dois caminhos com os cartões de recusa, que produzem o 422, e com o simulador, que produz o payment.denied.

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.

Todo cliente pertence ao ambiente da chave que o criou. A listagem, a consulta e a atualização só enxergam o ambiente da chave usada: o mesmo CPF pode ter um cadastro no sandbox e outro em produção, e cada chave vê só o seu. É o que garante que um cartão salvo em produção nunca seja cobrado num cliente de teste.

Parâmetros de 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",
    "address_number": "100"
  }'

# Resposta 201
{
  "data": {
    "id": "44dcf7a7-ebc3-4ad7-b122-01f404cda545",
    "name": "João da Silva",
    "email": "joao@exemplo.com",
    "document": "123.456.789-00",
    "country": "BR",
    "zip_code": "01310-100",
    "environment": "sandbox",
    "gateway_customer_ids": {},
    "metadata": { "address_number": "100" },
    "created_at": "2026-06-08T15:00:00"
  }
}

gateway_customer_ids nasce vazio e é preenchido em segundo plano, segundos depois, ou na primeira tokenização ou cobrança, o que vier antes. Você não precisa esperar por ele: o id da N7 já serve para POST /tokens e POST /charges.

Webhooks de saída (N7 para o seu servidor)

Configure endpoints HTTPS no seu dashboard para receber o desfecho de cada cobrança. É por aqui que você sabe que um PIX foi pago: a resposta de POST /charges devolve pending, e a confirmação chega depois.

1. você      POST /charges                    → recebe id e QR, status pending
2. comprador paga o PIX no banco dele
3. Asaas     avisa a N7                       ← webhook da N7, já configurado
4. N7        marca a transação como paid
5. N7        POST no SEU endpoint              → payment.paid, assinado
6. você      emite o ingresso

O que você configura

Só duas coisas, no painel da N7: a URL que recebe os eventos e o segredo que assina cada entrega. Nada no Asaas, nada no Stripe.

1. No topo do painel, escolha o ambiente: Sandbox ou Produção. O endpoint é cadastrado no ambiente que estiver selecionado, e só recebe eventos daquele ambiente.
2. Em API & Webhooks, clique em Adicionar endpoint. Informe a URL (HTTPS, pública) e, se quiser, os eventos; vazio assina todos.
3. No campo Segredo de assinatura, cole o segredo que o seu servidor já usa para validar o X-N7-Signature, com pelo menos 16 caracteres, ou deixe em branco para a N7 gerar um. O segredo aparece na lista de endpoints; clique nele para copiar.
4. Clique em Testar. A N7 envia um test.ping assinado com o mesmo segredo e os mesmos cabeçalhos de um evento real, e mostra o HTTP que o seu servidor respondeu.

Para receber sandbox e produção na mesma URL, cadastre o endpoint duas vezes, uma em cada ambiente, com o mesmo segredo ou com segredos diferentes. O cabeçalho X-N7-Environment e o campo environment do corpo dizem de qual ambiente veio cada evento.

Headers de cada entrega

Verificando a assinatura

// Node.js · Express, com o corpo cru preservado
// app.use("/webhooks/n7", express.raw({ type: "application/json" }));
const crypto = require("crypto");

function verify(rawBody, headers, secret) {
  const received = String(headers["x-n7-signature"] || "").replace(/^sha256=/, "");
  const timestamp = String(headers["x-n7-timestamp"] || "");

  // rejeita entregas antigas, contra replay
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(timestamp + "." + rawBody)
    .digest("hex");

  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

# Elixir
def valid_signature?(raw_body, headers, secret) do
  received = headers |> Map.get("x-n7-signature", "") |> String.replace_prefix("sha256=", "")
  timestamp = Map.get(headers, "x-n7-timestamp", "")

  expected =
    :crypto.mac(:hmac, :sha256, secret, "#{timestamp}.#{raw_body}")
    |> Base.encode16(case: :lower)

  Plug.Crypto.secure_compare(expected, received)
end

# Ruby on Rails · o corpo cru vem de request.raw_post, nunca de params.to_json
def n7_signature_valid?(request, secret)
  received  = request.headers["X-N7-Signature"].to_s.delete_prefix("sha256=")
  timestamp = request.headers["X-N7-Timestamp"].to_s
  return false if (Time.now.to_i - timestamp.to_i).abs > 300

  expected = OpenSSL::HMAC.hexdigest("SHA256", secret, "#{timestamp}.#{request.raw_post}")
  ActiveSupport::SecurityUtils.secure_compare(expected, received)
end

Formato do payload

{
  "event": "payment.paid",
  "environment": "live",
  "occurred_at": "2026-10-07T14:03:12",
  "data": {
    "transaction_id": "5fac4bcb-4e84-4a90-babf-195419aca231",
    "payment_link_id": null,
    "external_id": "pay_yxvvt5xg2tlzaong",
    "external_reference": "order_99001",
    "status": "paid",
    "method": "card_1x",
    "currency": "BRL",
    "amount": "5.00",
    "fee_amount": "0.40",
    "net_amount": "4.60",
    "installments": 1,
    "paid_at": "2026-10-07T14:03:11Z",
    "gateway": "Asaas",
    "customer": {
      "id": "44dcf7a7-ebc3-4ad7-b122-01f404cda545",
      "name": "Maria Souza",
      "email": "maria@example.com",
      "document_type": "cpf"
    },
    "metadata": {
      "external_reference": "order_99001",
      "card_brand": "VISA",
      "card_last4": "4444",
      "paid_at": "2026-10-07T14:03:11Z"
    }
  }
}

Eventos disponíveis

Assinar uma lista vazia significa receber todos. Hoje apenas quatro chegam a ser entregues, porque só eles representam mudança de desfecho de uma transação. Cada um sai no máximo uma vez por transação, mesmo quando o gateway avisa a N7 mais de uma vez: o cartão, por exemplo, é confirmado na aprovação e de novo quando o dinheiro cai, e você recebe um payment.paid só.

Reentrega

Uma entrega conta como recebida quando o seu servidor responde 2xx em até 10 segundos. Qualquer outra resposta, timeout ou erro de conexão é repetido, com o mesmo corpo e o mesmo X-N7-Delivery, até oito tentativas: na hora, e depois de 30 segundos, 2 minutos, 10 minutos, 30 minutos, 1 hora, 2 horas e 4 horas. A última sai umas oito horas depois da primeira. Cada tentativa aparece no painel, com o HTTP que o seu servidor respondeu.

Cotação de câmbio

A cotação é um recurso persistido, não um cálculo na hora: ela é travada, tem validade curta e é de uso único. Sem isso a taxa muda entre a tela que o pagador viu e a cobrança que ele recebeu, e a diferença sai do bolso de alguém.

Parâmetros

O header Idempotency-Key é honrado: a mesma chave com o mesmo corpo devolve a mesma cotação, em vez de abrir posição cambial duas vezes. A mesma chave com corpo diferente é recusada com 422 idempotency_key_reused.

Por isso a chave aqui é por tentativa de cotação, e não por pedido. Um pedido vive minutos ou horas; uma cotação vive ttl_seconds, por padrão bem menos. Versione o valor (pedido_88213.v1, .v2) ou use um UUID novo a cada tentativa, e confira expires_in antes de cobrar.

POST /api/v1/fx/quotes
Authorization: Bearer n7_sk_sand_…
Idempotency-Key: pedido_88213.v1

{
  "from_currency": "BRL",
  "to_currency": "USD",
  "amount": "50.00",
  "side": "target",
  "method": "pix",
  "ttl_seconds": 120
}

# Resposta 201
{
  "data": {
    "id": "24575497-3b27-4ded-9ceb-7c475a051ae8",
    "status": "active",
    "amount": "50.00",
    "quoted_amount": "261.49",
    "base_rate": "0.19503442",
    "spread_pct": "2.00",
    "effective_rate": "0.19121022",
    "expires_in": 119,
    "rate": { "source": "ptax", "observed_at": "2026-09-02T13:02:37Z", "stale": false },
    "breakdown": {
      "base_rate": "0.19503442",
      "rate_source": "ptax",
      "spread_pct": "2.00",
      "spread_amount": "5.12",
      "amount_without_spread": "256.37",
      "charged_amount": "261.49",
      "gateway_fee": "2.39",
      "iof": null,
      "iof_note": "Não há operação de câmbio nesta cobrança: o valor entra e sai na mesma moeda."
    }
  }
}

Duas coisas decidem quem paga o quê

side decide quem come o spread. Em target o pagador entrega mais, em source você recebe menos. O spread é receita da N7 nos dois casos.

fee_strategy decide quem paga a tarifa, exatamente como no link de pagamento. Com pass_on e side: target, você recebe exatamente o valor que pediu.

Exemplo com US$ 50,00 a R$ 5,42, spread de 2% e tarifa Pix de R$ 2,39.

Erros

A regra que amarra todos: nunca recotar em silêncio.

Cobrança internacional

Cobra em real uma venda precificada em moeda estrangeira, consumindo uma cotação travada. É aqui que o quote_id vira cobrança.

POST /api/v1/charges/international
{
  "quote_id": "867e72a5-330b-4267-8d45-c1162392cf0a",
  "amount": "50.00",
  "currency": "USD",
  "method": "pix",
  "external_reference": "order_arena_1",
  "customer": { "name": "Ana Souza", "email": "ana@exemplo.com", "document": "12345678909" }
}

# Resposta 201
{
  "data": {
    "status": "pending",
    "amount": "263.88",
    "currency": "BRL",
    "fee_amount": "2.39",
    "fee_pct": "0.00",
    "fee_fixed": "2.39",
    "pix_qr_code": "00020101021226820014br.gov.bcb.pix…",
    "pix_qr_image_url": "data:image/png;base64,iVBORw0KGgo…",
    "pix_qr_status": "ready",
    "fx": {
      "original_amount": "50.0000",
      "original_currency": "USD",
      "rate": "0.19503442",
      "effective_rate": "0.19121022",
      "spread_pct": "2.00",
      "settlement_currency": "BRL",
      "breakdown": {
        "charge_currency": "BRL",
        "charge_amount": "263.88",
        "settlement_currency": "USD",
        "settlement_amount": "50.00",
        "spread_amount": "5.15",
        "gateway_fee": "2.39"
      }
    }
  }
}

O objeto fx

Erros do fluxo internacional

Estornos

Estorna uma cobrança paga, total ou parcial. Parciais podem ser repetidos até somar o valor da venda. Funciona nos dois gateways.

Quem fica com a taxa

Por padrão a N7 devolve a própria margem e retém apenas o custo do gateway. A N7 empata, você perde só o custo real da transação, e ninguém lucra com um estorno. A resposta mostra os três números para você conseguir explicar a diferença ao seu cliente e lançar na contabilidade.

# Venda de US$ 120,00, tarifa N7 de US$ 4,98, taxa do gateway de US$ 3,78
# Estorno de US$ 80,00

POST /api/v1/charges/14ac03e6-d431-411b-b732-beedc125826c/refund
{ "amount": "80.00", "reason": "requested_by_customer" }

# Resposta 201
{
  "data": {
    "id": "7c31703b-c5b1-42e0-aaea-d8eaacda632e",
    "transaction_id": "14ac03e6-d431-411b-b732-beedc125826c",
    "status": "done",
    "amount": "80.00",
    "currency": "USD",
    "gateway_refund_id": "re_3UBHe6EWFlHBWTiI0pja5fzG",
    "gateway_fee_retained": "2.52",
    "n7_fee_refunded": "0.80",
    "net_returned_to_merchant": "77.48",
    "refundable_balance": "0.00"
  }
}

Erros

Gateways: o que você não precisa fazer

No modelo padrão 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.

Existe um segundo modelo para quem já tem contrato próprio com uma adquirente: a conta continua sendo sua, o dinheiro não passa pela N7, e a N7 orquestra roteamento, conciliação e webhooks por cima dela. Nesse caso a credencial é cadastrada uma vez no painel, fica guardada cifrada, e a cobrança falha com 424 missing_merchant_credentials enquanto ela não existir. Não há queda silenciosa para a conta da N7: uma venda sua nunca é processada na conta de outro.

Qual dos dois vale é definido por gateway, não por integração, e a resposta da cobrança não muda em nenhum dos casos. Se você não pediu o segundo, está no primeiro.

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, ou seja, 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, porque não há nada a configurar por API.

Em que moeda você recebe

A resposta depende da rota, e não da moeda em que você precificou. O que decide é a moeda em que a cobrança sai, porque é ela que o pagador paga e é ela que entra.

O saldo é por moeda, nunca somado: uma venda de US$ 50 entra no saldo em dólar, e não como 50 no saldo em reais. O painel mostra um cartão por moeda. Não existe endpoint de saldo nem de saque na API: consulte o painel, ou some o net_amount das transações paid por currency em GET /transactions.

Split Payment (CBS e IBS)

Não confunda com o split de receita acima. Aquele divide o dinheiro entre você e a N7. Este separa o tributo da reforma tributária no momento da liquidação e o encaminha para a Receita Federal (CBS) e para o Comitê Gestor do IBS.

Como funciona

Preencher os campos fiscais é o próprio ato de optar pelo split. Se você não enviar o bloco fiscal, a cobrança segue exatamente como hoje. Se enviar, o CBS e o IBS são separados do valor pago antes de o líquido chegar até você.

Escopo por método

Enviar fiscal em um método fora de escopo retorna 422 com split_not_eligible_for_method.

Parâmetros de POST /charges, bloco fiscal

Campos da resposta

Os campos de IBS seguem exatamente a mesma estrutura. CBS e IBS são calculados de forma independente e nunca se compensam entre si.

Como o valor segregado é calculado

Em boleto, Pix dinâmico e Pix automático o valor pago pode diferir do valor original, então entra proporcionalidade:

segregado = mín( (valor_pago / valor_original) * C , C , A )

C = cbs_corrigido quando existir, senão cbs_informado
A = cbs_em_aberto quando existir

# truncado para baixo em duas casas, sem arredondamento estatístico
# R$ 12,35954 vira R$ 12,35

Em Pix estático, TED e TEF não há proporcionalidade: o segregado é igual ao informado.

Eventos de webhook

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

// signature: o header X-N7-Signature ("sha256=..."); timestamp: o X-N7-Timestamp.
// O valor assinado é "{timestamp}.{corpo cru}", nunca o corpo sozinho.
function verifyWebhook(
  rawBody: Buffer,
  signature: string,
  timestamp: string,
  secret: string
): boolean {
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.`)
    .update(rawBody)
    .digest("hex");

  const received = signature.replace(/^sha256=/, "");
  const a = Buffer.from(expected);
  const b = Buffer.from(received);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}