Status de Onboarding KYB

curl -X GET "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status?correlation_id=a1b2c3d4-e5f6-4789-abcd-000000000001" \
  -H "api-key: <key>"

import requests

response = requests.get(
    "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status",
    headers={"api-key": "<key>"},
    params={"correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001"},
)
print(response.json())

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: { "api-key": "<key>" } }
);
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": "Not Found" }

curl -X GET "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status?correlation_id=a1b2c3d4-e5f6-4789-abcd-000000000001" \
  -H "api-key: <key>"

import requests

response = requests.get(
    "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status",
    headers={"api-key": "<key>"},
    params={"correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001"},
)
print(response.json())

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: { "api-key": "<key>" } }
);
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": "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.

Este endpoint requer apenas o header api-key — não há envelope assinado nem X-Signature.

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. 401 — api-key inválida ou ausente. 404 — nenhum processo de onboarding encontrado para este correlation na sua conta master.

Estados do KYB

O campo process 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`

Quando 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 URL webhook é 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>"

import requests

response = requests.get(
    "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status",
    headers={"api-key": "<key>"},
    params={"correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001"},
)
print(response.json())

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: { "api-key": "<key>" } }
);
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": "Not Found" }

Link de Onboarding KYB Atualizar Branding

​Parâmetros de query

​Response 200 OK

​Estados do KYB

​Webhooks do KYB

Parâmetros de query

Response `200 OK`

Estados do KYB

Webhooks do KYB