🛡️ NexusPay — Guia Técnico de Integração
Base: https://pay.nxschain.com/api
SANDBOX
Receba em USDT-N · D+0
Como funciona (3 passos)
1 · Crie a ordem
POST /v1/pix com o valor em US$. O motor devolve o Pix (copia-e-cola/QR) com o total em R$ já incluindo a taxa da rota, discriminada.
2 · Cliente paga no banco
Pagamento Pix real (fase prod: QR do provedor licenciado). O motor detecta o pagamento e dispara o sweep: USDT depositado no Vault com recipient = carteira NEXUS do lojista.
3 · Você recebe em USDT-N
Status vira PAID (polling ou webhook). O relayer cunha o USDT-N na carteira do lojista (~40s em prod). Liquidação D+0, sem chargeback.
Alternativa crypto
Cliente com carteira: POST /v1/orders paga em USDT-N (1,8%) ou NXS (0,5%) direto no contrato — confirmação on-chain em ~3s. O gateway também avisa seu sistema via webhook.
Autenticação do lojista (toda chamada)
X-Nexus-Api-Key sua apiKey (identifica o lojista)
X-Nexus-Timestamp epoch em ms (janela ±300s — anti-replay)
X-Nexus-Signature HMAC-SHA256(secretKey, ts:METODO:path:sha256(body))
GET sem corpo: sha256(body) = sha256("") (constante)
Query string: NÃO entra na assinatura (path sem "?")
Regra de ouro: apiKey/secretKey vivem no servidor da loja (backend/ERP), nunca no JavaScript do site público. Em produção, quem assina é o seu backend — o navegador nunca vê a secretKey.
Endpoints
| Método / rota | Autenticação | Descrição |
|---|
POST /v1/pix
body: {"amountUSD": 25} | HMAC lojista | Cria ordem Pix. Retorna id, amountUSD, feeUSD (rota), totalUSD, totalBRL (cliente paga), status:"PENDING", copyPaste. |
GET /v1/pix/:id | — (sandbox) | Polling de status: PENDING → PAID (com paidAt). Intervalo sugerido: 3 s. |
POST /v1/pix/webhook | Header X-Pix-Secret | Chamado pelo provedor Pix (ou operador, no sandbox) com {"id","status":"PAID"}. Marca PAID e registra o sweep p/ o Vault com recipient=lojista. Resposta: {ok, orderId, sweep:{step,recipient,amountUSD}}. Replays não duplicam (idempotente). |
GET /v1/pix/info | público | Modo (sandbox/prod), taxa da rota (feeBps), câmbio BRL/USD. |
POST /v1/orders | HMAC lojista | Ordem crypto (USDT-N/NXS) para checkout com carteira — mesmo padrão do PDV. |
GET /v1/merchant/profile | HMAC lojista | Perfil: endereço on-chain, nome, taxas (feeBpsToken 180 = 1,8%; feeBpsNative 50 = 0,5%), webhookUrl. |
GET /v1/merchant/orders | HMAC lojista | Histórico de ordens (status, valores, tx). Filtros: ?status=&limit=. |
PUT /v1/merchant/webhook | HMAC lojista | Configura {"webhookUrl","webhookSecret"} — o motor passa a avisar SEU sistema a cada pagamento (retries exponenciais; replay no /admin). |
Webhook de retorno (motor → seu sistema)
POSTna sua webhookUrl, corpo assinado:
Headers: X-Nexus-Signature = HMAC-SHA256(webhookSecret, corpo_bruto)
X-Nexus-Timestamp | X-Nexus-Event-Id = orderId
Body: {"event":"order.paid","orderId":"…","merchant":"0x…","token":"0x…",
"amount":"…(wei)","paidAmount":"…(wei)","fee":"…(wei)","net":"…(wei)",
"txHash":"0x…","payer":"0x…","timestamp":…}
Verificação obrigatória: recalcule o HMAC com o corpo recebido e compare (timing-safe). Responda 2xx para confirmar; sem 2xx o motor re-tenta com backoff exponencial.
Taxas exibidas ao cliente (transparência híbrida)
| Meio | Taxa | Na prática |
|---|
| Pix (rota on-ramp) | 2,0% | Discriminada: venda US$ 25,00 → +US$ 0,50 rota → total US$ 25,50 → cliente paga R$ 127,50 (câmbio R$ 5,00/US$, sandbox). Você recebe os US$ 25,00 integrais em USDT-N. |
| USDT-N (carteira) | 1,8% | Incentivo: sai mais barato que o Pix → banner no checkout. |
| NXS (carteira) | 0,5% | Menor taxa da rede. |
Sandbox vs produção
Hoje (sandbox — este guia)
- Pix de demonstração (copia-e-cola mock; QR renderizável)
- Confirmação via
POST /v1/pix/webhook com o secret do sandbox (quem opera o teste)
- Ordens em memória (reiniciam no reboot)
- Contrato de API definitivo — nada muda na fase prod
Produção (próxima fase)
- QR Pix real do provedor licenciado (Transak/Alter/Bitybank/Coinext) + KYC
- Callback assinado automático → sweep real na BSC → relayer cunha USDT-N (~40 s)
- Ordens persistidas + reconciliação
Ambientes e contato
Ambiente sandbox: https://pay.nxschain.com/api · modo sandbox (confirme via GET /v1/pix/info).
Demo ao vivo: https://pay.nxschain.com/checkout-demo · Suporte: suporte@inovatrek.com.br · WhatsApp (21) 99459-1338