Documentação da API NexyPay
Integre PIX em minutos. Nossa API REST é simples, rápida e foi desenhada para infoprodutores e e-commerces que precisam receber pagamentos sem complicação.
1. Autentique-se
Pegue sua API Key no painel e inclua em todas as requisições.
2. Crie um PIX
Envie um POST para gerar QR Code e código copia-e-cola.
3. Receba o webhook
Notificamos seu servidor automaticamente quando o cliente paga.
Autenticação
Todas as requisições autenticadas devem incluir sua api-key no corpo (JSON) da requisição. Você pode encontrar e regenerar sua chave no painel em Gateway → API Keys.
IPs Autorizados (opcional)
Para segurança extra, configure no painel uma lista de IPs autorizados. Requisições vindas de IPs fora dessa lista serão recusadas mesmo com a chave correta.
Quick start
O fluxo típico de pagamento com PIX leva 3 passos:
- Você chama
POST /api/v1/gateway/para gerar uma cobrança PIX → recebe QR Code + código copia-e-cola. - Apresenta o QR Code para o cliente — ele paga no app do banco dele.
- Assim que o pagamento cai, enviamos um webhook
POSTpara anotification_urlque você cadastrou.
POST /api/v1/webhook/ caso prefira polling em vez de webhook (não recomendado para alto volume).
Gerar PIX
Cria uma cobrança PIX com QR Code e código copia-e-cola. A cobrança expira em 30 minutos por padrão.
Parâmetros
| Campo | Tipo | Descrição |
|---|---|---|
| api-keyobrigatório | string | Sua chave de API. |
| amountobrigatório | number | Valor da cobrança em reais (ex.: 10.50). |
| methodobrigatório | string | Método de pagamento. Use "pix". |
| clientobrigatório | object | Dados do pagador. Ver tabela abaixo. |
| notification_urlopcional | string | URL HTTPS para receber webhook de pagamento. |
Objeto client
| Campo | Tipo | Descrição |
|---|---|---|
| nameobrigatório | string | Nome completo do pagador. |
| documentobrigatório | string | CPF ou CNPJ (apenas dígitos). |
| emailopcional | string | E-mail do pagador. |
| telefoneopcional | string | Telefone com DDD (apenas dígitos). |
Exemplo de requisição
curl -X POST https://app.nexypay.com.br/api/v1/gateway/ \
-H "Content-Type: application/json" \
-d '{
"api-key": "sua_api_key_aqui",
"amount": 10.50,
"method": "pix",
"client": {
"name": "João da Silva",
"document": "12345678900",
"email": "joao@example.com",
"telefone": "11987654321"
},
"notification_url": "https://seusite.com/webhook"
}'
<?php
$payload = [
'api-key' => 'sua_api_key_aqui',
'amount' => 10.50,
'method' => 'pix',
'client' => [
'name' => 'João da Silva',
'document' => '12345678900',
'email' => 'joao@example.com',
'telefone' => '11987654321',
],
'notification_url' => 'https://seusite.com/webhook',
];
$ch = curl_init('https://app.nexypay.com.br/api/v1/gateway/');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
echo $data['paymentCodeBase64']; // base64 do QR Code (use em <img src="data:image/png;base64,...">)
echo $data['paymentCode']; // PIX copia-e-cola
echo $data['idTransaction']; // guarde pra consultar status depois
const fetch = require('node-fetch');
const payload = {
'api-key': 'sua_api_key_aqui',
amount: 10.50,
method: 'pix',
client: {
name: 'João da Silva',
document: '12345678900',
email: 'joao@example.com',
telefone: '11987654321',
},
notification_url: 'https://seusite.com/webhook',
};
const response = await fetch('https://app.nexypay.com.br/api/v1/gateway/', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify(payload),
});
const data = await response.json();
console.log(data.paymentCodeBase64); // base64 do QR Code
console.log(data.paymentCode); // PIX copia-e-cola
console.log(data.idTransaction); // guarde pra consultar status
import requests
payload = {
"api-key": "sua_api_key_aqui",
"amount": 10.50,
"method": "pix",
"client": {
"name": "João da Silva",
"document": "12345678900",
"email": "joao@example.com",
"telefone": "11987654321",
},
"notification_url": "https://seusite.com/webhook",
}
r = requests.post(
"https://app.nexypay.com.br/api/v1/gateway/",
json=payload,
timeout=30,
)
data = r.json()
print(data["paymentCodeBase64"]) # base64 do QR Code
print(data["paymentCode"]) # PIX copia-e-cola
print(data["idTransaction"]) # guarde pra consultar status
Resposta de sucesso
{
"status": "success",
"message": "ok",
"idTransaction": "pv_69feca85b384e6.39636537",
"paymentCode": "00020126580014BR.GOV.BCB.PIX...",
"paymentCodeBase64": "iVBORw0KGgoAAAANSUhEUgAA..."
}
•
idTransaction — guarde para consultar status depois•
paymentCode — código PIX copia-e-cola•
paymentCodeBase64 — imagem PNG do QR Code em base64 (use direto em <img src="data:image/png;base64,...">)
Solicitar Saque (Cash Out)
Envia um valor do seu saldo NexyPay para uma chave PIX externa. Saques acima de R$ 5.000 passam por análise antes da liberação.
Parâmetros
| Campo | Tipo | Descrição |
|---|---|---|
| api-keyobrigatório | string | Sua chave de API. |
| amountobrigatório | number | Valor a sacar em reais. |
| pix_keyobrigatório | string | Chave PIX destino (CPF, CNPJ, e-mail, telefone ou aleatória). |
| pix_key_typeobrigatório | string | cpf, cnpj, email, phone ou random. |
Exemplo
curl -X POST https://app.nexypay.com.br/api/c1/cashout/ \
-H "Content-Type: application/json" \
-d '{
"api-key": "sua_api_key_aqui",
"amount": 100.00,
"pix_key": "seuemail@example.com",
"pix_key_type": "email"
}'
<?php
$payload = [
'api-key' => 'sua_api_key_aqui',
'amount' => 100.00,
'pix_key' => 'seuemail@example.com',
'pix_key_type' => 'email',
];
$ch = curl_init('https://app.nexypay.com.br/api/c1/cashout/');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_TIMEOUT => 30,
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
print_r($data);
Consultar Status da Transação
Consulta o status atual de uma cobrança PIX. Recomendado apenas para verificações pontuais — para acompanhamento em tempo real, use webhooks.
api-key e a transação precisa pertencer ao seu merchant. Tentativas de consulta com chave inválida retornam 400 bad_request.Exemplo
curl -X POST https://app.nexypay.com.br/api/v1/webhook/ \
-H "Content-Type: application/json" \
-d '{
"api-key": "sua_api_key_aqui",
"idtransaction": "pv_69feca85b384e6.39636537"
}'
<?php
$payload = [
'api-key' => 'sua_api_key_aqui',
'idtransaction' => 'pv_69feca85b384e6.39636537',
];
$ch = curl_init('https://app.nexypay.com.br/api/v1/webhook/');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_TIMEOUT => 10,
]);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
// Sucesso: {"status":"PAID_OUT"} (pago)
// {"status":"WAITING_FOR_APPROVAL"} (ainda não pago)
// Erro: {"error":"bad_request"} (api-key inválida ou idTransaction não pertence ao seu merchant)
Notificação de Pagamento (Webhook)
Quando você inclui notification_url ao criar a cobrança, enviamos automaticamente uma requisição POST para sua URL assim que o pagamento é confirmado.
Payload enviado
{
"status": "PAID",
"idTransaction": "pv_69feca85b384e6.39636537",
"amount": 10.50,
"external_reference": null,
"paid_at": "2026-05-09 17:42:18"
}
status: "PAID" (curto). Já o endpoint de consulta retorna status: "PAID_OUT" (estado armazenado no banco). Trate ambos como "pagamento confirmado".Como tratar
<?php
// webhook.php — endpoint que recebe a notificação da NexyPay
$payload = json_decode(file_get_contents('php://input'), true);
if (!$payload || empty($payload['idTransaction'])) {
http_response_code(400);
exit;
}
$idTransaction = $payload['idTransaction'];
$status = $payload['status']; // "PAID" no webhook
$amount = $payload['amount'];
$externalRef = $payload['external_reference'] ?? null;
// IMPORTANTE: confirme com nossa API se o status é real
// (evita webhook forjado por terceiros)
$confirma = consultarStatus($idTransaction);
if ($confirma['status'] === 'PAID_OUT') {
// libera produto, envia email, marca pedido como pago, etc
liberarPedido($idTransaction, $externalRef);
}
http_response_code(200);
echo 'OK';
POST /api/v1/webhook/ para validar o status real.Retentativas e Idempotência
Se sua URL de webhook não responder com HTTP 2xx em até 10 segundos, tentaremos novamente seguindo a política:
- Tentativa 1: imediata
- Tentativa 2: após 1 minuto
- Tentativa 3: após 5 minutos
- Tentativa 4: após 30 minutos
- Tentativa 5: após 2 horas
Garanta que seu endpoint seja idempotente: receber o mesmo idtransaction múltiplas vezes não pode duplicar pedidos. Use o idtransaction como chave única.
Consultar Saldo
Retorna o saldo atual da conta — disponível pra saque, retido em disputas (MEDs) e total.
Autenticação
Aceita api-key em qualquer um destes formatos:
- Header
Authorization: Bearer SUA_API_KEY(recomendado) - Header
X-API-Key: SUA_API_KEY - Body JSON:
{"api-key": "SUA_API_KEY"}(se usar POST)
Exemplo de requisição
curl -X GET https://app.nexypay.com.br/api/v1/saldo/ \
-H "Authorization: Bearer SUA_API_KEY"
<?php
$ch = curl_init('https://app.nexypay.com.br/api/v1/saldo/');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer SUA_API_KEY'],
CURLOPT_TIMEOUT => 10,
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
echo "Disponível: R$ " . number_format($data['saldo'], 2, ',', '.') . PHP_EOL;
echo "Retido: R$ " . number_format($data['saldo_retido'], 2, ',', '.') . PHP_EOL;
echo "Total: R$ " . number_format($data['total'], 2, ',', '.') . PHP_EOL;
const fetch = require('node-fetch');
const response = await fetch('https://app.nexypay.com.br/api/v1/saldo/', {
headers: { 'Authorization': 'Bearer SUA_API_KEY' },
});
const data = await response.json();
console.log(`Disponível: R$ ${data.saldo.toFixed(2)}`);
console.log(`Retido: R$ ${data.saldo_retido.toFixed(2)}`);
console.log(`Total: R$ ${data.total.toFixed(2)}`);
import requests
r = requests.get(
"https://app.nexypay.com.br/api/v1/saldo/",
headers={"Authorization": "Bearer SUA_API_KEY"},
timeout=10,
)
data = r.json()
print(f"Disponível: R$ {data['saldo']:.2f}")
print(f"Retido: R$ {data['saldo_retido']:.2f}")
print(f"Total: R$ {data['total']:.2f}")
Resposta de sucesso
{
"status": "success",
"saldo": 1234.56,
"saldo_retido": 50.00,
"total": 1284.56,
"currency": "BRL",
"transacoes_aprovadas": 87,
"consulted_at": "2026-05-10T14:23:11+00:00"
}
•
saldo — valor disponível pra saque imediato•
saldo_retido — valor temporariamente bloqueado em disputas (MEDs em análise)•
total — soma dos dois (saldo bruto)•
transacoes_aprovadas — contador histórico de PIX recebidos
HTTP 429 com header Retry-After: 60.
Health Check
Endpoint público para verificar se a API está online.
curl https://app.nexypay.com.br/api/status/
# Resposta:
# {"status":"ok","timestamp":"2026-05-09T17:42:18Z"}
Status de Transação
Estados possíveis de uma transação PIX no nosso sistema:
| Status | Onde aparece | Significado |
|---|---|---|
| WAITING_FOR_APPROVAL | banco / consulta | Cobrança gerada, aguardando pagamento do cliente. |
| PAID_OUT | banco / consulta | Pagamento confirmado e creditado no seu saldo. |
| PAID | webhook | Versão curta enviada no payload do webhook (significa o mesmo que PAID_OUT). |
PAID (mais curto, padrão de mercado), o banco e a consulta direta usam PAID_OUT. Sempre trate ambos como pagamento confirmado.Códigos de Erro
| HTTP | Erro | Causa comum |
|---|---|---|
| 400 | bad_request | Payload inválido, campos obrigatórios faltando ou api-key incorreta. |
| 401 | unauthorized | API Key ausente ou inválida. |
| 403 | ip_not_allowed | IP de origem não está na sua allowlist do painel. |
| 404 | not_found | Recurso não encontrado. |
| 405 | method_not_allowed | Use POST nos endpoints documentados. |
| 429 | rate_limited | Você ultrapassou o limite de requisições. Aguarde antes de tentar novamente. |
| 500 | server_error | Erro interno. Tente novamente em alguns segundos. |
| 503 | service_unavailable | Adquirente ou banco indisponível temporariamente. |
| 504 | gateway_timeout | Adquirente PIX demorou pra responder. Pode tentar novamente. |
Rate Limits
Para proteger a plataforma de abuso, todos os endpoints têm rate limit baseado em IP e em api-key.
| Endpoint | Limite |
|---|---|
| POST /api/v1/gateway/ | 120 req/min por api-key |
| POST /api/c1/cashout/ | 30 req/min por api-key |
| POST /api/v1/webhook/ | 50 req/min por IP |
| GET /api/status/ | 600 req/min por IP |
Quando você ultrapassa o limite, retornamos 429 rate_limited com header Retry-After indicando quantos segundos aguardar.
SDKs e Bibliotecas
Atualmente disponibilizamos integração via REST direta. SDKs oficiais em PHP, Node.js e Python estão no nosso roadmap. Enquanto isso, os exemplos acima cobrem 95% dos casos de uso.
Suporte
Precisa de ajuda? Tire suas dúvidas com a comunidade ou fale direto com a equipe: