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

# Link de Onboarding KYB

> POST /v2/naas/submerchants/onboarding_link — inicia o fluxo de verificação KYB para um sub-merchant cadastrado.

Inicia um fluxo de verificação KYB (Know Your Business) via CAF para um sub-merchant cadastrado. Retorna um identificador de processo `end2end` e a URL de onboarding da CAF.

<Warning>
  Este endpoint opera no nível do merchant master. **Não inclua `correlation_id` no envelope** — passe-o dentro do `payload` (veja abaixo).
</Warning>

## Campos do payload

| Campo            | Tipo          | Obrigatório | Descrição                                                                     |
| ---------------- | ------------- | ----------- | ----------------------------------------------------------------------------- |
| `correlation_id` | string (UUID) | Sim         | O UUID retornado por [Cadastrar Sub-merchant](/pt/api-reference/naas/enroll). |
| `webhook`        | string        | Não         | URL que recebe uma atualização de status a cada mudança de estado do KYB.     |

## Response `201 Created`

| Campo     | Tipo   | Descrição                                                   |
| --------- | ------ | ----------------------------------------------------------- |
| `end2end` | string | Identificador do processo KYB                               |
| `url`     | string | URL de onboarding da CAF — preenchida no momento da criação |

A `url` segue o formato `https://cadastro.io/{id}`. Se estiver vazia, use [GET /v2/naas/submerchants/onboarding\_status](/pt/api-reference/naas/onboarding-status) para consultar até que ela apareça.

**`400`** — `correlation_id` ausente ou vazio.

**`404`** — `correlation_id` não encontrado ou não pertence a este merchant master.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://checkout.noxpay.io/v2/naas/submerchants/onboarding_link \
    -H "api-key: <key>" \
    -H "X-Signature: <assinatura-do-corpo>" \
    -H "Content-Type: application/json" \
    -d '{
      "timestamp": "2026-05-25T14:30:00Z",
      "payload": {
        "correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001",
        "webhook": "https://yourserver.com/kyb-webhook"
      }
    }'
  ```

  ```python Python theme={null}
  import requests

  # correlation_id vai no payload, não no envelope
  body, sig = sign_envelope({
      "correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001",
      "webhook": "https://yourserver.com/kyb-webhook",
  })
  response = requests.post(
      "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_link",
      headers={"api-key": "<key>", "X-Signature": sig, "Content-Type": "application/json"},
      data=body,
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  // correlation_id vai no payload, não no envelope
  const { body, signature } = signEnvelope({
    correlation_id: "a1b2c3d4-e5f6-4789-abcd-000000000001",
    webhook: "https://yourserver.com/kyb-webhook",
  });
  const response = await fetch("https://checkout.noxpay.io/v2/naas/submerchants/onboarding_link", {
    method: "POST",
    headers: { "api-key": "<key>", "X-Signature": signature, "Content-Type": "application/json" },
    body,
  });
  const data = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "end2end": "NOX353CA9A97D8A4DA9A2999483077AB7C2",
    "url":     "https://cadastro.io/a1b2c3d4-e5f6-4789-abcd-000000000001"
  }
  ```

  ```json 404 theme={null}
  { "error": "correlation_id not found" }
  ```
</ResponseExample>