> ## Documentation Index
> Fetch the complete documentation index at: https://docs.noxpay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Status de Onboarding KYB

> GET /v2/naas/submerchants/onboarding_status — consulta o status atual do KYB para um sub-merchant cadastrado.

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.

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

## Parâmetros de query

| Parâmetro        | Tipo          | Obrigatório | Descrição                                                                     |
| ---------------- | ------------- | ----------- | ----------------------------------------------------------------------------- |
| `correlation_id` | string (UUID) | Sim         | O UUID retornado por [Cadastrar Sub-merchant](/pt/api-reference/naas/enroll). |

## 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](/pt/api-reference/naas/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](/pt/api-reference/naas/setup#verificação-de-webhook) para detalhes de verificação de assinatura.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status?correlation_id=a1b2c3d4-e5f6-4789-abcd-000000000001" \
    -H "api-key: <key>"
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript Node.js theme={null}
  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();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 (pending_link) theme={null}
  {
    "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"
  }
  ```

  ```json 200 (done) theme={null}
  {
    "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"
  }
  ```

  ```json 200 (error) theme={null}
  {
    "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"
  }
  ```

  ```json 404 theme={null}
  { "error": "Not Found" }
  ```
</ResponseExample>