Getting Started

Payment Card Verification is a step of the hosted identity widget. After the customer has photographed their document and taken a selfie, the widget asks for their payment card, front and back, in the same session. The result you already receive for the identity verification carries the card rows too.

This page assumes a working identity integration. If you do not have one yet, start with the identity Getting Started.

Prerequisites

The card step enabled for your tenant. Ask your Inyo contact. Until it is, a session asking for the card is refused with 422.
For tokenize mode, your gateway public key on your tenant, with tokenizing switched on. Inyo sets both; ask your Inyo contact.
Your identity integration: Authentication, a webhookUrl or redirect delivery, and signature verification on Receiving Results.

Two Modes

You choose the mode per session.

Mode	Request	What the holder does	What you receive
Verification only	`"paymentCard": {"capture": true}`	Photographs the card, front and back	Card rows in `checks`: the card is in view, readable and genuine, and its name matches the identity document
Verification and tokenizing	`"paymentCard": {"capture": true, "tokenize": {}}`	Photographs the card, then checks and confirms the details read from it	The same rows, one more that checks the token against the photographed card, and a `paymentCard` block carrying the gateway token

In tokenize mode the holder never types the card into a form of yours. The details are read from the photos on their device and confirmed on the widget's own screen.

Step 1: Create a Session with the Card Step

Get a token as usual — see Authentication — and add paymentCard to POST /v1/sessions:

curl --request POST \
  --url https://{FQDN}/v1/sessions \
  --header "Authorization: Bearer $ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
  "userRef": "user-123",
  "delivery": { "mode": "webhook" },
  "paymentCard": { "capture": true, "tokenize": { "storeLaterUse": false } }
}'

The response is the usual sessionId and widgetUrl. Every field and the refusals are on Card Sessions.

Send widgetUrl the way you already do. The holder goes through the identity steps, then the card step — see Widget Flow for what they see.

Step 3: Receive the Result

The session ends once and is delivered once, by the same webhook or redirect as any identity session. On a tokenize session the result carries the token:

{
  "status": "completed",
  "checks": [
    { "name": "payment_card_token_match", "status": "passed", "group": "payment_card", "severity": "high", "reason": null, "detail": "the tokenized card matches the photographed card and the holder" }
  ],
  "paymentCard": {
    "token": "3b9f6c1e-8d2a-4f7b-9e5c-1a2b3c4d5e6f",
    "lastFour": "4242",
    "kind": "one_time",
    "recordedAt": "2026-07-31T14:04:41.112Z"
  }
}

Read the card rows before you use the token: a tokenize session keeps its paymentCard block whatever the card checks concluded. See Checks and Results.

Step 4: Use the Token

paymentCard.token is a gateway card token. Use it with the gateway's payment APIs exactly as a token from the gateway's own tokenizer, under the same one-time and recurring rules.

Handle These Cases Before You Go Live

Case	What happens	See
The holder runs out of card attempts	The session ends `failed`, with no `paymentCard` block	Checks
A card check fails after the token is recorded	The session completes, the block is present, and the row says what failed	Checks
Tokenizing is switched off for your tenant after a link was sent	That link's card step runs as verification only	Card Sessions
A session without `paymentCard`	No card step, no card rows	—

Next Steps

Card Sessions — the paymentCard object in full
Data Handling — what reaches Inyo360 and what is kept
Sandbox & Test Data — testing the card step