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 viacorrelation_id.
URL base
/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.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 denaas_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 headerapi-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:
- Monte o envelope JSON com o timestamp UTC atual, opcionalmente o
correlation_id, e o payload do endpoint. - Serialize para bytes — não re-serialize após assinar.
- Calcule o SHA-256 dos bytes.
- Assine com sua chave privada RSA usando padding PKCS#1 v1.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.

