Settlement accounts

OpenAPI 0.39.0 replaces the account verification route with a two-stage check: GET/POST /portal/merchants/{merchant}/settlement-accounts, then POST …/settlement-accounts/{id}/check, …/{id}/confirm and …/{id}/approve. Owner, Admin and Finance read the accounts with settlements:read; Owner and Admin write with team:manage, the current membership version and, at the portal BFF, a sign-in younger than five minutes (403 STEP_UP_REQUIRED otherwise). Every write takes an Idempotency-Key: the same actor, key and body returns the original answer; a changed body returns 409 IDEMPOTENCY_CONFLICT.

Create takes {expected_version, previous_account, profile_version, currency, kind, reference}: the currency’s newest revision and its version (0 and null for the first), the saved KYB version, USD or CDF, BANK or WALLET, and a reference matching SYNTH-[A-Z0-9-]{8,48}. The synthetic participant answers the holder’s name, compared with the KYB legal name ignoring case and spacing: the account’s state is NAME_MATCHED, NAME_MISMATCH or NAME_UNAVAILABLE. In the sandbox a reference containing MISMATCH answers another holder’s name and one containing UNAVAILABLE no answer; any other answers the KYB legal name. check ({expected_version}) checks the same account again after no answer, a failed credit or a KYB change; it refuses an account already matched or verified against the current KYB with 409 ACCOUNT_CHECKED. Once the KYB as it stands is approved, credit_due turns true and confirm takes {expected_version, amount} in minor units: a right amount makes the account VERIFIED, a wrong one answers credit_outcome: WRONG with attempts_left, and the third ends the check (CREDIT_FAILED). The credit is refused with 409 APPROVED_KYB_REQUIRED before approval and 409 ACCOUNT_NOT_AWAITING_CREDIT in another state. The amount itself is never returned. In the sandbox the synthetic participant’s test credit carries the reference FUTA-VERIF and credits the reference’s last three digits in the currency’s unit: …137 credits 137 FC or $1.37, that is amount 13700 in CDF or 137 in USD; a reference whose last three digits are 000, or that has none, credits 100 FC or $1.00.

The first verified account of a currency is in_use (approval: NOT_NEEDED); settlements go to it while it is verified against the current KYB (destination). An account created while one is in use replaces it, even while the account in use is checked again, and once verified waits with approval: PENDING until approve ({expected_version}) by an Owner or Admin other than proposed_by, after a check against the current KYB; the proposer gets 403 ACCOUNT_SECOND_APPROVER_REQUIRED, and the database refuses an approval by the proposer too. Writes apply to the currency’s newest revision or to the account in use, which can be checked again while a replacement waits; a stale account or version answers 409 ACCOUNT_CHANGED, a changed KYB 409 ACCOUNT_PROFILE_CHANGED, and the same reference added again 409 ACCOUNT_ALREADY_ADDED. holder_name is the participant’s answer only when it matched; an account recorded before the two-stage check reads UNCHECKED and is checked from expected_version 1. A currency keeps at most 50 revisions (ACCOUNT_HISTORY_LIMIT) and an account at most 200 checks (ACCOUNT_VERIFICATION_LIMIT); a destination’s account_version runs from 2 to 201.

Accounts, evidence and command envelopes are encrypted and immutable; audit records hold identifiers only; responses carry a masked reference. Staff settlement proposals route to the currency’s destination checked against the current KYB. This is sandbox verification: a participant’s own name enquiry and test credit replace the synthetic participant once their specification exists.