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

# Cadastrar Sub-merchant

> POST /v2/naas/submerchants/enroll — registra um novo sub-merchant e retorna o UUID correlation_id.

Registra um novo sub-merchant sob o merchant master e retorna o `correlation_id` (UUID) que identifica o relacionamento. Este UUID é exigido por todos os outros endpoints NaaS que operam em nome do sub-merchant.

<Warning>
  Este endpoint opera no nível do merchant master. **Não inclua `correlation_id` no envelope** — omita esse campo completamente ao assinar.
</Warning>

## Campos do payload

| Campo          | Tipo    | Obrigatório | Descrição                                                                        |
| -------------- | ------- | ----------- | -------------------------------------------------------------------------------- |
| `tax_id`       | string  | Sim         | CNPJ do sub-merchant. Pontos, barras e hífens são removidos automaticamente.     |
| `legal_name`   | string  | Sim         | Razão social oficial.                                                            |
| `trade_name`   | string  | Não         | Nome fantasia ou marca.                                                          |
| `is_brazilian` | boolean | Sim         | `true` para empresas brasileiras, `false` para estrangeiras.                     |
| `split_pct`    | number  | Não         | Percentual de split padrão aplicado a todas as permissões, salvo override.       |
| `permissions`  | array   | Sim         | Pelo menos uma entrada. Um objeto vazio `{}` concede acesso a todos os produtos. |

**Objeto de permissão:**

| Campo          | Tipo   | Descrição                                                            |
| -------------- | ------ | -------------------------------------------------------------------- |
| `product_code` | string | Produto a habilitar. Omita para conceder acesso a todos os produtos. |
| `fee_pct`      | number | Override de taxa por entrada. Usa `split_pct` se omitido.            |

**Produtos disponíveis:**

| Código               | Descrição                                      |
| -------------------- | ---------------------------------------------- |
| `crossramp_checkout` | Links de checkout crypto-to-BRL                |
| `global_account`     | Gerenciamento de carteiras Fireblocks e saques |

Passe `[{}]` (um array com um objeto vazio) para conceder acesso a todos os produtos de uma vez, todos compartilhando o `split_pct` de nível superior.

## Response `201 Created`

```json theme={null}
{ "correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001" }
```

Guarde o `correlation_id` retornado — é o UUID usado em todas as chamadas NaaS subsequentes para este sub-merchant.

**`400`** — `tax_id`, `legal_name` ou `permissions` ausentes; ou `product_code` desconhecido.

**`409`** — o `tax_id` já está registrado como merchant master.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://checkout.noxpay.io/v2/naas/submerchants/enroll \
    -H "api-key: <key>" \
    -H "X-Signature: <assinatura-do-corpo>" \
    -H "Content-Type: application/json" \
    -d '{
      "timestamp": "2026-05-25T14:30:00Z",
      "payload": {
        "tax_id":       "30259965000164",
        "legal_name":   "Acme Pagamentos Ltda.",
        "trade_name":   "AcmePay",
        "is_brazilian": true,
        "split_pct":    1.5,
        "permissions": [
          { "product_code": "crossramp_checkout" },
          { "product_code": "global_account", "fee_pct": 0.5 }
        ]
      }
    }'
  ```

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

  # Sem correlation_id — omitir em sign_envelope
  body, sig = sign_envelope({
      "tax_id":       "30259965000164",
      "legal_name":   "Acme Pagamentos Ltda.",
      "trade_name":   "AcmePay",
      "is_brazilian": True,
      "split_pct":    1.5,
      "permissions":  [{"product_code": "crossramp_checkout"}, {"product_code": "global_account", "fee_pct": 0.5}],
  })
  response = requests.post(
      "https://checkout.noxpay.io/v2/naas/submerchants/enroll",
      headers={"api-key": "<key>", "X-Signature": sig, "Content-Type": "application/json"},
      data=body,
  )
  print(response.json())  # { "correlation_id": "a1b2c3d4-..." }
  ```

  ```javascript Node.js theme={null}
  // Sem correlationId — omitir em signEnvelope
  const { body, signature } = signEnvelope({
    tax_id:       "30259965000164",
    legal_name:   "Acme Pagamentos Ltda.",
    trade_name:   "AcmePay",
    is_brazilian: true,
    split_pct:    1.5,
    permissions:  [{ product_code: "crossramp_checkout" }, { product_code: "global_account", fee_pct: 0.5 }],
  });
  const response = await fetch("https://checkout.noxpay.io/v2/naas/submerchants/enroll", {
    method: "POST",
    headers: { "api-key": "<key>", "X-Signature": signature, "Content-Type": "application/json" },
    body,
  });
  const data = await response.json();
  // data.correlation_id → use este UUID em todas as chamadas subsequentes
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  { "correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001" }
  ```

  ```json 400 theme={null}
  { "error": "tax_id is required" }
  ```

  ```json 409 theme={null}
  { "error": "tax_id is already registered as a master merchant" }
  ```
</ResponseExample>