Acessar Painel →

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.

REST + JSON Status real-time HTTPS + TLS 1.3 Webhooks confiáveis

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.

Mantenha sua API Key secreta. Nunca a inclua em código frontend, repositórios públicos ou compartilhe por canais não seguros. Se vazar, regenere imediatamente no painel.

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 POST para a notification_url que você cadastrou.
Você também pode consultar o status manualmente via 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.

POST https://app.nexypay.com.br/api/v1/gateway/

Parâmetros

CampoTipoDescrição
api-keyobrigatóriostringSua chave de API.
amountobrigatórionumberValor da cobrança em reais (ex.: 10.50).
methodobrigatóriostringMétodo de pagamento. Use "pix".
clientobrigatórioobjectDados do pagador. Ver tabela abaixo.
notification_urlopcionalstringURL HTTPS para receber webhook de pagamento.

Objeto client

CampoTipoDescrição
nameobrigatóriostringNome completo do pagador.
documentobrigatóriostringCPF ou CNPJ (apenas dígitos).
emailopcionalstringE-mail do pagador.
telefoneopcionalstringTelefone 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..."
}
Campos retornados:
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.

POST https://app.nexypay.com.br/api/c1/cashout/

Parâmetros

CampoTipoDescrição
api-keyobrigatóriostringSua chave de API.
amountobrigatórionumberValor a sacar em reais.
pix_keyobrigatóriostringChave PIX destino (CPF, CNPJ, e-mail, telefone ou aleatória).
pix_key_typeobrigatóriostringcpf, 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.

POST https://app.nexypay.com.br/api/v1/webhook/
Este endpoint exige 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"
}
Atenção: o webhook envia 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';
Sempre confirme o status via consulta direta. Webhooks podem ser falsificados por terceiros que conhecem sua URL. Antes de liberar produto, faça 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.

GET https://app.nexypay.com.br/api/v1/saldo/

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"
}
O que cada campo significa:
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
Rate limit: 60 consultas por minuto por API key. Se ultrapassar, retornamos HTTP 429 com header Retry-After: 60.

Health Check

Endpoint público para verificar se a API está online.

GET https://app.nexypay.com.br/api/status/
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:

StatusOnde apareceSignificado
WAITING_FOR_APPROVAL banco / consulta Cobrança gerada, aguardando pagamento do cliente.
banco / consulta Pagamento confirmado e creditado no seu saldo.
webhook Versão curta enviada no payload do webhook (significa o mesmo que PAID_OUT).
Por que dois nomes para o mesmo estado? O webhook usa 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

HTTPErroCausa comum
400bad_requestPayload inválido, campos obrigatórios faltando ou api-key incorreta.
401unauthorizedAPI Key ausente ou inválida.
403ip_not_allowedIP de origem não está na sua allowlist do painel.
404not_foundRecurso não encontrado.
405method_not_allowedUse POST nos endpoints documentados.
429rate_limitedVocê ultrapassou o limite de requisições. Aguarde antes de tentar novamente.
500server_errorErro interno. Tente novamente em alguns segundos.
503service_unavailableAdquirente ou banco indisponível temporariamente.
504gateway_timeoutAdquirente 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.

EndpointLimite
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.

Quer contribuir com um SDK na sua linguagem? Entre em contato pelo Discord oficial — damos crédito + bônus na taxa.

Suporte

Precisa de ajuda? Tire suas dúvidas com a comunidade ou fale direto com a equipe: