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 |
threeDSData | object | No | The 3D Secure request the gateway's tokenizer takes, passed through unchanged. Omit it to tokenize without 3D Secure |
threeDSData
The fields and their rules are the gateway tokenizer's own β see 3DS Configuration:
| Field | Type | Description |
|---|---|---|
enable | boolean | Request 3D Secure for this card |
successUrl | string | Redirect mode. Your HTTPS page the 3D Secure provider sends the holder to after a passed challenge |
failUrl | string | Redirect mode. Your HTTPS page for a failed challenge |
enablePostMessage | boolean | PostMessage mode. true to receive the challenge result by postMessage on your own page instead |
Send enable: true with both URLs, or with enablePostMessage: true β not both. The URLs and enablePostMessage are refused without enable: true.
"paymentCard": {
"capture": true,
"tokenize": {
"storeLaterUse": false,
"threeDSData": { "enable": true, "enablePostMessage": true }
}
}
With 3D Secure requested, the widget's tokenizing takes a few seconds longer while the gateway's 3D Secure provider collects data from the holder's browser. The holder is never challenged in the widget. A challenge, if the issuer asks for one, comes when you authorize a payment with the token, on your own page, through the URLs or the postMessage listener you set here β see Handling 3D Secure. If you request 3D Secure, authorize while the holder is still on your page.
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, and your tenant has no webhookUrl | paymentCard.tokenize | The token is delivered by webhook the moment it exists. Ask Inyo to register your endpoint |
threeDSData with both return URLs and enablePostMessage, only one URL, or either without enable: true | paymentCard.tokenize.threeDSData | Choose one return mode, with enable: true |
| A return URL that is not HTTPS, or longer than 2,048 characters | paymentCard.tokenize.threeDSData.successUrl or .failUrl | Send an https:// URL of your own page |
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
PaymentCardTokenizedwebhook and thepaymentCardblock - Checks β the card rows in
checks
