KYC

Know Your Customer (KYC) verifies that an individual account holder is who they say they are. It's a regulatory and fraud-prevention primitive: collect a legal identity, match it against authoritative sources, confirm with a document and a selfie, and produce a binary outcome you can act on. Frame models KYC as a capability on an account — you request it, Frame runs the checks, and any downstream payment capability that depends on a verified identity activates automatically.

KYC is for individual accounts only. Businesses follow KYB (Know Your Business), which Frame runs against the legal entity while onboarding each owner or controller as a separate individual account in parallel.

When you need KYC

Request the kyc capability when your flow requires a verified identity. The two common cases:

• Paying funds out to an individual. card_receive and bank_account_receive both depend on completed KYC. Frame won't push money to an unverified person.
• Running age-restricted flows. age_verification and other compliance capabilities build on top of KYC.

If you request card_receive, bank_account_receive, or creator_shield on an account, Frame includes kyc automatically — you don't have to ask for it separately. Request kyc directly when you need identity verification independent of any payment capability (e.g., for compliance threshold enforcement on your platform).

Buyers paying you through hosted checkout don't need KYC. The card_send capability activates on a payment method alone; verifying every buyer's identity would be excessive friction for the case where you only need to charge their card.

Required information

To complete KYC for an individual account, Frame needs:

Anything you have at account-creation time, prefill — Frame won't re-collect it during the hosted flow. Fields you don't have are surfaced in the capability's currently_due array; the onboarding session then collects them through Frame-hosted UI.

The flow

KYC is gated by a hosted onboarding session — Frame owns the UX, you own the redirect points. The shape:

1. Create the account with kyc in the capabilities array and any identity fields you already have.
2. Create an onboarding session for the account. Frame returns a URL.
3. Redirect the account holder to that URL. The hosted flow walks them through:
   • Consenting to the identity verification process.
   • Capturing photos of a government-issued ID (front and back, or passport).
   • Taking a selfie for liveness detection and document matching.
   • Confirming any additional fields Frame couldn't prefill from your input (last 4 of SSN, address corrections, etc.).
4. Handle the return. Frame redirects the account holder to your return_url when they finish. The redirect fires when the user clicks through — not when the verification has resolved. Document verification runs asynchronously and can take seconds to minutes.
5. Confirm activation. Subscribe to the capability.activated (success) or capability.disabled (failure) webhook, or poll the account's kyc capability status until it settles. Don't act on the redirect alone.

Walk-through with code: Run KYC.

Outcomes

The kyc capability uses the standard capability lifecycle. The states that matter in practice for a KYC flow you've requested:

• active — Frame matched the identity, the document checks passed, and the selfie matched the document photo. The account holder is verified. Any payment capabilities that depended on KYC activate automatically.
• disabled — verification failed. Look at the capability's associated error records for the failure category (document quality, identity mismatch, etc.) where shareable. Your application should surface a remediation path: retry, request manual review, or decline service per your platform's policy.
• pending — Frame is still waiting on a check (a document is in review, the selfie comparison is queued). Stay subscribed to the capability webhook; the state will transition.

unrequested and ineligible are also valid states on a capability — see the capabilities concept — but for KYC the common path is pending → active or pending → disabled.

Outcomes are not predictive — a disabled KYC for one account holder doesn't say anything about a different one, even with similar fields. KYC is identity verification, not risk scoring.

Re-verification

KYC isn't a one-shot. If an account holder's information changes (legal name change, new address) or your platform's compliance policy mandates periodic refresh, update the profile fields. Frame re-evaluates the kyc capability against the new data automatically. If the update introduces fields Frame can't reconcile against the existing verified record (e.g., a substantially different document), the capability transitions back to pending and a fresh onboarding session collects what's needed.

The previous KYC result isn't "lost" — Frame tracks the verification history on the account. The capability surface reflects the current state.

Scope — what KYC checks

KYC verifies the legal identity claim:

• The name on file matches the document.
• The document is authentic (not forged, not visibly tampered).
• The selfie is a live person, not a static image.
• The selfie face matches the document photo within Frame's matching threshold.
• The other fields (SSN last 4, address, DOB) reconcile against authoritative sources where available.

KYC does not check:

• Whether the person is on a sanctions list (that's separate compliance work, run alongside).
• Whether the address is currently valid (that's address_verification).
• Whether the phone is reachable (that's phone_verification).
• Whether the person is of legal age for a regulated activity (that's age_verification, which builds on KYC).

Treat KYC as the foundation: it verifies identity, and the other compliance capabilities verify specific attributes of that identity.

Platform scope

In V1, Frame's KYC flow is delivered through frame-js (the web SDK) plus a server-side onboarding session you create from your backend. The hosted verification UI loads on os.framepayments.com and walks the account holder through document capture in the browser or mobile browser. Native mobile SDK integration (React Native, iOS, Android) is tracked separately under FRA-3933 — if you need KYC inside a native mobile app, talk to Frame support about the current options.

Gotchas

Symptom: the account holder completed the session and was redirected back, but the kyc capability is still pending. Why: Frame's redirect fires when the user clicks through, not when document analysis resolves. Verification can take seconds to minutes. Fix: listen for capability.activated / capability.disabled webhooks; treat the redirect as "they finished entering data," not "verification passed."

Symptom: you requested kyc plus card_receive on a new account and only kyc shows up pending in the response. Why: Frame stages dependent capabilities — card_receive won't be evaluated until kyc activates. The capability still exists on the account, just not surfaced until its prerequisites resolve. Fix: once kyc transitions to active, retrieve the account again and you'll see card_receive listed and being evaluated.

Symptom: a KYC verification passes for one account holder and fails for a similar-looking one. Why: document quality, lighting, and the matching threshold are all stochastic. KYC is identity-level, not risk-level — small data differences yield different outcomes. Fix: surface a remediation path (re-submit with clearer photos, manual review) rather than treating the failure as final.

Reference

For the full API surface, see POST/v1/accounts and POST/v1/onboarding_sessions.