Inyo

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

FieldTypeRequiredDescription
capturebooleanNotrue adds the card step to this session. Defaults to false
tokenizeobjectNoAlso tokenize the card through the gateway's tokenizer. Requires capture: true. Send {} for the defaults

tokenize

FieldTypeRequiredDescription
storeLaterUsebooleanNofalse (default) asks the gateway for a one-time token, true for a recurring one. The result reports it as kind: one_time or recurring
threeDSDataobjectNoThe 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:

FieldTypeDescription
enablebooleanRequest 3D Secure for this card
successUrlstringRedirect mode. Your HTTPS page the 3D Secure provider sends the holder to after a passed challenge
failUrlstringRedirect mode. Your HTTPS page for a failed challenge
enablePostMessagebooleanPostMessage 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"
}
CausefieldWhat to do
The card step is not enabled for your tenantpaymentCard.captureAsk your Inyo contact to enable it
tokenize sent, and your tenant has no payment card keypaymentCard.tokenizeThe tokenizer needs your gateway public key on your tenant. Ask your Inyo contact
tokenize sent, and tokenizing is switched off for your tenantpaymentCard.tokenizeAsk your Inyo contact, or send capture alone
tokenize sent, and your tenant has no webhookUrlpaymentCard.tokenizeThe 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: truepaymentCard.tokenize.threeDSDataChoose one return mode, with enable: true
A return URL that is not HTTPS, or longer than 2,048 characterspaymentCard.tokenize.threeDSData.successUrl or .failUrlSend an https:// URL of your own page
tokenize sent without capture: truepaymentCardSet capture: true. A card is tokenized only after it is captured
A field the object does not nameThe field as sentCheck the spelling against the tables above

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


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

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

Next Steps

  • Widget Flow β€” what the holder sees after the selfie
  • Results β€” the PaymentCardTokenized webhook and the paymentCard block
  • Checks β€” the card rows in checks