Documentação NightPay API

Bem-vindo à documentação da API NightPay. Nossa API RESTful permite que você integre pagamentos anônimos via PIX de forma simples e segura.

Base URL: https://api.nightpay.app/v1

Características

  • API RESTful com JSON
  • Autenticação via API Key
  • Webhooks em tempo real
  • D+0 - Pagamento instantâneo
  • Suporte HTTPS obrigatório
  • Rate limiting generoso

Autenticação

Todas as requisições à API NightPay devem ser autenticadas usando sua API Key no header Authorization.

Request Example
curl https://api.nightpay.app/v1/payments \
  -H "Authorization: Bearer sua_api_key_aqui" \
  -H "Content-Type: application/json"
Importante: Nunca exponha sua API Key em código client-side ou repositórios públicos.

Início Rápido

Crie seu primeiro pagamento em menos de 5 minutos:

1. Obtenha sua API Key

Acesse o dashboard em dashboard.nightpay.app e gere sua API Key na seção de Configurações.

Dashboard NightPay: Use o dashboard para gerenciar planos de assinatura, produtos, webhooks e visualizar relatórios. No código, você apenas referencia os IDs criados lá. Isso facilita atualizações de preços sem precisar fazer deploy!

2. Faça sua primeira requisição

JavaScript / Node.js
// ⚠️ IMPORTANTE: Este código deve rodar no BACKEND (servidor)
// Nunca exponha sua API Key no frontend!

const response = await fetch('https://api.nightpay.app/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sua_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 100.00,
    description: 'Produto X',
    customer_email: 'cliente@email.com'
  })
});

const payment = await response.json();
console.log('Código PIX:', payment.pix_code);
Segurança: Todas as chamadas à API devem ser feitas no backend. Para produtos/serviços com preço fixo, o frontend deve enviar apenas o product_id para seu servidor, que então valida e define o valor correto antes de chamar a API NightPay.

Criar Pagamento

POST
/payments

Cria um novo pagamento PIX anônimo e retorna o código PIX para o cliente.

Sobre o parâmetro amount:
Valores Fixos (produtos, serviços, assinaturas): O amount deve ser determinado pelo backend após validar o product_id ou plan_id no banco de dados.
Valores Liberais (doações, contribuições): O amount pode vir do frontend, pois o usuário escolhe quanto quer pagar. Mesmo assim, é recomendado definir valores mínimos e máximos no backend.

Parâmetros

ParâmetroTipoObrigatórioDescrição
amountfloatSimValor do pagamento em reais
descriptionstringSimDescrição do pagamento (max 200 caracteres)
customer_emailstringNãoEmail do cliente (opcional)
metadataobjectNãoMetadados customizados (JSON)
expires_inintegerNãoTempo de expiração em minutos (padrão: 60)

Resposta

200 OK
{
  "id": "pay_1a2b3c4d5e6f",
  "status": "pending",
  "amount": 100.00,
  "description": "Produto X",
  "pix_code": "00020126580014br.gov.bcb.pix...",
  "qr_code_url": "https://api.nightpay.app/v1/qr/pay_1a2b3c4d5e6f",
  "expires_at": "2025-10-14T18:30:00Z",
  "created_at": "2025-10-14T17:30:00Z"
}

Consultar Pagamento

GET
/payments/:id

Retorna os detalhes de um pagamento específico.

Request Example
curl https://api.nightpay.app/v1/payments/pay_1a2b3c4d5e6f \
  -H "Authorization: Bearer sua_api_key"

Resposta

200 OK
{
  "id": "pay_1a2b3c4d5e6f",
  "status": "paid",
  "amount": 100.00,
  "description": "Produto X",
  "customer_email": "cliente@email.com",
  "paid_at": "2025-10-14T17:35:00Z",
  "created_at": "2025-10-14T17:30:00Z"
}

Listar Pagamentos

GET
/payments

Lista todos os pagamentos com paginação.

Query Parameters

ParâmetroTipoDescrição
limitintegerNúmero de registros (padrão: 20, max: 100)
offsetintegerOffset para paginação (padrão: 0)
statusstringFiltrar por status: pending, paid, cancelled

Cancelar Pagamento

DELETE
/payments/:id

Cancela um pagamento pendente. Pagamentos já pagos não podem ser cancelados.

Request Example
curl -X DELETE https://api.nightpay.app/v1/payments/pay_1a2b3c4d5e6f \
  -H "Authorization: Bearer sua_api_key"

Assinaturas e Pagamentos Recorrentes

A NightPay oferece suporte completo para assinaturas e cobranças recorrentes, ideal para SaaS, serviços mensais e conteúdo exclusivo.

Nota: As cobranças recorrentes geram novos códigos PIX automaticamente a cada ciclo de cobrança.

Características

  • Cobranças automáticas mensais, trimestrais ou anuais
  • Gerenciamento de múltiplos planos
  • Cancelamento e pausar assinaturas
  • Webhooks para cada renovação
  • Retry automático em caso de falha
  • Período de teste (trial) configurável

Como Funciona

Ao criar uma assinatura, a NightPay gera automaticamente um código PIX para o primeiro pagamento. Após a confirmação, o sistema agenda as próximas cobranças conforme o plano escolhido. A cada renovação, um novo código PIX é gerado e enviado ao cliente via email e webhook.

Criar Assinatura

POST
/subscriptions

Cria uma nova assinatura recorrente.

Parâmetros

ParâmetroTipoObrigatórioDescrição
plan_idstringSimID do plano de assinatura
customer_emailstringSimEmail do cliente
customer_namestringNãoNome do cliente
trial_daysintegerNãoDias de período de teste gratuito
metadataobjectNãoMetadados customizados

Exemplo

JavaScript / Node.js
const response = await fetch('https://api.nightpay.app/v1/subscriptions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sua_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    plan_id: 'plan_monthly_pro',
    customer_email: 'cliente@email.com',
    customer_name: 'João Silva',
    trial_days: 7
  })
});

const subscription = await response.json();
console.log(subscription);

Resposta

200 OK
{
  "id": "sub_1a2b3c4d5e6f",
  "status": "trialing",
  "plan_id": "plan_monthly_pro",
  "customer_email": "cliente@email.com",
  "current_period_start": "2025-10-14T17:30:00Z",
  "current_period_end": "2025-11-14T17:30:00Z",
  "trial_end": "2025-10-21T17:30:00Z",
  "created_at": "2025-10-14T17:30:00Z"
}

Gerenciar Assinatura

Você pode pausar, cancelar ou atualizar assinaturas através da API.

Cancelar Assinatura

DELETE
/subscriptions/:id
Request Example
curl -X DELETE https://api.nightpay.app/v1/subscriptions/sub_1a2b3c4d5e6f \
  -H "Authorization: Bearer sua_api_key"

Pausar Assinatura

POST
/subscriptions/:id/pause

Pausa uma assinatura temporariamente. As cobranças não serão geradas até que seja reativada.

Reativar Assinatura

POST
/subscriptions/:id/resume

Reativa uma assinatura pausada. As cobranças serão retomadas no próximo ciclo.

Planos de Assinatura

Gerencie diferentes planos de assinatura para seu negócio.

Dica: Crie seus planos diretamente no Dashboard NightPay. Depois, basta usar o plan_id no seu código. Não é necessário criar planos via API!

Criar Plano via API (Opcional)

POST
/plans

Você pode criar planos via API, mas recomendamos criar no dashboard para maior facilidade.

ParâmetroTipoDescrição
namestringNome do plano (ex: "Pro", "Premium")
amountfloatValor da cobrança em reais
intervalstringIntervalo: monthly, quarterly, yearly
trial_daysintegerDias de teste padrão (opcional)
Exemplo
{
  "name": "Plano Pro",
  "amount": 49.90,
  "interval": "monthly",
  "trial_days": 7
}

Configurar Webhooks

Webhooks permitem que você receba notificações em tempo real sobre eventos de pagamento.

Configuração

  1. Acesse o dashboard em Configurações → Webhooks
  2. Adicione a URL do seu endpoint
  3. Selecione os eventos que deseja receber
  4. Salve e copie o secret de assinatura
Seu endpoint deve responder com status 200 OK em até 5 segundos.

Eventos de Webhook

payment.paid

Disparado quando um pagamento é confirmado.

Payload
{
  "event": "payment.paid",
  "data": {
    "id": "pay_1a2b3c4d5e6f",
    "status": "paid",
    "amount": 100.00,
    "paid_at": "2025-10-14T17:35:00Z"
  }
}

payment.expired

Disparado quando um pagamento expira sem ser pago.

payment.cancelled

Disparado quando um pagamento é cancelado.

Segurança de Webhooks

Verifique a autenticidade dos webhooks usando a assinatura HMAC SHA-256 no header X-NightPay-Signature.

Node.js - Verificar Assinatura
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

Tratamento de Erros

A API retorna códigos HTTP padrão para indicar sucesso ou falha.

CódigoDescrição
200Sucesso
400Requisição inválida
401API Key inválida ou ausente
404Recurso não encontrado
429Rate limit excedido
500Erro interno do servidor

Formato de Erro

Resposta de Erro
{
  "error": {
    "type": "invalid_request",
    "message": "Valor mínimo é R$ 1,00",
    "field": "amount"
  }
}

Ambiente de Testes

Use a API Key de teste para simular pagamentos sem movimentar dinheiro real.

API Keys de teste começam com test_ e de produção com live_

Simular Pagamento

Use valores específicos para simular diferentes cenários:

  • 100.00 - Pagamento aprovado imediatamente
  • 200.00 - Pagamento aprovado após 30 segundos
  • 999.00 - Pagamento expirado

Rate Limits

Os limites de requisições variam por plano:

PlanoRequisições/minuto
Básico60 req/min
Pro300 req/min
Enterprise1000 req/min
Os headers X-RateLimit-Limit e X-RateLimit-Remaining indicam seu limite e saldo.

Caso de Uso: E-commerce

Integre pagamentos PIX anônimos em sua loja online com checkout simples e rápido.

Sobre Produtos: Para e-commerce, você pode cadastrar produtos no Dashboard NightPay ou no seu próprio banco de dados. O importante é que o backend sempre valide o preço antes de criar o pagamento.

Fluxo de Integração

  1. Checkout: Cliente finaliza compra e escolhe PIX como forma de pagamento
  2. Frontend envia product_id: Frontend envia apenas identificadores dos produtos, nunca valores
  3. Backend valida: Seu servidor busca os preços corretos no banco de dados
  4. Gerar Pagamento: Backend chama a API NightPay com o valor validado
  5. Exibir QR Code: Mostre o QR Code PIX para o cliente
  6. Webhook: Receba notificação quando o pagamento for confirmado
  7. Confirmação: Libere o produto/serviço para o cliente

Exemplo Completo

Backend - Node.js/Express
const express = require('express');
const app = express();

// ✅ CORRETO: Validar valores no backend
app.post('/checkout', async (req, res) => {
  const { product_id, customer_email } = req.body;
  
  // Buscar preço real do produto no banco de dados
  const product = await db.products.findById(product_id);
  
  if (!product) {
    return res.status(404).json({ error: 'Produto não encontrado' });
  }
  
  // Criar pagamento com valor validado
  const payment = await fetch('https://api.nightpay.app/v1/payments', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer ' + process.env.NIGHTPAY_API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: product.price, // ✅ Valor do banco de dados
      description: product.name,
      customer_email: customer_email,
      metadata: { 
        product_id: product.id,
        order_id: await createOrder(product_id, customer_email)
      }
    })
  }).then(r => r.json());
  
  res.json({ 
    payment_id: payment.id,
    qr_code_url: payment.qr_code_url,
    pix_code: payment.pix_code
  });
});
Nunca faça isso: Aceitar o valor (amount) diretamente do frontend. Um usuário mal-intencionado pode modificar o valor no cliente e comprar produtos por preços menores. Sempre valide preços no backend!
Dica: Salve o payment_id junto com o pedido para rastrear o status via webhook.

Caso de Uso: SaaS & Assinaturas

Monetize seu software com assinaturas recorrentes e períodos de teste.

Configuração de Planos

Primeiro, crie seus planos no Dashboard NightPay em Configurações → Planos:

  • Plano Pro Mensal - R$ 49,90/mês (ID: plan_pro_monthly)
  • Plano Pro Anual - R$ 499,00/ano (ID: plan_pro_yearly)
  • Plano Enterprise - R$ 199,00/mês (ID: plan_enterprise_monthly)

Depois, simplesmente use os IDs no seu código:

