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.
https://api.nightpay.app/v1Caracterí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.
curl https://api.nightpay.app/v1/payments \
-H "Authorization: Bearer sua_api_key_aqui" \
-H "Content-Type: application/json"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.
2. Faça sua primeira requisição
// ⚠️ 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);product_id para seu servidor, que então valida e define o valor correto antes de chamar a API NightPay. Criar Pagamento
/paymentsCria um novo pagamento PIX anônimo e retorna o código PIX para o cliente.
• 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âmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
amount | float | Sim | Valor do pagamento em reais |
description | string | Sim | Descrição do pagamento (max 200 caracteres) |
customer_email | string | Não | Email do cliente (opcional) |
metadata | object | Não | Metadados customizados (JSON) |
expires_in | integer | Não | Tempo de expiração em minutos (padrão: 60) |
Resposta
{
"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
/payments/:idRetorna os detalhes de um pagamento específico.
curl https://api.nightpay.app/v1/payments/pay_1a2b3c4d5e6f \
-H "Authorization: Bearer sua_api_key"Resposta
{
"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
/paymentsLista todos os pagamentos com paginação.
Query Parameters
| Parâmetro | Tipo | Descrição |
|---|---|---|
limit | integer | Número de registros (padrão: 20, max: 100) |
offset | integer | Offset para paginação (padrão: 0) |
status | string | Filtrar por status: pending, paid, cancelled |
Cancelar Pagamento
/payments/:idCancela um pagamento pendente. Pagamentos já pagos não podem ser cancelados.
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.
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
/subscriptionsCria uma nova assinatura recorrente.
Parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
plan_id | string | Sim | ID do plano de assinatura |
customer_email | string | Sim | Email do cliente |
customer_name | string | Não | Nome do cliente |
trial_days | integer | Não | Dias de período de teste gratuito |
metadata | object | Não | Metadados customizados |
Exemplo
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
{
"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
/subscriptions/:idcurl -X DELETE https://api.nightpay.app/v1/subscriptions/sub_1a2b3c4d5e6f \
-H "Authorization: Bearer sua_api_key"Pausar Assinatura
/subscriptions/:id/pausePausa uma assinatura temporariamente. As cobranças não serão geradas até que seja reativada.
Reativar Assinatura
/subscriptions/:id/resumeReativa 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.
plan_id no seu código. Não é necessário criar planos via API! Criar Plano via API (Opcional)
/plansVocê pode criar planos via API, mas recomendamos criar no dashboard para maior facilidade.
| Parâmetro | Tipo | Descrição |
|---|---|---|
name | string | Nome do plano (ex: "Pro", "Premium") |
amount | float | Valor da cobrança em reais |
interval | string | Intervalo: monthly, quarterly, yearly |
trial_days | integer | Dias de teste padrão (opcional) |
{
"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
- Acesse o dashboard em
Configurações → Webhooks - Adicione a URL do seu endpoint
- Selecione os eventos que deseja receber
- Salve e copie o secret de assinatura
200 OK em até 5 segundos. Eventos de Webhook
payment.paid
Disparado quando um pagamento é confirmado.
{
"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.
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ódigo | Descrição |
|---|---|
200 | Sucesso |
400 | Requisição inválida |
401 | API Key inválida ou ausente |
404 | Recurso não encontrado |
429 | Rate limit excedido |
500 | Erro interno do servidor |
Formato 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.
test_ e de produção com live_Simular Pagamento
Use valores específicos para simular diferentes cenários:
100.00- Pagamento aprovado imediatamente200.00- Pagamento aprovado após 30 segundos999.00- Pagamento expirado
Rate Limits
Os limites de requisições variam por plano:
| Plano | Requisições/minuto |
|---|---|
| Básico | 60 req/min |
| Pro | 300 req/min |
| Enterprise | 1000 req/min |
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.
Fluxo de Integração
- Checkout: Cliente finaliza compra e escolhe PIX como forma de pagamento
- Frontend envia product_id: Frontend envia apenas identificadores dos produtos, nunca valores
- Backend valida: Seu servidor busca os preços corretos no banco de dados
- Gerar Pagamento: Backend chama a API NightPay com o valor validado
- Exibir QR Code: Mostre o QR Code PIX para o cliente
- Webhook: Receba notificação quando o pagamento for confirmado
- Confirmação: Libere o produto/serviço para o cliente
Exemplo Completo
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
});
});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! 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:
// ✅ 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
- Cliente escolhe um plano na sua aplicação
- Sistema cria assinatura via API com período de teste
- Cliente recebe email com instruções de pagamento
- Após teste, cobrança automática é gerada
- Renovações automáticas todos os meses/anos
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:
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:
// 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):
plan_donate_10, plan_donate_25, plan_donate_50, plan_donate_100 no dashboard e ofereça como opções de apoio mensal. // 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ê.