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)

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:
  • Santander-style 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.
Flow:
  1. POST /buyers with kycMode: MARKETPLACE_LED.
  2. Upload documents via POST /buyers/{id}/kyc/documents — CoC, VAT proof, AML declaration, 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.
  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: 
curl -X PATCH "https://api.novatrade24.com/v1/partners/${SELLER_ID}/buyers/${BUYER_ID}" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'If-Match: "0"' \
  -H "Content-Type: application/json" \
  -d '{ "kycMode": "NT24_LED" }'
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

ArtifactMode AMode B
VAT validation (VIES)✅✅
Document upload (CoC, VAT proof, ID, AML declaration)✅✅
Daily re-VIES until pickup✅✅
iDenfy identity verification—✅
AML screening—✅
Signed KYC profile PDF—✅
GET /kyc/profile available404✅
POST /kyc/verify available400✅

​
Capability gate — what happens if Mode A is denied

{
  "type": "https://api.novatrade24.com/problems/capability-required",
  "title": "Capability Required",
  "status": 403,
  "detail": "kycMode=MARKETPLACE_LED requires 'allowMarketplaceLedKyc' capability, which is not granted to your organization.",
  "traceId": "req_..."
}
Ask Novatrade24 to provision the capability — or switch to Mode B.

​
Webhook events for KYC

EventFires in
kyc.vies_check_failedBoth modes — when VIES transitions from valid to invalid.
kyc.verification_completedMode B only — on iDenfy + AML outcome.
self_service_invitation.usedBoth modes — when a buyer completes a self-service upload invitation.
self_service_invitation.expiredBoth modes.
No kyc.verification_started — Phase 1 catalog is deliberately trimmed.

​
Next

Buyer onboarding

End-to-end buyer workflow.

DPA + GDPR

How KYC data is handled.