curl -X GET "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status?correlation_id=a1b2c3d4-e5f6-4789-abcd-000000000001" \
-H "api-key: <key>" \
-H "X-Timestamp: 2026-05-27T14:30:00Z" \
-H "X-Correlation-ID: a1b2c3d4-e5f6-4789-abcd-000000000001" \
-H "X-Signature: <assinatura-dos-headers>"
import requests
# Headers assinados
headers = sign_get_headers(private_key, "a1b2c3d4-e5f6-4789-abcd-000000000001")
headers["api-key"] = "<key>"
response = requests.get(
"https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status",
headers=headers,
params={"correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001"},
)
print(response.json())
// Headers assinados
const headers = signGETHeaders("a1b2c3d4-e5f6-4789-abcd-000000000001");
headers["api-key"] = "<key>";
const params = new URLSearchParams({
correlation_id: "a1b2c3d4-e5f6-4789-abcd-000000000001",
});
const response = await fetch(
`https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status?${params}`,
{ headers }
);
const data = await response.json();
{
"end2end": "NOX353CA9A97D8A4DA9A2999483077AB7C2",
"component": "kyb_caf_submerchant",
"created_at": "2026-05-25T14:30:00Z",
"status": "Pending",
"substatus": "Awaiting KYB Completion",
"process": "kyb_caf_submerchant.pending_link",
"message": "Onboarding link sent; waiting for submerchant to complete identity verification"
}
{
"end2end": "NOX353CA9A97D8A4DA9A2999483077AB7C2",
"component": "kyb_caf_submerchant",
"created_at": "2026-05-25T14:30:00Z",
"status": "Completed",
"substatus": "KYB Complete",
"process": "kyb_caf_submerchant.done",
"message": "KYB verification complete; submerchant fully onboarded"
}
{
"end2end": "NOX353CA9A97D8A4DA9A2999483077AB7C2",
"component": "kyb_caf_submerchant",
"created_at": "2026-05-25T14:30:00Z",
"status": "Failed",
"substatus": "KYB Error",
"process": "kyb_caf_submerchant.error",
"message": "An error occurred during KYB verification",
"error_message": "KYB could not be completed. Please contact support.",
"error_from_state": "PENDING_KYB",
"error_detail": "CAF: transaction not found"
}
{ "error": "missing X-Timestamp" }
{ "error": "Not Found" }
NaaS — Gestão de Sub-merchants
Status de Onboarding KYB
GET /v2/naas/submerchants/onboarding_status — consulta o status atual do KYB para um sub-merchant cadastrado.
curl -X GET "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status?correlation_id=a1b2c3d4-e5f6-4789-abcd-000000000001" \
-H "api-key: <key>" \
-H "X-Timestamp: 2026-05-27T14:30:00Z" \
-H "X-Correlation-ID: a1b2c3d4-e5f6-4789-abcd-000000000001" \
-H "X-Signature: <assinatura-dos-headers>"
import requests
# Headers assinados
headers = sign_get_headers(private_key, "a1b2c3d4-e5f6-4789-abcd-000000000001")
headers["api-key"] = "<key>"
response = requests.get(
"https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status",
headers=headers,
params={"correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001"},
)
print(response.json())
// Headers assinados
const headers = signGETHeaders("a1b2c3d4-e5f6-4789-abcd-000000000001");
headers["api-key"] = "<key>";
const params = new URLSearchParams({
correlation_id: "a1b2c3d4-e5f6-4789-abcd-000000000001",
});
const response = await fetch(
`https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status?${params}`,
{ headers }
);
const data = await response.json();
{
"end2end": "NOX353CA9A97D8A4DA9A2999483077AB7C2",
"component": "kyb_caf_submerchant",
"created_at": "2026-05-25T14:30:00Z",
"status": "Pending",
"substatus": "Awaiting KYB Completion",
"process": "kyb_caf_submerchant.pending_link",
"message": "Onboarding link sent; waiting for submerchant to complete identity verification"
}
{
"end2end": "NOX353CA9A97D8A4DA9A2999483077AB7C2",
"component": "kyb_caf_submerchant",
"created_at": "2026-05-25T14:30:00Z",
"status": "Completed",
"substatus": "KYB Complete",
"process": "kyb_caf_submerchant.done",
"message": "KYB verification complete; submerchant fully onboarded"
}
{
"end2end": "NOX353CA9A97D8A4DA9A2999483077AB7C2",
"component": "kyb_caf_submerchant",
"created_at": "2026-05-25T14:30:00Z",
"status": "Failed",
"substatus": "KYB Error",
"process": "kyb_caf_submerchant.error",
"message": "An error occurred during KYB verification",
"error_message": "KYB could not be completed. Please contact support.",
"error_from_state": "PENDING_KYB",
"error_detail": "CAF: transaction not found"
}
{ "error": "missing X-Timestamp" }
{ "error": "Not Found" }
Retorna o status atual do KYB de um sub-merchant. O formato do response é idêntico ao payload do webhook KYB — você pode usar o mesmo código de parsing para os dois.
Response
Quando
Este endpoint exige headers assinados. Envie
X-Timestamp, X-Correlation-ID e X-Signature, conforme descrito em Requisições GET — headers assinados.Headers
| Header | Descrição |
|---|---|
api-key | Sua chave de API do merchant master |
X-Timestamp | Timestamp UTC no formato RFC 3339. Requisições fora de ±1 minuto são rejeitadas. |
X-Correlation-ID | UUID do relacionamento master–sub-merchant |
X-Signature | Assinatura RSA-PKCS1v15-SHA256 da string canônica <X-Timestamp>\n<X-Correlation-ID>, codificada em Base64 |
Parâmetros de query
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
correlation_id | string (UUID) | Sim | O UUID retornado por Cadastrar Sub-merchant. |
Response 200 OK
| Campo | Tipo | Descrição |
|---|---|---|
end2end | string | Identificador do processo KYB |
component | string | Sempre kyb_caf_submerchant |
created_at | string | Timestamp ISO 8601 de criação |
status | string | Status de alto nível (Pending, Processing, Completed, Failed) |
substatus | string | Rótulo de status detalhado |
process | string | Estado legível por máquina (ver Estados do KYB abaixo) |
message | string | Descrição legível do estado atual |
400 — correlation_id ausente, ou header de assinatura ausente/inválido (ex.: {"error": "missing X-Timestamp"}).
401 — api-key inválida ou ausente, ou X-Signature não confere.
404 — nenhum processo de onboarding encontrado para este correlation na sua conta master.
Estados do KYB
O campoprocess mapeia para os seguintes estados:
process | status | substatus | Descrição |
|---|---|---|---|
kyb_caf_submerchant.initial | Pending | KYB Initiated | Processo iniciado; criando sessão de onboarding na CAF |
kyb_caf_submerchant.pending_link | Pending | Awaiting KYB Completion | Link de onboarding pronto; aguardando o sub-merchant concluir a verificação |
kyb_caf_submerchant.pending_kyb | Pending | Under Review | Documentos enviados; revisão CAF em andamento |
kyb_caf_submerchant.processing | Processing | KYB Approved | CAF aprovou; provisionando conta do merchant |
kyb_caf_submerchant.done | Completed | KYB Complete | Sub-merchant totalmente onboardado e ativo |
kyb_caf_submerchant.error | Failed | KYB Error | Verificação falhou; consulte error_detail |
status é "Failed", o response também inclui:
| Campo | Descrição |
|---|---|
error_from_state | O estado em que o processo estava quando o erro ocorreu |
error_detail | Mensagem de erro bruta da etapa com falha |
error_message | Descrição legível adequada para exibição ao usuário final |
Webhooks do KYB
Quando uma URLwebhook é fornecida em POST /v2/naas/submerchants/onboarding_link, a Noxpay envia um POST assinado para essa URL a cada mudança de estado do KYB. O formato do payload é idêntico ao response de status acima.
O webhook é assinado com seu segredo de webhook do NaaS (configurado em NaaS → Configuração → Segredo de Webhook). Consulte Configuração do NaaS para detalhes de verificação de assinatura.
curl -X GET "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status?correlation_id=a1b2c3d4-e5f6-4789-abcd-000000000001" \
-H "api-key: <key>" \
-H "X-Timestamp: 2026-05-27T14:30:00Z" \
-H "X-Correlation-ID: a1b2c3d4-e5f6-4789-abcd-000000000001" \
-H "X-Signature: <assinatura-dos-headers>"
import requests
# Headers assinados
headers = sign_get_headers(private_key, "a1b2c3d4-e5f6-4789-abcd-000000000001")
headers["api-key"] = "<key>"
response = requests.get(
"https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status",
headers=headers,
params={"correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001"},
)
print(response.json())
// Headers assinados
const headers = signGETHeaders("a1b2c3d4-e5f6-4789-abcd-000000000001");
headers["api-key"] = "<key>";
const params = new URLSearchParams({
correlation_id: "a1b2c3d4-e5f6-4789-abcd-000000000001",
});
const response = await fetch(
`https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status?${params}`,
{ headers }
);
const data = await response.json();
{
"end2end": "NOX353CA9A97D8A4DA9A2999483077AB7C2",
"component": "kyb_caf_submerchant",
"created_at": "2026-05-25T14:30:00Z",
"status": "Pending",
"substatus": "Awaiting KYB Completion",
"process": "kyb_caf_submerchant.pending_link",
"message": "Onboarding link sent; waiting for submerchant to complete identity verification"
}
{
"end2end": "NOX353CA9A97D8A4DA9A2999483077AB7C2",
"component": "kyb_caf_submerchant",
"created_at": "2026-05-25T14:30:00Z",
"status": "Completed",
"substatus": "KYB Complete",
"process": "kyb_caf_submerchant.done",
"message": "KYB verification complete; submerchant fully onboarded"
}
{
"end2end": "NOX353CA9A97D8A4DA9A2999483077AB7C2",
"component": "kyb_caf_submerchant",
"created_at": "2026-05-25T14:30:00Z",
"status": "Failed",
"substatus": "KYB Error",
"process": "kyb_caf_submerchant.error",
"message": "An error occurred during KYB verification",
"error_message": "KYB could not be completed. Please contact support.",
"error_from_state": "PENDING_KYB",
"error_detail": "CAF: transaction not found"
}
{ "error": "missing X-Timestamp" }
{ "error": "Not Found" }