Skip to main content
Every buyer is created with a kycMode. The mode determines who is responsible for KYC work and what artifacts come out of the process.

​
Mode A: Marketplace-led (MARKETPLACE_LED)

Mode A is not available yet. Every buyer write naming MARKETPLACE_LED is refused with 403, and capabilities.allowMarketplaceLedKyc reads false for every organization until it is. Create buyers with NT24_LED.
You or the marketplace gathers KYC data. NT24 stores it, runs VIES validation, and makes it available on compliance evaluation. No iDenfy, no AML, no signed profile PDF. Who it fits:
  • Marketplaces where your compliance team is already running a full KYC process.
  • DMS providers who have a KYC stack and want NT24 only for VAT compliance storage + VIES.
Requirements:
  • Your organization must have capabilities.allowMarketplaceLedKyc=true. Provisioned by agreement once Mode A is available.
Flow:
  1. POST /buyers with kycMode: MARKETPLACE_LED.
  2. Upload documents via POST /buyers/{id}/kyc/documents, CoC, VAT proof, ID, etc.
  3. Trigger POST /buyers/{id}/kyc/vies-check (or let the daily scheduler handle it once the buyer is attached to an order).
  4. Compliance treats KYC as valid when documents are complete + latest VIES result is VALID.
Artifacts produced:
  • Raw documents stored and attached to the buyer.
  • VIES result history.
  • No signed KYC profile PDF.

​
Mode B: NT24-led (NT24_LED)

NT24 runs the full KYC flow: iDenfy for identity, AML screening, and generates a signed KYC profile PDF your customer’s auditor can consume. Who it fits:
  • Direct dealer integrations where NT24’s KYC is the compliance offering.
  • Customers who want a turnkey KYC process without building one.
Flow:
  1. POST /buyers with kycMode: NT24_LED.
  2. POST /buyers/{id}/kyc/verify starts the verification, returns an iDenfy session URL for the buyer. If the buyer lets that link lapse unused, closing an order that names them is refused until they complete a new identification. Issuing a new link does not lift the refusal; completing the identification does.
  3. Buyer completes iDenfy in-browser. NT24 runs AML screening in parallel.
  4. Webhook kyc.verification_completed fires with outcome (VERIFIED or REJECTED).
  5. For VERIFIED buyers: GET /buyers/{id}/kyc/profile downloads the signed PDF.
Artifacts produced:
  • Full iDenfy verification report (id scan + selfie liveness).
  • AML screening result.
  • Signed KYC profile PDF.

​
Mode upgrade A → B

A buyer created in Mode A can be upgraded to Mode B via PATCH:
The If-Match value is the buyer’s ETag exactly as the last read returned it, not the version integer — see optimistic concurrency. After upgrade, trigger POST /kyc/verify to start NT24-led flow. Existing uploaded documents are preserved. Downgrade (B → A) is not allowed. Documents generated in Mode B (iDenfy, AML) are legal artifacts and cannot be retroactively de-scoped.

​
Artifact comparison

​
Capability gate: what happens if Mode A is denied

Every organization gets this answer until Mode A is available. Use Mode B.

​
Webhook events for KYC

No kyc.verification_started. The catalog is deliberately trimmed to state-change events only.

​
Next

Buyer onboarding

End-to-end buyer workflow.

DPA + GDPR

How KYC data is handled.