KYC, KYB, and AML compliance

Banking cannot activate an account until the holder is verified. The compliance module covers three flows: KYC (Know Your Customer) for individuals, KYB (Know Your Business) for entities, and AML (Anti-Money Laundering) screening for both at onboarding and on every transaction. All three sit under /banking/compliance/*.

KYC (individuals)

KYC verifies a natural person's identity. The flow is: initiate, submit documents, await automated decision, optional manual review, final approval or rejection.

Status lifecycle

pending → in_progress → approved
                    ↓
              review_required → approved | rejected
                    ↓
                rejected

Initiate

{ "holderId": "holder_abc" }

The holder must already exist with identity fields populated. The platform pushes the data to the configured verification provider (Persona by default; Plaid Identity and Alloy are also supported via SponsorBankProvider) and returns a verification record with status in_progress.

Get status

Returns the current KYC record: status, provider, decision factors (when available), required documents, and reasons for any rejection or review hold.

Submit a document

Body: { type: string, fileId: string }. Upload the file via the file API first, then submit the file ID here. Document types:

Type	Notes
drivers_license	Front + back; some sponsors accept either alone.
passport	International support varies.
state_id	Government-issued ID.
utility_bill	Address verification.
bank_statement	Optional secondary doc.

Manual review

When the provider returns review_required (typically because automated checks were inconclusive), an admin can override:

{ "decision": "approved", "notes": "Verified ID via video call" }

decision is approved or rejected. notes is required and stored on the audit trail. This endpoint should be gated to a senior compliance role on your side — controllers do not gate it beyond RoleType.User.

KYB (businesses)

KYB verifies a legal entity. It includes the business itself, beneficial owners (any individual owning ≥25%), and at least one control person.

Initiate

{ "holderId": "holder_biz_abc" }

The holder must be holderType: "business" with businessName, ein, and registered address.

Add beneficial owners

{
  "firstName": "Alice",
  "lastName": "Doe",
  "dateOfBirth": "1985-04-12",
  "ssn": "123-45-6789",
  "ownershipPercentage": 60,
  "isControlPerson": true,
  "address": {
    "line1": "100 Main St",
    "city": "Brooklyn",
    "state": "NY",
    "postalCode": "11201",
    "country": "US"
  }
}

Required for any owner with ≥25%. Add owners until total disclosed ownership ≥75% (the regulatory threshold) and at least one isControlPerson: true. KYB cannot finish until both conditions are met.

Each beneficial owner runs through their own KYC sub-flow — the document submission endpoints can be re-used per owner ID once they're linked.

Submit business documents

{ "type": "articles_of_incorporation", "fileId": "file_..." }

Types:

Type	What
articles_of_incorporation	Or LLC operating agreement.
ein_letter	IRS-issued EIN confirmation (CP 575).
bank_statement	Existing business bank statement.

Get status and review

Same shape as KYC review — { decision, notes }.

AML

AML covers two checks: entity screening (against sanctions lists like OFAC, plus PEP and adverse-media databases) and transaction screening (anomaly detection on transfers).

Entity screening

{ "holderId": "holder_abc" }

Screens the holder's name, DOB, and address against:

• OFAC SDN — US sanctions list.
• OFAC consolidated — non-SDN sanctions.
• EU and UN consolidated lists.
• PEP — Politically Exposed Persons.
• Adverse media.

Returns hit/no-hit per list, with confidence scores and matched record details. Hits move the holder to amlStatus: "review_required"; clean returns move to cleared. AML screening runs automatically on KYC/KYB initiation; this endpoint is for re-screens (rerun on a periodic cadence — quarterly is typical).

Transaction screening

{ "transferId": "tr_abc" }

Runs rules on a single transfer: structuring patterns, velocity anomalies, high-risk geography, sanctioned counterparties. Returns risk score and any rule hits. Used in two modes:

• Real-time, called inline before submitting a wire or large ACH.
• Batch, scheduled to scan recent transfers and flag suspicious ones for SAR (Suspicious Activity Report) review.

The platform does not file SARs on your behalf — that's the sponsor's obligation. The AML output gives you the data the sponsor's BSA officer needs.

Risk levels

Holders carry a riskLevel (low, medium, high) computed from KYC/KYB results plus AML hits. High-risk holders get enhanced due diligence — additional document requirements, lower default limits, manual approval before activation.

Provider abstraction

The actual identity verification, sanctions data, and transaction screening run via third-party providers. The default is Persona for KYC/KYB; Alloy and Plaid Identity are configured alternatives. Provider choice is per-org and lives in SponsorBankProvider config. Switching providers does not change the API surface — only the back-end vendor.

Ongoing monitoring

Compliance is not one-and-done. Best practice patterns:

Cadence	Action
At onboarding	Full KYC/KYB, AML entity screen.
Per transfer	AML transaction screen (real-time for high value, batch for volume).
Quarterly	Re-run AML entity screen on all active holders.
Annually	Refresh KYC docs that have expired (DL, passport).
On change	Re-screen when address, name, or business owners change.

The platform does not run these schedules automatically — wire them up via Automation flows or your own scheduler.

What the platform doesn't do

Be explicit about scope:

• The platform is not a regulated financial institution. Compliance status flows from the sponsor bank.
• The platform does not file SARs, CTRs, or other regulatory reports. It surfaces the data; the sponsor or your designated BSA officer files.
• The platform does not make final accept/reject decisions on its own — automated approvals reflect provider scores; final approval is the sponsor's call.
• AML risk scores are inputs to a human decision, not autonomous determinations.

If you need a deeper compliance posture (your own BSA officer, your own sanctions program), build on top of the data the module surfaces — don't assume the platform replaces your obligations.