Card Sessions

The card step is asked for per session, with the paymentCard object on POST /v1/sessions. Everything else about the request — userRef, prefill, delivery, language — is the identity session's, documented on Verification Sessions.

Create a Session with the Card Step

Endpoint: POST /v1/sessions
Authentication: Bearer token with the sessions scope — see Authentication

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": true
    }
  }
}'

{
  "sessionId": "9f1c8e42-7c3e-4f2b-9d7a-2b1e5c8f4a10",
  "status": "pending",
  "widgetUrl": "https://{FQDN}/verify/8Kd2mQ…",
  "expiresAt": "2026-08-02T15:02:11.481Z"
}

The response is the same as any session's. Deliver widgetUrl the usual way; the card step follows the selfie.

For verification only, send capture alone:

{ "userRef": "user-123", "paymentCard": { "capture": true } }

The `paymentCard` Object

Field	Type	Required	Description
`capture`	boolean	No	`true` adds the card step to this session. Defaults to `false`
`tokenize`	object	No	Also tokenize the card through the gateway's tokenizer. Requires `capture: true`. Send `{}` for the defaults

`tokenize`

Field	Type	Required	Description
`storeLaterUse`	boolean	No	`false` (default) asks the gateway for a one-time token, `true` for a recurring one. The result reports it as `kind`: `one_time` or `recurring`

The card is tokenized without 3D Secure, so the holder is never challenged in the widget. Authenticate when you charge the token: see Handling 3D Secure.

Every object here refuses a field it does not name, so a misspelled storeLaterUse is a 422 rather than a one-time token you did not ask for.

Error Responses

All return 422 with errorCode: "validation_error", in the problem shape every Inyo360 KYC endpoint answers with. errors[].field names the field:

{
  "type": "docs#/components/schemas/ProblemDetails",
  "title": "Unprocessable Entity",
  "status": 422,
  "errorCode": "validation_error",
  "errors": [
    {
      "field": "paymentCard.tokenize",
      "message": "paymentCard.tokenize is not enabled for this tenant",
      "type": "value_error"
    }
  ],
  "correlationId": "…",
  "instance": "/v1/sessions"
}

Cause	`field`	What to do
The card step is not enabled for your tenant	`paymentCard.capture`	Ask your Inyo contact to enable it
`tokenize` sent, and your tenant has no payment card key	`paymentCard.tokenize`	The tokenizer needs your gateway public key on your tenant. Ask your Inyo contact
`tokenize` sent, and tokenizing is switched off for your tenant	`paymentCard.tokenize`	Ask your Inyo contact, or send `capture` alone
`tokenize` sent without `capture: true`	`paymentCard`	Set `capture: true`. A card is tokenized only after it is captured
A field the object does not name	The field as sent	Check the spelling against the tables above

The session-wide refusals — webhook mode with no webhookUrl, prefill problems — are on Verification Sessions.

Settings That Change After a Link Is Sent

The card step and tokenizing are read again each time the widget asks, not only when the session is created.

What changes for your tenant	A link already sent
Tokenizing is switched off, or the payment card key is removed	The card step still runs, as verification only. No token is requested and no `paymentCard` block is delivered
The card step is switched off	The session finishes on the identity steps alone, with no card rows

Next Steps

Widget Flow — what the holder sees after the selfie
Results — the paymentCard block in the result
Checks — the card rows in checks