Guia de Introdução à API Npay.digital

Bem-vindo à documentação da API Npay.digital. Esta é sua porta de entrada para integrar nosso sistema de pagamentos à sua aplicação.

Visão Geral

A API Npay.digital é uma interface RESTful que utiliza JSON para serialização de dados. Todas as respostas da API, incluindo erros, são retornadas em formato JSON.

URL Base

https://api.npay.digital/v1/

Primeiros Passos

Siga estes passos para começar a integrar:

1. Obtenha suas chaves de API no painel do desenvolvedor
2. Configure a autenticação em sua aplicação
3. Comece com chamadas simples como verificação de saldo
4. Implemente os endpoints necessários para seu fluxo de pagamento
5. Configure webhooks para receber notificações em tempo real

Autenticação

A API Npay.digital utiliza autenticação via Bearer Token. Todas as requisições devem incluir o cabeçalho de autorização.

Obtendo seu Token

Seu token de API pode ser encontrado no painel do desenvolvedor após o registro.

Utilizando o Token

curl -X GET \
  https://api.npay.digital/v1/balance \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json'

Rate Limiting

Nossa API possui limites de requisições para garantir a estabilidade do serviço:

• Plano Gratuito: 100 requisições/minuto
• Plano Starter: 500 requisições/minuto
• Plano Pro: 2.000 requisições/minuto
• Plano Enterprise: Limites personalizados

Os cabeçalhos de resposta incluem informações sobre seu limite atual:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1627839900

Tratamento de Erros

A API utiliza códigos de status HTTP convencionais para indicar sucesso ou falha:

Exemplo de Resposta de Erro

{
  "error": {
    "code": "invalid_amount",
    "message": "O valor deve ser maior que R$ 1,00",
    "details": {
      "min_amount": 100,
      "currency": "BRL"
    }
  }
}

Criando um Pagamento

Abaixo está um exemplo completo de como criar uma transação PIX:

curl -X POST \
  https://api.npay.digital/v1/payments \
  -H 'Authorization: Bearer seu_token_aqui' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 10000,
    "currency": "BRL",
    "payment_method": "pix",
    "description": "Pagamento de serviço",
    "customer": {
      "name": "João Silva",
      "document": "123.456.789-09",
      "email": "joao@exemplo.com"
    },
    "metadata": {
      "order_id": "12345"
    }
  }'

{
  "id": "pay_123456789",
  "status": "pending",
  "amount": 10000,
  "currency": "BRL",
  "payment_method": "pix",
  "pix": {
    "qr_code": "00020126360014BR.GOV.BCB.PIX0114+5567999999999...",
    "qr_code_image": "https://api.npay.digital/v1/payments/pay_123456789/qr",
    "expires_at": "2023-08-20T23:59:59Z"
  },
  "created_at": "2023-08-20T12:00:00Z"
}

SDKs Oficiais

Disponibilizamos SDKs para facilitar a integração:

Instalação

npm install npay-digital

pip install npay-digital

composer require npay/digital

Exemplo com Node.js

const Npay = require('npay-digital');

const client = new Npay.Client(process.env.NPAY_API_KEY);

async function createPayment() {
  try {
    const payment = await client.payments.create({
      amount: 10000,
      currency: 'BRL',
      payment_method: 'pix',
      description: 'Pagamento de serviço',
      customer: {
        name: 'João Silva',
        document: '123.456.789-09',
        email: 'joao@exemplo.com'
      }
    });
    
    console.log('Pagamento criado:', payment);
  } catch (error) {
    console.error('Erro ao criar pagamento:', error);
  }
}

createPayment();

Coleção Postman

Para testar rapidamente nossa API, importe nossa coleção Postman:

Configuração do Ambiente

1. Importe a coleção no Postman
2. Crie um novo ambiente chamado "Npay.digital"
3. Adicione uma variável api_key com seu token
4. Comece a testar os endpoints!