KYB Onboarding Status

curl -X GET "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status?correlation_id=a1b2c3d4-e5f6-4789-abcd-000000000001" \
  -H "api-key: <key>" \
  -H "X-Timestamp: 2026-05-27T14:30:00Z" \
  -H "X-Correlation-ID: a1b2c3d4-e5f6-4789-abcd-000000000001" \
  -H "X-Signature: <signed-headers-signature>"

import requests

headers = sign_get_headers(private_key, "a1b2c3d4-e5f6-4789-abcd-000000000001")
headers["api-key"] = "<key>"
response = requests.get(
    "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status",
    headers=headers,
    params={"correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001"},
)
print(response.json())

const headers = signGETHeaders("a1b2c3d4-e5f6-4789-abcd-000000000001");
headers["api-key"] = "<key>";
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 }
);
const data = await response.json();

{
  "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"
}

{
  "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"
}

{
  "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"
}

{ "error": "missing X-Timestamp" }

{ "error": "Not Found" }

curl -X GET "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status?correlation_id=a1b2c3d4-e5f6-4789-abcd-000000000001" \
  -H "api-key: <key>" \
  -H "X-Timestamp: 2026-05-27T14:30:00Z" \
  -H "X-Correlation-ID: a1b2c3d4-e5f6-4789-abcd-000000000001" \
  -H "X-Signature: <signed-headers-signature>"

import requests

headers = sign_get_headers(private_key, "a1b2c3d4-e5f6-4789-abcd-000000000001")
headers["api-key"] = "<key>"
response = requests.get(
    "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status",
    headers=headers,
    params={"correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001"},
)
print(response.json())

const headers = signGETHeaders("a1b2c3d4-e5f6-4789-abcd-000000000001");
headers["api-key"] = "<key>";
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 }
);
const data = await response.json();

{
  "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"
}

{
  "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"
}

{
  "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"
}

{ "error": "missing X-Timestamp" }

{ "error": "Not Found" }

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.

This endpoint requires signed headers. Send X-Timestamp, X-Correlation-ID, and X-Signature as described in GET requests — signed headers.

Headers

Header	Description
`api-key`	Your master merchant API key
`X-Timestamp`	RFC 3339 UTC timestamp. Requests outside ±1 minute are rejected.
`X-Correlation-ID`	UUID of the master–sub-merchant relationship
`X-Signature`	Base64-encoded RSA-PKCS1v15-SHA256 signature of the canonical string `<X-Timestamp>\n<X-Correlation-ID>`

Query parameters

Parameter	Type	Required	Description
`correlation_id`	string (UUID)	Yes	The UUID returned by Enroll Sub-merchant.

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, or missing/invalid signature header (e.g. {"error": "missing X-Timestamp"}). 401 — invalid or missing api-key, or X-Signature fails verification. 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, 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 for signature verification details.

curl -X GET "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status?correlation_id=a1b2c3d4-e5f6-4789-abcd-000000000001" \
  -H "api-key: <key>" \
  -H "X-Timestamp: 2026-05-27T14:30:00Z" \
  -H "X-Correlation-ID: a1b2c3d4-e5f6-4789-abcd-000000000001" \
  -H "X-Signature: <signed-headers-signature>"

import requests

headers = sign_get_headers(private_key, "a1b2c3d4-e5f6-4789-abcd-000000000001")
headers["api-key"] = "<key>"
response = requests.get(
    "https://checkout.noxpay.io/v2/naas/submerchants/onboarding_status",
    headers=headers,
    params={"correlation_id": "a1b2c3d4-e5f6-4789-abcd-000000000001"},
)
print(response.json())

const headers = signGETHeaders("a1b2c3d4-e5f6-4789-abcd-000000000001");
headers["api-key"] = "<key>";
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 }
);
const data = await response.json();

{
  "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"
}

{
  "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"
}

{
  "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"
}

{ "error": "missing X-Timestamp" }

{ "error": "Not Found" }

Getting Started

Global Account

Crossramp Checkout

Conversions

Noxpay Infra

NaaS — Setup

NaaS — Submerchant Management

NaaS — Crossramp Checkout

NaaS — Global Account

NaaS — Splits

Reference

KYB Onboarding Status

Headers

Query parameters

Response `200 OK`

KYB States

KYB Webhooks

​Headers

​Query parameters

​Response 200 OK

​KYB States

​KYB Webhooks

Headers

Query parameters

Response `200 OK`

KYB States

KYB Webhooks