Card Verification

Card verification confirms that a payment card is valid and that the account holder physically controls it. Frame runs the check as part of the onboarding session — a four-step flow that combines a temporary authorization, a 3D Secure challenge, an in-session code entry, and a final validation. The cardholder is never actually billed; the auth is voided automatically after the flow resolves.

Card verification is for card payment methods. ACH verification is a different shape entirely — see bank account verification for that flow.

When to use it

Request card_verification when:

• Your platform stores cards on file and you want explicit ownership confirmation before subsequent charges.
• You want the dispute-evidence advantage 3DS-authenticated transactions carry (more on this below).
• A compliance or risk-management policy requires authenticated cardholder presence at the time of linking, not just at the time of each charge.

For one-off card charges through hosted checkout, you don't need card_verification as a separate capability — Frame already runs the standard issuer checks at charge time. Use card verification when you're storing the card for future use and want the up-front ownership signal.

The flow

Card verification runs four steps inside the onboarding session:

1. $1 pre-authorization — Frame submits a $1 authorization against the card. This is an auth, not a capture — the funds are held briefly and released; the cardholder is never billed. The auth is voided automatically after the verification flow resolves.
2. 3D Secure challenge — the issuer's 3DS flow runs, prompting the cardholder to authenticate (one-time code, biometric, push notification — issuer-dependent). This is what proves the person at the form has access to the cardholder's authentication channel.
3. Code entry — the account holder confirms a verification value inside the onboarding session, demonstrating they control the card.
4. Validation — Frame validates the submitted value. If it matches, the card is linked to the account and the capability activates.

The whole flow happens inside the hosted onboarding session — no redirects, no third-party windows. The cardholder sees one continuous experience: enter card, complete 3DS, confirm, done.

Address-match data stored on the payment method

The 3DS challenge during card verification captures address-match data and stores it on the payment method — so cards verified this way come with strong AVS signal already baked in. This is data on the payment method, not a separate capability activation.

If your platform also wants the address_verification capability as a first-class active state on the account (for downstream policy gating, audit trails, etc.), request address_verification explicitly alongside card_verification. They're independent capabilities; one doesn't auto-expand to include the other. For ACH payment methods, see address verification for the bank-account-side mechanism.

The 3DS cryptogram

A side benefit of 3DS authentication during card verification: Frame stores the 3DS cryptogram (a cryptographic proof of issuer-authenticated authorization) against the payment method.

If a future transaction on this card is disputed, Frame can submit the cryptogram as part of the dispute evidence. 3DS-authenticated transactions carry a significantly higher win rate on chargeback representment because the cryptogram proves the cardholder authenticated with their issuer at the time of card linking — shifting liability away from the merchant. See 3D Secure for the broader 3DS model.

What it doesn't do

Card verification confirms the card is real and the cardholder is present at link time. It doesn't:

• Guarantee the card will be valid in the future (cards expire, get cancelled, get lost).
• Replace per-charge fraud checks — Frame still runs standard fraud signals on each transaction.
• Apply to ACH payment methods — bank accounts have their own verification flow.
• Run outside the onboarding session — there's no standalone "verify a card" API.

Gotchas

Symptom: the $1 authorization shows up on the cardholder's statement and they're calling to ask about it. Why: even though Frame voids the auth, some issuers display pending auths in the customer's statement view for a short window before clearing. Fix: communicate the pattern in your onboarding UX — "you may see a $1 hold that will disappear within a few days" — and provide customer support a canned response.

Symptom: the 3DS challenge fails for an account holder you trust. Why: 3DS friction varies by issuer — some banks send SMS codes that get filtered, some require app-based authentication the user doesn't have installed, some have outage windows. Fix: Frame's card verification fails closed on 3DS failure; the capability transitions to disabled with a 3DS-related reason. Surface a remediation path (try a different card, try again later) rather than treating it as a permanent block.

Symptom: you requested card_verification and expected address_verification to activate along with it. Why: they're independent capabilities — card_verification doesn't auto-expand to include address_verification. The 3DS challenge captures address-match data on the payment method itself, but the address_verification capability stays unrequested unless you ask for it explicitly. Fix: if you want both capabilities active on the account, request both in the capabilities array.

Reference

For onboarding session creation (where card verification flows live), see POST/v1/onboarding_sessions.