Step-Up Authentication Methods
Overview
When a request to create tokenized card authentication options returns STEP_UP_AUTHENTICATE, the issuer requires additional verification before the device can be approved and passkey registration can proceed. This page compares the available step-up methods and walks through the complete flow for each one.
Authentication Step-Up Methods
This table lists every step-up method, the stepUpOptions.method value that identifies it, and which endpoints apply to it:
| Step-Up Method Type | Step-Up Method Description | stepUpOptions.method | Example Value | stepUpOptions.platformType | stepUpOptions.subMethod | One-Time Passwords | Validate | Authentication Registrations |
|---|---|---|---|---|---|---|---|---|
| One-time password (OTP) | Email OTP | OTP_EMAIL | [email protected] | — | — | Yes | Yes | Yes |
| One-time password (OTP) | Issuer account login OTP | OTP_ONLINE_BANKING | — | — | — | Yes | Yes | Yes |
| One-time password (OTP) | SMS OTP | OTP_SMS | — | — | — | Yes | Yes | Yes |
| Issuer application | Issuer application does not return an issuer authentication code | APP_TO_APP | Mobile Banking Application | — | — | No | No | Yes |
| Issuer application | Issuer application returns an issuer authentication code | APP_TO_APP | Mobile Banking Application | — | — | No | Yes | Yes |
| Issuer | Issuer 3-D Secure | APP_TO_APP | Mobile Banking Application | WEB | 3DS | No | No | Yes |
| Phone | Cardholder calls issuer call center | CUSTOMER_SERVICE | 1-800-555-1212 | — | — | No | No | Yes |
| Phone | Issuer calls cardholder | OUTBOUND_CALL | — | — | — | No | No | Yes |
The endpoint columns refer to:
- One-Time Passwords:
POST /tms/v2/tokenized-cards/{tokenId}/authentication-options/one-time-passwords - Validate:
POST /tms/v2/tokenized-cards/{tokenId}/authentication-options/validate - Authentication Registrations:
POST /tms/v2/tokenized-cards/{tokenId}/authentication-registrations
Select the step-up method that matches the stepUpOptions.method value returned in your authentication options response to see its complete registration flow.
Follow these steps to register a device and network token combination with Payment Passkey for the APP_TO_APP, CUSTOMER_SERVICE, and OUTBOUND_CALL step-up methods.
Determine FIDO Availability
Create a Passkey Service registration for the device and network token combination.
Endpoint
POST /tms/v2/tokenized-cards/{tokenId}/authentication-registrations
POST /tms/v2/tokenized-cards/{tokenId}/authentication-registrations
The {tokenId} is the identifier of the tokenized card.
Example
{ "clientCorrelationId": "4cba8c5a-5b21-4812-8783-f91be68aa72a", "sessionInformation": { "secureToken": "ezAwMX06AAM1NUHl3Gq8..." }, "authenticatorRenderMethod": "IFRAME", "orderInformation": { "amountDetails": { "totalAmount": "1765.95", "currency": "978" }, "billTo": { "email": "[email protected]", "phoneNumber": "4158880000" } }, "merchantInformation": { "merchantDescriptor": { "name": "TWVyY2hhbnQgVlphRjVYQmo", "url": "aHR0cHM6Ly93d3cuTWVyY2hhbnQtVlphRjVYQmouY29t" } }, "deviceInformation": { "platformType": "WEB", "ipAddress": "104.28.3.217", "httpAcceptContent": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7", "httpBrowserLanguage": "en-US", "httpBrowserJavaEnabled": false, "httpBrowserJavaScriptEnabled": true, "httpBrowserColorDepth": "24", "httpBrowserScreenHeight": "1080", "httpBrowserScreenWidth": "1920", "httpBrowserTimeDifference": "420", "userAgentBrowserValue": "Mozilla/5.0(WindowsNT10.0;Win64;x64)AppleWebKit/537.36(KHTML,likeGecko)Chrome/134.0.0.0Safari/537.36Edg/134.0.0.0" }, "buyerInformation": { "language": "en_US" }}{ "authenticationContext": { "id": "de5ecf36-2a5c-4f66-b01f-15d6e5b73715", "endpoint": "/vts-auth/authenticate", "payload": "aGVsbG8", "platformType": "WEB" }}| Field | Type | Description |
|---|---|---|
buyerInformation.language | string | The cardholder's language preference. |
clientCorrelationId | string | A unique identifier for the client request. |
deviceInformation.httpAcceptContent | string | The HTTP Accept header from the device browser. |
deviceInformation.httpBrowserColorDepth | string | The color depth of the device browser. |
deviceInformation.httpBrowserJavaEnabled | boolean | Whether Java is enabled on the device browser. |
deviceInformation.httpBrowserJavaScriptEnabled | boolean | Whether JavaScript is enabled on the device browser. |
deviceInformation.httpBrowserLanguage | string | The language setting of the device browser. |
deviceInformation.httpBrowserScreenHeight | string | The screen height of the device browser. |
deviceInformation.httpBrowserScreenWidth | string | The screen width of the device browser. |
deviceInformation.httpBrowserTimeDifference | string | The time zone offset of the device browser. |
deviceInformation.ipAddress | string | The IP address of the device. |
deviceInformation.platformType | string | The platform type of the device. |
deviceInformation.userAgentBrowserValue | string | The user agent string of the device browser. |
merchantInformation.merchantDescriptor.name | string | The merchant display name. |
merchantInformation.merchantDescriptor.url | string | The merchant URL. |
orderInformation.amountDetails.currency | string | The currency code. |
orderInformation.amountDetails.totalAmount | string | The total transaction amount. |
orderInformation.billTo.email | string | The cardholder's email address. |
sessionInformation.secureToken | string | The secure session token. |
Optional Fields
| Field | Type | Description |
|---|---|---|
authenticatorRenderMethod | string | The method for rendering the authenticator element. |
orderInformation.billTo.phoneNumber | string | The cardholder's phone number. |
Cardholder Authentication with FIDO
The cardholder authenticates with FIDO using the URL from the merchantInformation.merchantDescriptor.url field sent to the /tms/v2/tokenized-cards/{tokenId}/authentication-registrations endpoint.
Create Payment Credentials with FIDO Data
Create a cryptogram that supplies authenticated Passkey Service credentials.
Endpoint
POST /tms/v2/tokens/{tokenId}/payment-credentials
POST /tms/v2/tokens/{tokenId}/payment-credentials
Example
{ "clientCorrelationId": "aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX", "transactionType": "ECOM", "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "email": "[email protected]", "address1": "123 Fake Street", "locality": "Austin", "administrativeArea": "TX", "postalCode": "78751", "country": "US" } }, "merchantInformation": { "merchantDescriptor": { "name": "Merchants Name", "url": "http://www.example.com" } }, "buyerInformation": { "language": "en_US" }, "authenticatedIdentities": [ { "id": "HmP8qo_aBOGemJEV_VoC@KaolERq_rL>95dfJV[vtYvDkwf]MchKrItaM2^sGI0", "provider": "string", "data": "@=TFf@Xhj[Vl\\tpf3zJ=bl@E0HCqVcPlxFz]3yRLbG3bTpBzDJtHNMlnP6pL", "relyingPartyId": "<Base64URL encoded string>", "userAuthenticationMethod": "USERNAME_PASSWORD" } ], "deviceInformation": { "ipAddress": "127.0.0.1", "httpAcceptContent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36", "httpBrowserLanguage": "en-US", "httpBrowserJavaEnabled": true, "httpBrowserJavaScriptEnabled": true, "httpBrowserColorDepth": "24", "httpBrowserScreenHeight": "1080", "httpBrowserScreenWidth": "1920", "httpBrowserTimeDifference": "-480", "userAgentBrowserValue": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36" }}{ "_links": { "self": { "href": "/tms/v2/tokens/7010000000016241111/payment-credentials" } }, "tokenizedCard": { "state": "ACTIVE", "enrollmentId": "c2d1b36fad46aed1ca8318dca5ed1e02", "tokenReferenceId": "168661ada5115ca3589b1ba3dabdb102", "number": "4895370016750801", "expirationMonth": "12", "expirationYear": "2023", "type": "visa", "cryptogram": "AwAAAADggP/Ce5+ZciCXQUUAAAA=", "eci": "05", "requestorId": "40010052236", "card": { "suffix": "0394", "expirationMonth": "12", "expirationYear": "2023" } }, "card": { "number": "411111XXXXXX1111" }, "issuer": { "paymentAccountReference": "V0010013022298169667504231315" }, "processingInformation": { "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "previousTransactionId": "123456789619999" } } }, "commerceIndicator": "vbv" }}| Field | Type | Description |
|---|---|---|
authenticatedIdentities.data | string | The FIDO authentication response data (fidoResponse.fidoBlob). |
authenticatedIdentities.id | string | A unique identifier for the authenticated identity (fidoResponse.identifier). |
authenticatedIdentities.provider | string | The identity provider that performed the authentication. |
authenticatedIdentities.relyingPartyId | string | The FIDO relying party identifier, Base64URL encoded (fidoResponse.rpID). |
clientCorrelationId | string | A unique identifier for the client request. |
deviceInformation.httpAcceptContent | string | The HTTP Accept header from the device browser. |
deviceInformation.httpBrowserColorDepth | string | The color depth of the device browser. |
deviceInformation.httpBrowserJavaEnabled | boolean | Whether Java is enabled on the device browser. |
deviceInformation.httpBrowserJavaScriptEnabled | boolean | Whether JavaScript is enabled on the device browser. |
deviceInformation.httpBrowserLanguage | string | The language setting of the device browser. |
deviceInformation.httpBrowserScreenHeight | string | The screen height of the device browser. |
deviceInformation.httpBrowserScreenWidth | string | The screen width of the device browser. |
deviceInformation.httpBrowserTimeDifference | string | The time zone offset of the device browser. |
deviceInformation.ipAddress | string | The IP address of the device. |
deviceInformation.platformType | string | The platform type of the device. |
deviceInformation.userAgentBrowserValue | string | The user agent string of the device browser. |
merchantInformation.merchantDescriptor.name | string | The merchant display name. |
merchantInformation.merchantDescriptor.url | string | The merchant URL. |
orderInformation.amountDetails.currency | string | The currency code. |
orderInformation.amountDetails.totalAmount | string | The total transaction amount. |
orderInformation.billTo.address1 | string | The cardholder's street address. |
orderInformation.billTo.administrativeArea | string | The cardholder's state or province. |
orderInformation.billTo.country | string | The cardholder's country. |
orderInformation.billTo.email | string | The cardholder's email address. |
orderInformation.billTo.firstName | string | The cardholder's first name. |
orderInformation.billTo.lastName | string | The cardholder's last name. |
orderInformation.billTo.locality | string | The cardholder's city. Required for countries where billing address information is available. |
orderInformation.billTo.postalCode | string | The cardholder's postal code. |
transactionType | string | The type of transaction, for example ECOM for e-commerce. |
Follow these steps to register a device and network token combination with Payment Passkey for a web or application notification from an issuer that is not integrated with Visa.
Validate the OTP or Issuer Authentication Code
When the cardholder receives their OTP by their selected method (SMS, email, or online banking), or an issuer authentication code from their banking application, verify the OTP or issuer authentication code with this request.
Endpoint
POST /tms/v2/tokenized-cards/{tokenId}/authentication-options/validate
POST /tms/v2/tokenized-cards/{tokenId}/authentication-options/validate
Example
{ "clientCorrelationId": "aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX", "stepUpOption": { "id": "YWEwMjFhZmFkZDU4ZWI0NDJjYTM0MzY4OTY1YjdhMDE=" }, "otp": "456789", "issuerAuthCode": "HTZlY2YwOWQ3MDZmYWZj4GMww2Y0YjllZWFkODZkHJI="}{ "action": "AUTHENTICATION_REGISTRATION"}| Field | Type | Description |
|---|---|---|
clientCorrelationId | string | Set to the client reference ID. |
stepUpOption.id | string | The identifier of the step-up option the cardholder selected, from stepUpOptions.id in the authentication options response. |
Optional Fields
| Field | Type | Description |
|---|---|---|
issuerAuthCode | string | Required when otp is not included in the request. The authentication code returned by the issuer's application. |
otp | string | Required when issuerAuthCode is not included in the request. The one-time password code the cardholder received from the issuer. |
Determine FIDO Availability
Create a Passkey Service registration for the device and network token combination.
Endpoint
POST /tms/v2/tokenized-cards/{tokenId}/authentication-registrations
POST /tms/v2/tokenized-cards/{tokenId}/authentication-registrations
The {tokenId} is the identifier of the tokenized card.
Example
{ "clientCorrelationId": "4cba8c5a-5b21-4812-8783-f91be68aa72a", "sessionInformation": { "secureToken": "ezAwMX06AAM1NUHl3Gq8..." }, "authenticatorRenderMethod": "IFRAME", "orderInformation": { "amountDetails": { "totalAmount": "1765.95", "currency": "978" }, "billTo": { "email": "[email protected]", "phoneNumber": "4158880000" } }, "merchantInformation": { "merchantDescriptor": { "name": "TWVyY2hhbnQgVlphRjVYQmo", "url": "aHR0cHM6Ly93d3cuTWVyY2hhbnQtVlphRjVYQmouY29t" } }, "deviceInformation": { "platformType": "WEB", "ipAddress": "104.28.3.217", "httpAcceptContent": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7", "httpBrowserLanguage": "en-US", "httpBrowserJavaEnabled": false, "httpBrowserJavaScriptEnabled": true, "httpBrowserColorDepth": "24", "httpBrowserScreenHeight": "1080", "httpBrowserScreenWidth": "1920", "httpBrowserTimeDifference": "420", "userAgentBrowserValue": "Mozilla/5.0(WindowsNT10.0;Win64;x64)AppleWebKit/537.36(KHTML,likeGecko)Chrome/134.0.0.0Safari/537.36Edg/134.0.0.0" }, "buyerInformation": { "language": "en_US" }}{ "authenticationContext": { "id": "de5ecf36-2a5c-4f66-b01f-15d6e5b73715", "endpoint": "/vts-auth/authenticate", "payload": "aGVsbG8", "platformType": "WEB" }}| Field | Type | Description |
|---|---|---|
buyerInformation.language | string | The cardholder's language preference. |
clientCorrelationId | string | A unique identifier for the client request. |
deviceInformation.httpAcceptContent | string | The HTTP Accept header from the device browser. |
deviceInformation.httpBrowserColorDepth | string | The color depth of the device browser. |
deviceInformation.httpBrowserJavaEnabled | boolean | Whether Java is enabled on the device browser. |
deviceInformation.httpBrowserJavaScriptEnabled | boolean | Whether JavaScript is enabled on the device browser. |
deviceInformation.httpBrowserLanguage | string | The language setting of the device browser. |
deviceInformation.httpBrowserScreenHeight | string | The screen height of the device browser. |
deviceInformation.httpBrowserScreenWidth | string | The screen width of the device browser. |
deviceInformation.httpBrowserTimeDifference | string | The time zone offset of the device browser. |
deviceInformation.ipAddress | string | The IP address of the device. |
deviceInformation.platformType | string | The platform type of the device. |
deviceInformation.userAgentBrowserValue | string | The user agent string of the device browser. |
merchantInformation.merchantDescriptor.name | string | The merchant display name. |
merchantInformation.merchantDescriptor.url | string | The merchant URL. |
orderInformation.amountDetails.currency | string | The currency code. |
orderInformation.amountDetails.totalAmount | string | The total transaction amount. |
orderInformation.billTo.email | string | The cardholder's email address. |
sessionInformation.secureToken | string | The secure session token. |
Optional Fields
| Field | Type | Description |
|---|---|---|
authenticatorRenderMethod | string | The method for rendering the authenticator element. |
orderInformation.billTo.phoneNumber | string | The cardholder's phone number. |
Cardholder Authentication with FIDO
The cardholder authenticates with FIDO using the URL from the merchantInformation.merchantDescriptor.url field sent to the /tms/v2/tokenized-cards/{tokenId}/authentication-registrations endpoint.
Create Payment Credentials with FIDO Data
Create a cryptogram that supplies authenticated Passkey Service credentials.
Endpoint
POST /tms/v2/tokens/{tokenId}/payment-credentials
POST /tms/v2/tokens/{tokenId}/payment-credentials
Example
{ "clientCorrelationId": "aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX", "transactionType": "ECOM", "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "email": "[email protected]", "address1": "123 Fake Street", "locality": "Austin", "administrativeArea": "TX", "postalCode": "78751", "country": "US" } }, "merchantInformation": { "merchantDescriptor": { "name": "Merchants Name", "url": "http://www.example.com" } }, "buyerInformation": { "language": "en_US" }, "authenticatedIdentities": [ { "id": "HmP8qo_aBOGemJEV_VoC@KaolERq_rL>95dfJV[vtYvDkwf]MchKrItaM2^sGI0", "provider": "string", "data": "@=TFf@Xhj[Vl\\tpf3zJ=bl@E0HCqVcPlxFz]3yRLbG3bTpBzDJtHNMlnP6pL", "relyingPartyId": "<Base64URL encoded string>", "userAuthenticationMethod": "USERNAME_PASSWORD" } ], "deviceInformation": { "ipAddress": "127.0.0.1", "httpAcceptContent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36", "httpBrowserLanguage": "en-US", "httpBrowserJavaEnabled": true, "httpBrowserJavaScriptEnabled": true, "httpBrowserColorDepth": "24", "httpBrowserScreenHeight": "1080", "httpBrowserScreenWidth": "1920", "httpBrowserTimeDifference": "-480", "userAgentBrowserValue": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36" }}{ "_links": { "self": { "href": "/tms/v2/tokens/7010000000016241111/payment-credentials" } }, "tokenizedCard": { "state": "ACTIVE", "enrollmentId": "c2d1b36fad46aed1ca8318dca5ed1e02", "tokenReferenceId": "168661ada5115ca3589b1ba3dabdb102", "number": "4895370016750801", "expirationMonth": "12", "expirationYear": "2023", "type": "visa", "cryptogram": "AwAAAADggP/Ce5+ZciCXQUUAAAA=", "eci": "05", "requestorId": "40010052236", "card": { "suffix": "0394", "expirationMonth": "12", "expirationYear": "2023" } }, "card": { "number": "411111XXXXXX1111" }, "issuer": { "paymentAccountReference": "V0010013022298169667504231315" }, "processingInformation": { "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "previousTransactionId": "123456789619999" } } }, "commerceIndicator": "vbv" }}| Field | Type | Description |
|---|---|---|
authenticatedIdentities.data | string | The FIDO authentication response data (fidoResponse.fidoBlob). |
authenticatedIdentities.id | string | A unique identifier for the authenticated identity (fidoResponse.identifier). |
authenticatedIdentities.provider | string | The identity provider that performed the authentication. |
authenticatedIdentities.relyingPartyId | string | The FIDO relying party identifier, Base64URL encoded (fidoResponse.rpID). |
clientCorrelationId | string | A unique identifier for the client request. |
deviceInformation.httpAcceptContent | string | The HTTP Accept header from the device browser. |
deviceInformation.httpBrowserColorDepth | string | The color depth of the device browser. |
deviceInformation.httpBrowserJavaEnabled | boolean | Whether Java is enabled on the device browser. |
deviceInformation.httpBrowserJavaScriptEnabled | boolean | Whether JavaScript is enabled on the device browser. |
deviceInformation.httpBrowserLanguage | string | The language setting of the device browser. |
deviceInformation.httpBrowserScreenHeight | string | The screen height of the device browser. |
deviceInformation.httpBrowserScreenWidth | string | The screen width of the device browser. |
deviceInformation.httpBrowserTimeDifference | string | The time zone offset of the device browser. |
deviceInformation.ipAddress | string | The IP address of the device. |
deviceInformation.platformType | string | The platform type of the device. |
deviceInformation.userAgentBrowserValue | string | The user agent string of the device browser. |
merchantInformation.merchantDescriptor.name | string | The merchant display name. |
merchantInformation.merchantDescriptor.url | string | The merchant URL. |
orderInformation.amountDetails.currency | string | The currency code. |
orderInformation.amountDetails.totalAmount | string | The total transaction amount. |
orderInformation.billTo.address1 | string | The cardholder's street address. |
orderInformation.billTo.administrativeArea | string | The cardholder's state or province. |
orderInformation.billTo.country | string | The cardholder's country. |
orderInformation.billTo.email | string | The cardholder's email address. |
orderInformation.billTo.firstName | string | The cardholder's first name. |
orderInformation.billTo.lastName | string | The cardholder's last name. |
orderInformation.billTo.locality | string | The cardholder's city. Required for countries where billing address information is available. |
orderInformation.billTo.postalCode | string | The cardholder's postal code. |
transactionType | string | The type of transaction, for example ECOM for e-commerce. |
Follow these steps to register a device and network token combination with Payment Passkey for the OTP_EMAIL, OTP_ONLINE_BANKING, and OTP_SMS step-up methods.
Issuer Sends a One-Time Password Code
Create a one-time password (OTP) for a tokenized card. The issuer is notified when the stepUpOptions.method field is set to OTP_SMS, OTP_EMAIL, or OTP_ONLINE_BANKING.
Endpoint
POST /tms/v2/tokenized-cards/{tokenId}/authentication-options/one-time-passwords
POST /tms/v2/tokenized-cards/{tokenId}/authentication-options/one-time-passwords
Example
{ "clientCorrelationId": "aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX", "stepUpOption": { "id": "YWEwMjFhZmFkZDU4ZWI0NDJjYTM0MzY4OTY1YjdhMDE=" }}{ "maxRequestsAllowed": 0, "maxVerificationAllowed": 0, "codeExpiration": 0}| Field | Type | Description |
|---|---|---|
clientCorrelationId | string | Set to the client reference ID. |
stepUpOption.id | string | The identifier of the step-up option the cardholder selected, from stepUpOptions.id in the authentication options response. |
Validate the OTP Code
When the cardholder receives their OTP by their selected method (SMS, email, or online banking), verify the OTP with this request. If you receive an error when you validate the OTP, get a new OTP from the issuer and repeat the previous step.
Endpoint
POST /tms/v2/tokenized-cards/{tokenId}/authentication-options/validate
POST /tms/v2/tokenized-cards/{tokenId}/authentication-options/validate
Example
{ "clientCorrelationId": "aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX", "stepUpOption": { "id": "YWEwMjFhZmFkZDU4ZWI0NDJjYTM0MzY4OTY1YjdhMDE=" }, "otp": "456789", "issuerAuthCode": "HTZlY2YwOWQ3MDZmYWZj4GMww2Y0YjllZWFkODZkHJI="}{ "action": "AUTHENTICATION_REGISTRATION"}| Field | Type | Description |
|---|---|---|
clientCorrelationId | string | Set to the client reference ID. |
stepUpOption.id | string | The identifier of the step-up option the cardholder selected, from stepUpOptions.id in the authentication options response. |
Optional Fields
| Field | Type | Description |
|---|---|---|
issuerAuthCode | string | Required when otp is not included in the request. The authentication code returned by the issuer's application. |
otp | string | Required when issuerAuthCode is not included in the request. The one-time password code the cardholder received from the issuer. |
Determine FIDO Availability
Create a Passkey Service registration for the device and network token combination.
Endpoint
POST /tms/v2/tokenized-cards/{tokenId}/authentication-registrations
POST /tms/v2/tokenized-cards/{tokenId}/authentication-registrations
The {tokenId} is the identifier of the tokenized card.
Example
{ "clientCorrelationId": "4cba8c5a-5b21-4812-8783-f91be68aa72a", "sessionInformation": { "secureToken": "ezAwMX06AAM1NUHl3Gq8..." }, "authenticatorRenderMethod": "IFRAME", "orderInformation": { "amountDetails": { "totalAmount": "1765.95", "currency": "978" }, "billTo": { "email": "[email protected]", "phoneNumber": "4158880000" } }, "merchantInformation": { "merchantDescriptor": { "name": "TWVyY2hhbnQgVlphRjVYQmo", "url": "aHR0cHM6Ly93d3cuTWVyY2hhbnQtVlphRjVYQmouY29t" } }, "deviceInformation": { "platformType": "WEB", "ipAddress": "104.28.3.217", "httpAcceptContent": "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7", "httpBrowserLanguage": "en-US", "httpBrowserJavaEnabled": false, "httpBrowserJavaScriptEnabled": true, "httpBrowserColorDepth": "24", "httpBrowserScreenHeight": "1080", "httpBrowserScreenWidth": "1920", "httpBrowserTimeDifference": "420", "userAgentBrowserValue": "Mozilla/5.0(WindowsNT10.0;Win64;x64)AppleWebKit/537.36(KHTML,likeGecko)Chrome/134.0.0.0Safari/537.36Edg/134.0.0.0" }, "buyerInformation": { "language": "en_US" }}{ "authenticationContext": { "id": "de5ecf36-2a5c-4f66-b01f-15d6e5b73715", "endpoint": "/vts-auth/authenticate", "payload": "aGVsbG8", "platformType": "WEB" }}| Field | Type | Description |
|---|---|---|
buyerInformation.language | string | The cardholder's language preference. |
clientCorrelationId | string | A unique identifier for the client request. |
deviceInformation.httpAcceptContent | string | The HTTP Accept header from the device browser. |
deviceInformation.httpBrowserColorDepth | string | The color depth of the device browser. |
deviceInformation.httpBrowserJavaEnabled | boolean | Whether Java is enabled on the device browser. |
deviceInformation.httpBrowserJavaScriptEnabled | boolean | Whether JavaScript is enabled on the device browser. |
deviceInformation.httpBrowserLanguage | string | The language setting of the device browser. |
deviceInformation.httpBrowserScreenHeight | string | The screen height of the device browser. |
deviceInformation.httpBrowserScreenWidth | string | The screen width of the device browser. |
deviceInformation.httpBrowserTimeDifference | string | The time zone offset of the device browser. |
deviceInformation.ipAddress | string | The IP address of the device. |
deviceInformation.platformType | string | The platform type of the device. |
deviceInformation.userAgentBrowserValue | string | The user agent string of the device browser. |
merchantInformation.merchantDescriptor.name | string | The merchant display name. |
merchantInformation.merchantDescriptor.url | string | The merchant URL. |
orderInformation.amountDetails.currency | string | The currency code. |
orderInformation.amountDetails.totalAmount | string | The total transaction amount. |
orderInformation.billTo.email | string | The cardholder's email address. |
sessionInformation.secureToken | string | The secure session token. |
Optional Fields
| Field | Type | Description |
|---|---|---|
authenticatorRenderMethod | string | The method for rendering the authenticator element. |
orderInformation.billTo.phoneNumber | string | The cardholder's phone number. |
Cardholder Authentication with FIDO
The cardholder authenticates with FIDO using the URL from the merchantInformation.merchantDescriptor.url field sent to the /tms/v2/tokenized-cards/{tokenId}/authentication-registrations endpoint.
Create Payment Credentials with FIDO Data
Create a cryptogram that supplies authenticated Passkey Service credentials.
Endpoint
POST /tms/v2/tokens/{tokenId}/payment-credentials
POST /tms/v2/tokens/{tokenId}/payment-credentials
Example
{ "clientCorrelationId": "aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX", "transactionType": "ECOM", "orderInformation": { "amountDetails": { "totalAmount": "102.21", "currency": "USD" }, "billTo": { "firstName": "John", "lastName": "Smith", "email": "[email protected]", "address1": "123 Fake Street", "locality": "Austin", "administrativeArea": "TX", "postalCode": "78751", "country": "US" } }, "merchantInformation": { "merchantDescriptor": { "name": "Merchants Name", "url": "http://www.example.com" } }, "buyerInformation": { "language": "en_US" }, "authenticatedIdentities": [ { "id": "HmP8qo_aBOGemJEV_VoC@KaolERq_rL>95dfJV[vtYvDkwf]MchKrItaM2^sGI0", "provider": "string", "data": "@=TFf@Xhj[Vl\\tpf3zJ=bl@E0HCqVcPlxFz]3yRLbG3bTpBzDJtHNMlnP6pL", "relyingPartyId": "<Base64URL encoded string>", "userAuthenticationMethod": "USERNAME_PASSWORD" } ], "deviceInformation": { "ipAddress": "127.0.0.1", "httpAcceptContent": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36", "httpBrowserLanguage": "en-US", "httpBrowserJavaEnabled": true, "httpBrowserJavaScriptEnabled": true, "httpBrowserColorDepth": "24", "httpBrowserScreenHeight": "1080", "httpBrowserScreenWidth": "1920", "httpBrowserTimeDifference": "-480", "userAgentBrowserValue": "Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2228.0 Safari/537.36" }}{ "_links": { "self": { "href": "/tms/v2/tokens/7010000000016241111/payment-credentials" } }, "tokenizedCard": { "state": "ACTIVE", "enrollmentId": "c2d1b36fad46aed1ca8318dca5ed1e02", "tokenReferenceId": "168661ada5115ca3589b1ba3dabdb102", "number": "4895370016750801", "expirationMonth": "12", "expirationYear": "2023", "type": "visa", "cryptogram": "AwAAAADggP/Ce5+ZciCXQUUAAAA=", "eci": "05", "requestorId": "40010052236", "card": { "suffix": "0394", "expirationMonth": "12", "expirationYear": "2023" } }, "card": { "number": "411111XXXXXX1111" }, "issuer": { "paymentAccountReference": "V0010013022298169667504231315" }, "processingInformation": { "authorizationOptions": { "initiator": { "merchantInitiatedTransaction": { "previousTransactionId": "123456789619999" } } }, "commerceIndicator": "vbv" }}| Field | Type | Description |
|---|---|---|
authenticatedIdentities.data | string | The FIDO authentication response data (fidoResponse.fidoBlob). |
authenticatedIdentities.id | string | A unique identifier for the authenticated identity (fidoResponse.identifier). |
authenticatedIdentities.provider | string | The identity provider that performed the authentication. |
authenticatedIdentities.relyingPartyId | string | The FIDO relying party identifier, Base64URL encoded (fidoResponse.rpID). |
clientCorrelationId | string | A unique identifier for the client request. |
deviceInformation.httpAcceptContent | string | The HTTP Accept header from the device browser. |
deviceInformation.httpBrowserColorDepth | string | The color depth of the device browser. |
deviceInformation.httpBrowserJavaEnabled | boolean | Whether Java is enabled on the device browser. |
deviceInformation.httpBrowserJavaScriptEnabled | boolean | Whether JavaScript is enabled on the device browser. |
deviceInformation.httpBrowserLanguage | string | The language setting of the device browser. |
deviceInformation.httpBrowserScreenHeight | string | The screen height of the device browser. |
deviceInformation.httpBrowserScreenWidth | string | The screen width of the device browser. |
deviceInformation.httpBrowserTimeDifference | string | The time zone offset of the device browser. |
deviceInformation.ipAddress | string | The IP address of the device. |
deviceInformation.platformType | string | The platform type of the device. |
deviceInformation.userAgentBrowserValue | string | The user agent string of the device browser. |
merchantInformation.merchantDescriptor.name | string | The merchant display name. |
merchantInformation.merchantDescriptor.url | string | The merchant URL. |
orderInformation.amountDetails.currency | string | The currency code. |
orderInformation.amountDetails.totalAmount | string | The total transaction amount. |
orderInformation.billTo.address1 | string | The cardholder's street address. |
orderInformation.billTo.administrativeArea | string | The cardholder's state or province. |
orderInformation.billTo.country | string | The cardholder's country. |
orderInformation.billTo.email | string | The cardholder's email address. |
orderInformation.billTo.firstName | string | The cardholder's first name. |
orderInformation.billTo.lastName | string | The cardholder's last name. |
orderInformation.billTo.locality | string | The cardholder's city. Required for countries where billing address information is available. |
orderInformation.billTo.postalCode | string | The cardholder's postal code. |
transactionType | string | The type of transaction, for example ECOM for e-commerce. |
Thanks for your feedback!
Last published: September 29, 2026