Documentação da API v2

Integre pagamentos PIX em sua aplicação com nossa API simples e segura

🚀 Início Rápido

1

Obter Token de Acesso

Use suas credenciais para obter um token de acesso válido por 1 hora

2

Gerar QR Code PIX

Use o token para gerar QR Codes PIX para seus clientes

3

Processar Pagamentos

Receba pagamentos instantâneos via PIX em sua aplicação

🌐 URL Base

Todas as requisições devem ser feitas para:

Production 
https://nexgenpag.com

🔑 Autenticação

A Nexgenpag utiliza autenticação OAuth 2.0. Primeiro obtenha um token de acesso, depois use-o nas requisições subsequentes.

Obter Token de Acesso

POST /oauth/token 
POST /v2/oauth/token
Authorization: Basic {base64(client_id:client_secret)}
Content-Type: application/json

Headers Requeridos

Header Valor Descrição
Authorization Basic {base64} Credenciais em Base64 (client_id:client_secret)
Content-Type application/json Tipo de conteúdo da requisição

Exemplo de Requisição

curl -X POST "https://nexgenpag.com/v2/oauth/token" \
  -H "Authorization: Basic $(echo -n 'client_id:client_secret' | base64)" \
  -H "Content-Type: application/json"

Exemplo de Resposta

200 - Sucesso
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "expires_in": 3600
}
401 - Erro de Autenticação
{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}

📱 Gerar QR Code PIX

Gere QR Codes PIX para receber pagamentos instantâneos.

POST /pix/qrcode 
POST /v2/pix/qrcode
Authorization: Bearer {access_token}
Content-Type: application/json

Headers Requeridos

Header Valor Descrição
Authorization Bearer {token} Token de acesso obtido na autenticação
Content-Type application/json Tipo de conteúdo da requisição

Parâmetros do Body

Parâmetro Tipo Obrigatório Descrição
amount number Sim Valor da transação (ex: 15.50)
external_id string Não ID externo da transação gerado por você
postbackUrl string Não URL de webhook para receber status do pagamento
payerQuestion string Não Descrição referente a transação
payer.name string Sim Nome completo do cliente
payer.document string Sim CPF/CNPJ do cliente
payer.email string Sim Email do cliente

Exemplo de Requisição

{
  "amount": 15.50,
  "external_id": "pedido_123456",
  "postbackUrl": "https://webhook.seusite.com/pix",
  "payerQuestion": "Pagamento do pedido #123456",
  "payer": {
    "name": "João Silva Santos",
    "document": "12345678900",
    "email": "joao.silva@email.com"
  }
}

Exemplo de Resposta

200 - Sucesso
{
  "transactionId": "4392d1d7e408d3cec04fm1zf3gv7vkq1",
  "external_id": "pedido_123456",
  "status": "PENDING",
  "amount": 15.50,
  "calendar": {
    "expiration": 3000,
    "dueDate": "2024-10-07 04:41:05"
  },
  "debtor": {
    "name": "João Silva Santos",
    "document": "12345678900"
  },
  "qrcode": "00020126850014br.gov.bcb.pix2563pix.voluti.com.br/qr/v3/at/6ed39bf2-bdc2-42b8-a95b-13d2212146b25204000053039865802BR5925BS PAYMENTS SOLUTIONS LTD6008SALVADOR62070503***63048D9B"
}
Importante: O QR Code expira em 50 minutos (3000 segundos). O status inicial é sempre "PENDING" e será atualizado via webhook quando o pagamento for confirmado.

⚠️ Tratamento de Erros

Códigos de Status HTTP

Código Descrição
200 Sucesso
400 Dados inválidos ou erro no pagamento
401 Token inválido ou expirado
403 Usuário inativo ou sem permissão
422 Erro de validação dos dados
500 Erro interno do servidor

Exemplos de Erro

401 - Token Inválido
{
  "error": "invalid_token",
  "error_description": "Access token is invalid or expired"
}
422 - Erro de Validação
{
  "error": "validation_error",
  "error_description": "Invalid input data",
  "details": {
    "amount": ["O campo amount é obrigatório."],
    "payer.email": ["O campo payer.email deve ser um email válido."]
  }
}

🧪 Testando a API

Script PHP de Teste

 true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Basic $auth",
        "Content-Type: application/json"
    ],
]);

$tokenResult = curl_exec($ch);
$tokenData = json_decode($tokenResult, true);
$accessToken = $tokenData['access_token'] ?? null;

if (!$accessToken) {
    die("Erro ao obter token: " . $tokenResult);
}

// 2. Gerar QR Code PIX
$pixUrl = "$baseUrl/v2/pix/qrcode";
$pixData = [
    'amount' => 15.50,
    'external_id' => 'teste_' . time(),
    'payerQuestion' => 'Pagamento de teste',
    'payer' => [
        'name' => 'João Silva',
        'document' => '12345678900',
        'email' => 'joao@email.com'
    ]
];

$ch = curl_init($pixUrl);
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer $accessToken",
        "Content-Type: application/json"
    ],
    CURLOPT_POSTFIELDS => json_encode($pixData),
]);

$pixResult = curl_exec($ch);
echo "Resposta PIX: " . $pixResult;