Inyo

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.
  • For tokenize mode, a webhookUrl. The token is delivered by webhook the moment it exists, whatever the session's delivery mode.
  • Your identity integration: Authentication, a webhookUrl or redirect delivery, and signature verification on Receiving Results.

Two Modes

You choose the mode per session.

ModeRequestWhat the holder doesWhat you receive
Verification only"paymentCard": {"capture": true}Photographs the card, front and backCard 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 itThe gateway token in its own webhook, then the same rows and one more that checks the token against the photographed card

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.


Step 2: Deliver the Widget

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: Pre-Authorize on the Token

On a tokenize session, your webhookUrl receives PaymentCardTokenized as soon as the holder's card is tokenized, before the session's decision. Branch on event β€” see Event Types:

{
  "event": "PaymentCardTokenized",
  "sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "paymentCard": {
    "token": "3b9f6c1e-8d2a-4f7b-9e5c-1a2b3c4d5e6f",
    "kind": "one_time",
    "lastFour": "4242",
    "holderName": "MARIA SANTOS",
    "payerIpAddress": "203.0.113.42",
    "expiresAt": "2026-07-31T14:34:39Z",
    "recordedAt": "2026-07-31T14:04:41.112Z"
  },
  "notifiedAt": "2026-07-31T14:04:41.530Z"
}

Authorize a card payment with capture: false and the token as cardTokenId, before expiresAt. The funds are held, not moved. Every field is on Card Results.


Step 4: Capture or Void on the Result

The session ends once, and its result is delivered by the same webhook or redirect as any identity session, as SessionResultUpdated. It carries the token again beside the checks:

{
  "event": "SessionResultUpdated",
  "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 and the decision, then capture the authorization, or void it to release the hold. A tokenize session keeps its paymentCard block whatever the card checks concluded. See Checks and Card Results.

paymentCard.token is a gateway card token, used 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

CaseWhat happensSee
The holder runs out of card attemptsThe session ends failed, with no paymentCard blockChecks
A card check fails after the token is recordedThe session completes, the block is present, and the row says what failed. Void the authorization if you will not captureChecks
The session is declined or expires after you pre-authorizedVoid the authorization to release the holdCard Results
PaymentCardTokenized never reaches youIt is retried until shortly before the token expires; read the session to fetch the token meanwhileCard Results
Tokenizing is switched off for your tenant after a link was sentThat link's card step runs as verification onlyCard Sessions
A session without paymentCardNo card step, no card rowsβ€”

Next Steps