Usar Planos no Código
// ✅ Backend - Usar plan_id criado no dashboard
app.post('/subscribe', async (req, res) => {
  const { plan_id, customer_email } = req.body;
  
  // Validar planos permitidos
  const validPlans = [
    'plan_pro_monthly',
    'plan_pro_yearly',
    'plan_enterprise_monthly'
  ];
  
  if (!validPlans.includes(plan_id)) {
    return res.status(400).json({ error: 'Plano inválido' });
  }
  
  // Criar assinatura (valores já estão no plano)
  const subscription = await createSubscription({
    plan_id: plan_id, // Plano criado no dashboard
    customer_email: customer_email
  });
  
  res.json(subscription);
});

Fluxo de Assinatura

  1. Cliente escolhe um plano na sua aplicação
  2. Sistema cria assinatura via API com período de teste
  3. Cliente recebe email com instruções de pagamento
  4. Após teste, cobrança automática é gerada
  5. Renovações automáticas todos os meses/anos
Importante: Configure webhooks para subscription.renewed e subscription.payment_failed para gerenciar renovações.

Caso de Uso: Marketplace

Gerencie pagamentos entre compradores e múltiplos vendedores com split de pagamento.

Split de Pagamento

Divida o valor da transação entre vendedores e a plataforma:

Split Example
const payment = await createPayment({
  amount: 100.00,
  description: 'Produto marketplace',
  splits: [
    {
      recipient_id: 'vendor_123',
      percentage: 85, // 85% para vendedor
      liable: true
    },
    {
      recipient_id: 'platform',
      percentage: 15 // 15% taxa da plataforma
    }
  ]
});

Múltiplos Vendedores

Cadastre vendedores na plataforma e gerencie os repasses automaticamente. Cada vendedor recebe sua parte sem precisar compartilhar dados bancários.

Caso de Uso: Doações

Receba doações mantendo total privacidade dos doadores e beneficiários.

Doações Únicas

Para doações, o valor pode ser escolhido pelo usuário, mas é recomendado validar limites no backend:

Single Donation
// Backend - Validar limites de doação
app.post('/donate', async (req, res) => {
  let { amount, donor_email, project_id } = req.body;
  
  // Validar valor mínimo e máximo
  amount = parseFloat(amount);
  if (amount < 5.00 || amount > 10000.00) {
    return res.status(400).json({ 
      error: 'Valor deve estar entre R$ 5,00 e R$ 10.000,00' 
    });
  }
  
  const donation = await createPayment({
    amount: amount,
    description: `Doação - Projeto ${project_id}`,
    customer_email: donor_email,
    metadata: {
      type: 'donation',
      project: project_id,
      anonymous: req.body.anonymous || false
    }
  });
  
  res.json(donation);
});

Doações Recorrentes

Para doações recorrentes, crie planos predefinidos no Dashboard (ex: R$ 10, R$ 25, R$ 50, R$ 100):

Dica: Crie planos como plan_donate_10, plan_donate_25, plan_donate_50, plan_donate_100 no dashboard e ofereça como opções de apoio mensal.
Recurring Donation
// Backend - Usar plan_id validado
app.post('/donate/recurring', async (req, res) => {
  const { plan_id, donor_email } = req.body;
  
  // Validar se o plano existe e é de doação
  const validPlans = ['plan_donate_10', 'plan_donate_25', 'plan_donate_50', 'plan_donate_100'];
  if (!validPlans.includes(plan_id)) {
    return res.status(400).json({ error: 'Plano inválido' });
  }
  
  const recurringDonation = await createSubscription({
    plan_id: plan_id, // ✅ Valor do plano é fixo
    customer_email: donor_email,
    metadata: {
      type: 'recurring_donation',
      cause: req.body.cause || 'general'
    }
  });
  
  res.json(recurringDonation);
});

Benefícios para Doações

  • Doadores mantêm privacidade completa
  • Sem exposição de dados bancários
  • Recibos automáticos por email
  • Dashboard com analytics de doações
  • Webhooks para agradecimentos automáticos

Precisa de Ajuda?

Nossa equipe de suporte 100% humanizado está pronta para ajudar você.

Chat & Email

Resposta em até 2 horas

suporte@nightpay.app

Gerente Dedicado

Planos Enterprise

Ver Planos

Central de Ajuda

Guias e tutoriais

Ver FAQ