Skip to main content

O que é o NaaS?

O Noxpay as a Service (NaaS) permite que um merchant master opere contas de sub-merchants de forma programática. Usando sua chave de API master junto com uma assinatura criptográfica, você pode cadastrar sub-merchants, iniciar onboarding KYB, criar links de checkout, gerenciar carteiras, iniciar saques e consultar splits — tudo vinculado a um sub-merchant específico via correlation_id.

URL base

Todos os endpoints NaaS estão sob o prefixo /v2/naas/.

Configuração de chave

1. Gerar um par de chaves RSA

A chave deve ter pelo menos 2048 bits. Recomendamos 4096 bits para chaves de longa duração.
O formato PKCS#1 de chave pública também é aceito:
Mantenha naas_private.pem em seus servidores e nunca a compartilhe. Apenas a chave pública é registrada na Noxpay.

2. Registrar a chave pública

No painel da Noxpay, acesse NaaS → Configuração → Chave Pública, cole o conteúdo de naas_public.pem e salve. A chave entra em vigor imediatamente. Você pode rotacioná-la a qualquer momento — a chave anterior é desativada automaticamente.

Autenticação

Toda requisição NaaS exige o header api-key. O mecanismo de autenticação difere pelo método HTTP:
  • Requisições POST carregam a autenticação no corpo da requisição como um envelope JSON assinado.
  • Requisições GET carregam a autenticação inteiramente em headers — nenhum corpo é enviado.

Requisições POST — envelope assinado

Todo corpo POST é um envelope JSON:
Para assinar a requisição:
  1. Monte o envelope JSON com o timestamp UTC atual, opcionalmente o correlation_id, e o payload do endpoint.
  2. Serialize para bytes — não re-serialize após assinar.
  3. Calcule o SHA-256 dos bytes.
  4. Assine com sua chave privada RSA usando padding PKCS#1 v1.5.
  5. Codifique o resultado em Base64 e envie como X-Signature.

Requisições GET — headers assinados

Endpoints GET não enviam corpo. Passe a autenticação em três headers adicionais: Para assinar a requisição, monte a string canônica <X-Timestamp>\n<X-Correlation-ID> — o valor exato de X-Timestamp, uma quebra de linha (\n), seguido do valor exato de X-Correlation-ID — assine o hash SHA-256 com sua chave RSA (PKCS#1 v1.5) e codifique o resultado em Base64 como X-Signature.

Proteção contra replay

Cada combinação (timestamp, correlation_id, signature) é tratada como um token de uso único. Sempre use o horário atual ao montar o envelope ou assinar headers — nunca reutilize uma requisição previamente assinada.

Verificação de webhook

Todos os webhooks do NaaS são assinados com HMAC-SHA256 usando seu segredo de webhook. A assinatura é entregue em dois headers: Verifique qualquer um dos headers — eles carregam o mesmo digest. Registre seu segredo de webhook em NaaS → Configuração → Segredo de Webhook. O segredo deve ter entre 32 e 512 caracteres imprimíveis, sem espaços.