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 — Submerchant Management
Enroll Sub-merchant
POST /v2/naas/submerchants/enroll — register a new sub-merchant and receive the correlation_id UUID.
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
Permission object:
Available products:
Pass Response
Store the returned
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. |
| 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. |
| Code | Description |
|---|---|
crossramp_checkout | Crypto-to-BRL checkout links |
global_account | Fireblocks wallet management and withdrawals |
[{}] (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" }
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" }