Enroll Sub-merchant

curl -X POST https://checkout.noxpay.io/v2/naas/submerchants/enroll \
  -H "api-key: <key>" \
  -H "X-Signature: <signed-body-signature>" \
  -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 }
      ]
    }
  }'

import requests

# No correlation_id — omit it from 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-..." }

// No correlationId — omit it from 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 this UUID for all subsequent calls

{ "correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001" }

{ "error": "tax_id is required" }

{ "error": "tax_id is already registered as a master merchant" }

curl -X POST https://checkout.noxpay.io/v2/naas/submerchants/enroll \
  -H "api-key: <key>" \
  -H "X-Signature: <signed-body-signature>" \
  -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 }
      ]
    }
  }'

import requests

# No correlation_id — omit it from 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-..." }

// No correlationId — omit it from 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 this UUID for all subsequent calls

{ "correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001" }

{ "error": "tax_id is required" }

{ "error": "tax_id is already registered as a master merchant" }

Registers a new sub-merchant under the master merchant and returns the correlation_id (UUID) that identifies the relationship. This UUID is required by all other NaaS endpoints that operate on behalf of the sub-merchant.

This endpoint operates at the master merchant level. Do not include correlation_id in the envelope — omit that field entirely when signing.

Payload fields

Field	Type	Required	Description
`tax_id`	string	Yes	Sub-merchant CNPJ. Dots, slashes, and dashes are stripped automatically.
`legal_name`	string	Yes	Official company name.
`trade_name`	string	No	Trade or brand name.
`is_brazilian`	boolean	Yes	`true` for Brazilian companies, `false` for foreign.
`split_pct`	number	No	Default split percentage applied to all permissions unless overridden.
`permissions`	array	Yes	At least one entry. An empty object `{}` grants access to all products.

Permission object:

Field	Type	Description
`product_code`	string	Product to enable. Omit to grant access to all products.
`fee_pct`	number	Per-entry fee override. Falls back to `split_pct` if omitted.

Available products:

Code	Description
`crossramp_checkout`	Crypto-to-BRL checkout links
`global_account`	Fireblocks wallet management and withdrawals

Pass [{}] (an array with one empty object) to grant access to all products at once, all sharing the top-level split_pct.

Response `201 Created`

{ "correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001" }

Store the returned correlation_id — it is the UUID used in all subsequent NaaS calls for this sub-merchant. 400 — missing tax_id, legal_name, or permissions; or unknown product_code. 409 — the tax_id is already registered as a master merchant.

curl -X POST https://checkout.noxpay.io/v2/naas/submerchants/enroll \
  -H "api-key: <key>" \
  -H "X-Signature: <signed-body-signature>" \
  -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 }
      ]
    }
  }'

import requests

# No correlation_id — omit it from 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-..." }

// No correlationId — omit it from 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 this UUID for all subsequent calls

{ "correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001" }

{ "error": "tax_id is required" }

{ "error": "tax_id is already registered as a master merchant" }

NaaS — Authentication & Setup KYB Onboarding Link

​Payload fields

​Response 201 Created

Payload fields

Response `201 Created`