Flow — Onboarding KYB (merchant)
Création d’un marchand sur la plateforme : entité morale (KYB) + représentant légal (KYC) + premier owner (membre). Flow en 2 étapes (cf. ADR-0004).
Sequence diagram
Trust boundaries traversées
| Étape | Crossing | Contrôle |
|---|---|---|
| 2 (étape 1) | KAM (CMMS) → Orchestrator | Auth KAM + RBAC kam |
| 8 (étape 2) | Lien user → merchant | Vérification user existe + KYC validé |
| Invariant owner | MerchantMembersService.assertNotLastActiveOwner | DB CHECK + service-level |
| 15 (étape 3) | App Business → Orchestrator | JWT + X-Merchant-Id + memberships valides |
| 21 | Orch → Apentis (KYB) | API key vendor |
Spécificités KYB
- KYC subject ≠ propriétaire :
merchants.legal_representative_person_idest le sujet KYC indépendant. Permet le cas du gérant qui n’est pas le représentant légal officiel. - Au moins 1 owner actif : invariant enforced en service (
assertNotLastActiveOwner). Un merchant sans owner actif ne peut pas exister. - Rôles
merchant_member:owner,admin,operator,cashier,accountant.cashierrequiert unposId(DB CHECK). X-Merchant-Idheader : sélecteur du merchant actif côtémobile-business(le user peut avoir plusieurs memberships à terme).
Pré-conditions
- KAM authentifié dans CMMS.
- Au moins un user Nex existant et KYC validé (sera le premier owner).
Post-conditions
| Entity | État |
|---|---|
merchants | créé, status pending puis verified après KYB |
people (legal rep) | créé |
merchant_members | au moins 1 owner actif |
kyb_documents | enregistrés |
| Wallet merchant | créé |
| Apentis | dossier KYB soumis |
Acceptance criteria (Gherkin)
gherkin
Scenario: Onboarding KYB complet d'un merchant
Given un KAM authentifié dans CMMS
And un user Nex existant et KYC validé
When le KAM crée un merchant et lie l'user comme owner
Then le merchant existe avec status "pending"
And merchant_members contient 1 entrée owner active
And un wallet ledger est créé
When l'owner se connecte à Nex Business et upload les documents KYB
And Apentis valide le dossier
Then merchant.status passe à "verified"
And l'owner peut commencer à encaisser
Scenario: Tentative de retirer le dernier owner
Given un merchant avec un seul owner actif
When une opération tente de désactiver cet owner
Then l'opération est rejetée avec motif "au moins un owner actif requis"
Scenario: Cashier sans posId
When une création de merchant_member role=cashier est faite sans posId
Then la DB CHECK rejette la création
And l'API renvoie une erreur de validation