> ## 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.

# KYB Onboarding Status

> GET /v2/naas/submerchants/onboarding_status — check the current KYB status for an enrolled sub-merchant.

Returns the current KYB status for a sub-merchant's onboarding process. The response has the same shape as KYB webhook payloads, so you can use the same parsing code for both.

<Note>
  This endpoint requires only the `api-key` header — no signed envelope or `X-Signature`.
</Note>

## Query parameters

| Parameter        | Type          | Required | Description                                                             |
| ---------------- | ------------- | -------- | ----------------------------------------------------------------------- |
| `correlation_id` | string (UUID) | Yes      | The UUID returned by [Enroll Sub-merchant](/api-reference/naas/enroll). |

## Response `200 OK`

| Field        | Type   | Description                                                        |
| ------------ | ------ | ------------------------------------------------------------------ |
| `end2end`    | string | Process identifier for the KYB flow                                |
| `component`  | string | Always `kyb_caf_submerchant`                                       |
| `created_at` | string | ISO 8601 creation timestamp                                        |
| `status`     | string | High-level status (`Pending`, `Processing`, `Completed`, `Failed`) |
| `substatus`  | string | Detailed status label                                              |
| `process`    | string | Machine-readable state (see KYB States below)                      |
| `message`    | string | Human-readable description of the current state                    |

**`400`** — missing `correlation_id`.

**`401`** — invalid or missing `api-key`.

**`404`** — no onboarding process found for this correlation under your master account.

## KYB States

The `process` field maps to the following states:

| `process`                          | `status`   | `substatus`             | Description                                                              |
| ---------------------------------- | ---------- | ----------------------- | ------------------------------------------------------------------------ |
| `kyb_caf_submerchant.initial`      | Pending    | KYB Initiated           | Process started; creating CAF onboarding session                         |
| `kyb_caf_submerchant.pending_link` | Pending    | Awaiting KYB Completion | Onboarding link ready; waiting for sub-merchant to complete verification |
| `kyb_caf_submerchant.pending_kyb`  | Pending    | Under Review            | Documents submitted; CAF review in progress                              |
| `kyb_caf_submerchant.processing`   | Processing | KYB Approved            | CAF approved; provisioning merchant account                              |
| `kyb_caf_submerchant.done`         | Completed  | KYB Complete            | Sub-merchant fully onboarded and active                                  |
| `kyb_caf_submerchant.error`        | Failed     | KYB Error               | Verification failed; see `error_detail`                                  |

When `status` is `"Failed"`, the response also includes:

| Field              | Description                                                     |
| ------------------ | --------------------------------------------------------------- |
| `error_from_state` | The state the process was in when the error occurred            |
| `error_detail`     | Raw error message from the failed step                          |
| `error_message`    | Human-readable description suitable for displaying to end users |

## KYB Webhooks

When a `webhook` URL is provided in [POST /v2/naas/submerchants/onboarding\_link](/api-reference/naas/onboarding-link), Noxpay sends a signed `POST` to that URL on every KYB state change. The payload shape is identical to the status response above — you can use the same parsing code for both.

The webhook is signed with your NaaS webhook secret (configured at **NaaS → Setup → Webhook Secret**). See [NaaS Setup](/api-reference/naas/setup#webhook-verification) for signature verification details.

<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>