> ## Documentation Index
> Fetch the complete documentation index at: https://developers.novatrade24.com/llms.txt
> Use this file to discover all available pages before exploring further.

# KYC modes (A vs B)

> Marketplace-led vs NT24-led verification — who runs KYC, what artifacts are produced, and when to pick which.

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`:

```bash theme={null}
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

| Artifact                                              | Mode A | Mode 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` available                          |   404  |    ✅   |
| `POST /kyc/verify` available                          |   400  |    ✅   |

## Capability gate — what happens if Mode A is denied

```json theme={null}
{
  "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

| Event                             | Fires in                                                              |
| --------------------------------- | --------------------------------------------------------------------- |
| `kyc.vies_check_failed`           | Both modes — when VIES transitions from valid to invalid.             |
| `kyc.verification_completed`      | Mode B only — on iDenfy + AML outcome.                                |
| `self_service_invitation.used`    | Both modes — when a buyer completes a self-service upload invitation. |
| `self_service_invitation.expired` | Both modes.                                                           |

No `kyc.verification_started` — Phase 1 catalog is deliberately trimmed.

## Next

<CardGroup cols={2}>
  <Card title="Buyer onboarding" icon="user-plus" href="/guides/buyer-onboarding">
    End-to-end buyer workflow.
  </Card>

  <Card title="DPA + GDPR" icon="scale-balanced" href="/security/gdpr">
    How KYC data is handled.
  </Card>
</CardGroup>