A NavePay expõe a API v2 com paths como /v2/oauth/token e /v2/pix/*, na raiz do host (não dentro de /api).

​
Fluxo de autenticação

  1. POST https://seu-dominio.com/v2/oauth/token com public_id e secret da chave de API:
    • HTTP Basic: usuário = public_id, senha = secret;
    • ou corpo JSON grant_type=client_credentials com public_id e secret (recomendado na NavePay).
  2. Resposta: access_token, token_type: Bearer, expires_in (segundos).
  3. Demais chamadas: Authorization: Bearer {access_token}.
Também são aceitos client_id e client_secret no corpo como alias do par public_id / secret (útil para clientes OAuth2 genéricos).

​
Limites (anti-abuso)

  • POST /v2/oauth/token tem rate limit por IP (padrão 20/min; limite configurável no servidor — veja .env.example).
  • As demais rotas /v2 são limitadas por access token (ou por IP se o header faltar), também configurável no .env.example.

​
Endpoints v2

MétodoPathDescrição
POST/v2/oauth/tokenObter access token
POST/v2/pix/qrcodeCobrança PIX (QR dinâmico)
POST/v2/pix/paymentEnvio PIX (saque)
POST/v2/pix/refundDevolução PIX (cash-in pago)
POST/v2/consult-transactionConsulta por pix_id
POST/v2/balanceSaldo (formato padrão v2)

​
Regras de negócio NavePay

  • Cash-in / cash-out usam o provedor de liquidação da plataforma, com carteira interna e taxas por integrador onde aplicável (v2 de saque e reembolso).
  • Respostas de sucesso dos endpoints PIX seguem o corpo retornado pelo provedor, no contrato v2.
Veja cada endpoint nas páginas seguintes.