Pix e dinheiro
| Termo | O que é |
|---|---|
| Pix | O meio de pagamento instantâneo do Banco Central. É o único meio da API pública da NyxPag |
| BR Code | O código do Pix em texto, o mesmo que o QR Code carrega |
| Copia e Cola | O BR Code em formato texto, para colar no app do banco. É o campo pix.copyPaste |
| QR Code | A imagem do BR Code. Vem em pix.qrCodeBase64, sem o prefixo data:image |
| Chave Pix | O endereço de quem recebe: CPF, CNPJ, e-mail, telefone ou chave aleatória |
| Cobrança | Uma operação de entrada: direction: "in" e type: "payment" |
| Transferência | Uma operação de saída: direction: "out" e type: "withdrawal" |
Tarifa (fee) | O que a NyxPag cobra pela operação. Depende da conta e vem em fee |
coverFee | Define quem paga a tarifa. Cobrança: false por padrão, e a tarifa sai do que você recebe. Transferência: true por padrão, e a tarifa sai do saldo além do valor enviado |
| Split | Divisão do valor de uma venda entre a sua conta e outras contas NyxPag |
| Saldo disponível | O que você pode usar agora (available) |
| Saldo reservado | O que é seu, mas ainda não está livre: transferências em andamento e reservas da conta (reserved) |
| MED | Mecanismo Especial de Devolução: a contestação de um Pix pelo pagador, que retém o valor durante a análise |
Valor líquido (netAmount) | O que sobra depois de tarifa e split |
Identificação e segurança
| Termo | O que é |
|---|---|
| API Key | A credencial da sua integração, no formato nyx_live_.... Vai no cabeçalho Authorization |
| Bearer | O esquema do cabeçalho: Authorization: Bearer nyx_live_... |
| Permissão | O que uma chave pode fazer: balance:read, payments:write, transactions:read, transfers:write |
| IP allowlist | Lista de IPs autorizados a usar uma chave. Fora dela, 403 ip_not_allowed |
| KYC | Verificação de identidade da conta. Sem ela, 403 kyc_required |
requestId | O protocolo de cada requisição. Aparece em toda resposta. Mande ao suporte |
| Segredo do webhook | A chave com que a NyxPag assina os webhooks. Mostrada uma vez no dashboard |
| Assinatura | Um HMAC-SHA256 de <timestamp>.<corpo bruto>, no cabeçalho X-NyxPag-Signature |
| HMAC-SHA256 | A função usada para assinar e conferir os webhooks |
Operação
| Termo | O que é |
|---|---|
| Idempotência | A propriedade de repetir uma requisição sem duplicar o efeito |
Idempotency-Key | Cabeçalho com a chave de idempotência, até 100 caracteres |
externalId | A mesma chave, no corpo. É salvo na transação e serve para consultar. Aceita letras, números e . _ : / - |
| Reconciliação | Dois sentidos: a NyxPag conferindo uma operação incerta (o 202), ou o seu job conferindo que o seu sistema bate com a NyxPag |
| Webhook | Um POST que a NyxPag envia ao seu servidor quando algo muda |
| Entrega | Cada tentativa de envio de um webhook. Tem um X-NyxPag-Delivery |
| Backoff | A espera crescente entre tentativas |
| Jitter | Um atraso aleatório somado ao backoff, para que clientes não repitam todos juntos |
| MCP | Model Context Protocol. O endpoint somente leitura para assistentes de IA |
Campos da transação
| Campo | O que é |
|---|---|
status | pending, approved, failed, cancelled ou refunded |
direction | in (entrada) ou out (saída) |
type | payment, deposit, withdrawal ou internal_transfer |
method | pix ou internal (entre contas NyxPag) |
expired | true quando a cobrança foi cancelada por passar de 15 minutos |
processingState | monitoring, reconciling ou completed |
amount | Cobrança: o que o pagador paga. Transferência: o que o destinatário recebe |
debitedAmount | Transferência: o que saiu do seu saldo |
splitAmount | O total descontado por split |
pix | O objeto com copyPaste e qrCodeBase64 |
expiresAt | O fim da validade de uma cobrança |
Cabeçalhos
| Cabeçalho | O que é |
|---|---|
Authorization | Envia a API Key |
Idempotency-Key | Envia a chave de idempotência |
Retry-After | No 429, quantos segundos esperar |
RateLimit-Limit | O limite da regra aplicada |
RateLimit-Remaining | Quantas requisições restam na janela |
RateLimit-Reset | Segundos até a janela reiniciar |
X-NyxPag-Version | A versão da API |
X-NyxPag-Signature | A assinatura do webhook, no formato t=<timestamp>,v1=<hex> |
X-NyxPag-Event | O nome do evento do webhook |
X-NyxPag-Delivery | O ID único de uma entrega de webhook |
Códigos importantes
| Código | O que é |
|---|---|
idempotency_conflict | 409: mesma chave, corpo diferente |
operation_refused | 422: uma regra de negócio impediu a operação |
rate_limit_exceeded | 429: passou de 100 requisições em 60 segundos |
WITHDRAWAL_IN_PROGRESS | 409: já existe uma transferência pendente |
Perguntas frequentes
Respostas rápidas para as dúvidas mais comuns.
Erros
O catálogo completo de códigos de erro.