KYB draft

Owner/Admin members can read and save a private structured draft through GET/POST /portal/merchants/{merchant}/kyb. Fresh membership and MFA are required; Finance, Developer and Support have no access to these identity fields. The browser routes through its session/CSRF BFF.

The profile contains legal name, optional business type, RCCM, national identification and tax number, address, director name/identifier, the activity and at most ten beneficial owners. The activity holds a sector (FASHION, TELECOM, FOOD, EDUCATION, PUBLIC_SERVICES or OTHER), a monthly volume band (UNDER_10K, FROM_10K_TO_50K, FROM_50K_TO_250K or OVER_250K), a website or social page, a start month YYYY-MM (a past or the current month in the DRC’s easternmost time, UTC+2) and what is sold. Sector and band are categories: no limit is derived from them. Each beneficial owner has a stable id (a UUID assigned at the first save when empty, which identity documents name), the identity document type (VOTER_CARD, PASSPORT or DRIVING_LICENCE), its number, optional ownership in integer basis points (10000 = 100%, the sum cannot exceed 10000) and pep, the owner’s own declaration of a prominent public function; screening is separate. Empty fields are allowed for a draft. Text is bounded and normalized; controls, unknown fields and invalid values are rejected. This is not submission validation.

A save requires expected_version and Idempotency-Key, and replaces the whole draft: a profile without the activity, or an owner without id and pep, returns 400 KYB_PROFILE_INCOMPLETE. Start at version 0 for NOT_STARTED. Successful saves return DRAFT with the next version; a save that changes nothing returns the draft with its version kept. While the latest submission is SUBMITTED or IN_REVIEW, changes return 409 KYB_UNDER_REVIEW. Bodies over 32 KiB return 413 REQUEST_TOO_LARGE. An exact normalized retry returns its original successful response, even after later versions. A new stale request or changed body under an old key conflicts. All replays recheck current authorization. The portal saves on its own shortly after typing stops and before moving to another step, and shows when the draft was saved; on KYB_VERSION_CHANGED it reads the saved draft again and reapplies the edits not yet saved.

The draft and complete idempotency request/response envelope use authenticated encryption with purpose, merchant and command binding. Audit records contain only action/version metadata. No plaintext identifiers are stored in audit or command columns. The local wrapping key remains outside the database; production vault, key rotation, access review, retention and deletion remain release gates. Enter only synthetic identifiers in this sandbox.

Private image attachments, submission and the compliance review are separate workflows; live activation is not available in the sandbox. A saved draft is not a verified business.