Card Verification

Card verification confirms that a payment card is valid and belongs to the account holder. frameOS runs this as part of the onboarding flow — making card setup feel like a natural step of sign-up rather than a separate verification process.

Card verification is only available for card payment methods. It is not supported for bank account (ACH) payment methods.

How it works

Card verification runs a four-step flow during onboarding:

  1. $1 pre-authorization — frameOS runs a $1 authorization against the card. This is a pre-authorization only — it is voided automatically after the verification flow completes, so the charge is never captured and the account holder is never billed. If the user does not complete card verification within one hour, the authorization is automatically voided.
  2. 3DS challenge — a 3D Secure authentication challenge is triggered on the authorization, requiring the account holder to verify their identity with their card issuer.
  3. Code entry — the account holder enters the verification value into the onboarding flow to confirm they have access to the card.
  4. Validation — frameOS validates the submitted value. If it matches, the card is verified and linked to the account.

Because address verification is performed as part of the 3DS check, both capabilities are satisfied in a single flow.

The 3DS authentication also generates a cryptogram that is stored against the payment method. If a dispute is raised on a future transaction, frameOS can submit this cryptogram as part of the dispute evidence — significantly increasing the likelihood of winning the representment.

Integrate with onboarding

Card verification is designed to be part of onboarding. We recommend requesting the card_verification capability alongside your other capabilities so the account holder completes card setup while they're already in the sign-up flow — rather than encountering it later as a separate step.

REQUEST
curl --request POST \
  --url https://api.framepayments.com/v1/accounts \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "individual",
  "capabilities": ["kyc", "card_verification"],
  "profile": {
    "individual": {
      "email": "marcia@example.com",
      "name": {
        "first_name": "Marcia",
        "last_name": "Longo"
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      }
    }
  }
}'

Once the account is created, create an onboarding session. frameOS handles the $1 authorization, 3DS challenge, and code validation within the hosted flow.

Create an account with card verification

Parameters
typestringrequired

Must be individual. Card verification is only supported for individual accounts.

capabilitiesarrayrequired

Include card_verification to enable card verification. Address verification is automatically included — you do not need to add address_verification separately.

profile.individual.emailstringoptional

The account holder's email address.

profile.individual.name.first_namestringoptional

The account holder's first name.

profile.individual.name.last_namestringoptional

The account holder's last name.

profile.individual.phoneobjectoptional

Object containing number and country_code for the account holder's phone.

POST/v1/accounts
curl --request POST \
  --url https://api.framepayments.com/v1/accounts \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "individual",
  "capabilities": ["card_verification"],
  "profile": {
    "individual": {
      "email": "marcia@example.com",
      "name": {
        "first_name": "Marcia",
        "last_name": "Longo"
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      }
    }
  }
}'
RESPONSE
{
  "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "object": "account",
  "type": "individual",
  "status": "pending",
  "external_id": null,
  "capabilities": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567891",
      "object": "capability",
      "name": "card_verification",
      "status": "pending",
      "disabled_reason": null,
      "currently_due": [],
      "disabled": null
    }
  ],
  "profile": {
    "individual": {
      "email": "marcia@example.com",
      "ssn_last_four": null,
      "name": {
        "first_name": "Marcia",
        "middle_name": null,
        "last_name": "Longo",
        "suffix": null
      },
      "phone": {
        "number": "3107484186",
        "country_code": "1"
      },
      "birthdate": null,
      "address": null
    }
  },
  "terms_of_service": null,
  "metadata": {},
  "livemode": false,
  "created": 1721010605
}

Complete onboarding

Create an onboarding session to launch the card verification flow. frameOS guides the account holder through adding their card, completing the 3DS challenge, and entering their verification code — all within the hosted session.

REQUEST
curl --request POST \
  --url https://api.framepayments.com/v1/onboarding_sessions \
  --header 'Authorization: Bearer API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "account_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "return_url": "https://example.com/onboarding/complete"
}'

After the session completes, retrieve the account to confirm the card_verification capability status has transitioned to active.