Business and merchant verification (KYB and KYM)

KYB (know your business) and KYM (know your merchant) extend hosted verification from people to businesses and merchants. Your server creates a one-shot link, the business or merchant completes onboarding on a Noxtica page, and your operators review the case in Backoffice. A backend engineer creates the sessions, and a Backoffice administrator follows them.

What it is

Availability: In development. Business and merchant verification is not generally open, and nothing on this page is a commitment on scope, availability or date. Whether the calls and Backoffice pages below work for your organisation depends on your organisation; ask your account team. When it is not available, Backoffice shows “KYB is not available for this workspace yet.” or “Merchant verification (KYM) is not available for this workspace yet.”, and the API answers 404 with V1 endpoint not found.

• KYB is hosted business onboarding. The business representative enters business information, uploads documents, declares owners, reviews and submits. A submitted session goes to human review in Backoffice. This page describes no automated business-registry check.
• KYM is hosted merchant onboarding plus notify-only transaction monitoring. The merchant enters a profile, uploads documents, accepts a declaration, reviews and submits. Your server can also report transactions, which feed alert rules. An alert is a notification for a person to review. It never starts a payment action.

Both hosted pages open as a full page. They cannot be embedded in an iframe. Results are signals: your operators decide, and Backoffice keeps the case and its notes.

Prerequisites

• Confirmation from your account team that KYB or KYM is enabled for your organisation. Without it, every call below answers 404.
• A Backoffice user with the administrator role for the KYB and KYM pages. Changes ask for fresh step-up verification (MFA).
• A server key with the right permission: “Verify identity documents (KYC)” for KYB, and “Manage KYM merchant onboarding sessions and transactions” for KYM. Create it in Backoffice → API & SDK → Server API Keys. The secret is shown once. Server keys start with sk_prod_. Keep the key on your server.
• The hosted verification service configured for your environment. If it is not, session creation answers 503 hosted_verify_not_configured.
• For events: an endpoint registered as in Identity verification events and webhooks.

Steps

1. Create a KYB session

POST https://collect.noxtica.com/v1/kyb/sessions
Authorization: Bearer sk_prod_your_server_key
Content-Type: application/json

The body is a JSON object and can be {}. Every field is optional, and the business can fill in the real details on the hosted page. Snake_case names such as legal_name are accepted too.

curl -sS https://collect.noxtica.com/v1/kyb/sessions \
  -H "Authorization: Bearer $NOXTICA_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"legalName":"Example Co","countryOfIncorporation":"GB","entityKind":"company"}'

A new session returns 200:

{
  "ok": true,
  "sessionId": "<uuid>",
  "url": "https://verify.noxtica.com/b/<token>",
  "expiresAt": 1790848845000,
  "requestId": "<request-id>"
}

url is a one-shot link that carries the access token. It is returned once, in this response, and no later call returns it. Treat it as a secret and do not log it. expiresAt is in epoch milliseconds.

2. Create a KYM session

POST https://collect.noxtica.com/v1/kym/sessions
Authorization: Bearer sk_prod_your_server_key
Content-Type: application/json

The response has the same shape as the KYB response, with a url that starts https://verify.noxtica.com/m/. KYB requires an uppercase country code, and KYM accepts either case.

3. Send the link and follow the session in Backoffice

Send the one-shot url to the business representative or merchant by redirect, email or QR code, as in Identity verification integration. Store the sessionId.

These sessions have no server-side status read like the one for identity sessions. Follow them in Backoffice (the KYB hub is at /kyb and the KYM hub at /kym), or use events:

On the two sessions pages, the “Just started — one-time link” table shows a new link once, with “Copy link”, “Open hosted page”, “QR code” and “Live status”. It is not saved anywhere. “Create test session” starts a one-hour session with no real customer data. Its name begins “TEST session ”.

4. Report merchant transactions (KYM)

Report one observed transaction for a merchant case that already exists. Take the caseId from the “Case” column on KYM Sessions or from Merchant Cases.

POST https://collect.noxtica.com/v1/kym/transactions
Authorization: Bearer sk_prod_your_server_key
Content-Type: application/json

{
  "caseId": "<case-id>",
  "idempotencyKey": "txn-0001",
  "amountMinor": 1000,
  "currency": "EUR",
  "occurredAt": "2026-10-27T09:30:00Z",
  "counterpartyRef": "cp_example"
}

A new row returns 201 with {"ok": true, "eventId": "<id>", "deduplicated": false, "requestId": "<request-id>"}. A repeat returns 200 with "deduplicated": true. The body can be at most 4096 bytes. The call only records the event for alert rules. It starts no payment.

5. Subscribe to events

Register an endpoint and tick the labels below under “Events to deliver” in Backoffice → Integrations & API → Webhooks. Signatures, headers and deduplication work as for identity events.

The data objects carry no names, registration numbers or party details:

{
  "id": "<deliveryId>",
  "type": "kyb.entity.under_review",
  "created_at": 1790762445000,
  "tenant_id": "<tenant-id>",
  "data": {
    "schemaVersion": "1",
    "entityId": "<entity-id>",
    "status": "under_review",
    "occurredAt": 1790762445000,
    "deliveryId": "<deliveryId>"
  }
}

These events are notifications, not decisions. Business and merchant events are not part of the identity delivery log, and Noxtica publishes no retry schedule for them. kym.* events are attempted once. Plan for a missed event: open the entity or case in Backoffice to see its current state.

Verify it works

1. In Backoffice, open KYB → KYB Sessions (or KYM → KYM Sessions) and select “Create test session”. A row appears under “Just started — one-time link”. If you see “KYB is not available for this workspace yet.”, the module is not enabled.
2. Select “Open hosted page”, or scan the QR code, and walk through the steps.
3. Select “Live status” on the row. It shows the status and the step and refreshes by itself while the panel is open.
4. Call the create endpoint with your server key. A 200 response with sessionId, url and expiresAt means the module, the key and the hosted service are all in place.
5. After the session is submitted, find the entity under KYB Entities or the case under Merchant Cases.

Troubleshooting

Related

• Identity verification events and webhooks — register an endpoint and verify signatures.
• Identity verification integration — the same hosted-link pattern for individuals.
• Identity verification data — Noxtica does not delete verification details or evidence automatically, and an administrator removes them.
• Identity verification FAQ and troubleshooting — common questions.
• Identity verification — the product overview and its limits.
• Server API reference — the generated endpoint reference.