Overview

The Cloud Token Framework (CTF) is the framework for binding a device and a network token. CTF enables merchants to perform one-time issuer identification and verification and securely binds a user's device to a Visa network token. CTF reduces fraud rates and improves transaction conversion.

Use Classic CTF when your app requires device-level cryptographic binding to a Visa network token in a mobile in-app environment. If your integration instead requires FIDO-based passkey authentication for e-commerce checkout (browser or mobile web), use Payment Passkey instead.

Prerequisites

To send device binding requests, you must have a self-signed certificate associated with your merchant account. See Cloud Token Framework Key Generation.

A token requestor must pass local authentication information. The token requestor can select up to two of these authentication factors for the cardholder to verify their identity at checkout:

Knowledge — Knowledge verification factors include information that only the cardholder knows. For example, a password.

Possession — Possession verification factors include something that only the cardholder has. For example, a pre-registered mobile phone, a card reader, or a key generation device.

Inherence — Inherence verification factors include something that the cardholder is. For example, biometric data. Biometric data includes facial recognition, a fingerprint, voice recognition, or a behavioral biometric.

Cloud Token Framework Key Generation

Follow these steps to generate the credentials required to send device binding requests:

When you follow these steps you create these files:

• root-ca-private-key.pem
• root-ca-certificate.pem
• device-signing-private-key.pem
• device-signing.csr
• device-signing-certificate.pem

# Private CA key (keep offline, never share)openssl genrsa -out root-ca-private-key.pem 2048# Self-signed CA certificate (public) with proper CA extensionsopenssl req -x509 -new -nodes -key root-ca-private-key.pem -days 3650 -out root-ca-certificate.pem

# Device signing private keyopenssl genrsa -out device-signing-private-key.pem 2048# Certificate signing request (CSR) for the device signing keyopenssl req -new -key device-signing-private-key.pem -out device-signing.csr# Issue the device signing certificate from your CAopenssl x509 -req -in device-signing.csr -CA root-ca-certificate.pem -CAkey root-ca-private-key.pem -CAcreateserial -out device-signing-certificate.pem -days 500 -outform PEM

# Verify that device-signing-certificate.pem chains to root-ca-certificate.pemopenssl verify -CAfile root-ca-certificate.pem device-signing-certificate.pem# Verify that data signed with device-signing-private-key.pem matches device-signing-certificate.pemopenssl x509 -in device-signing-certificate.pem -pubkey -noout > device-signing-public-key.pemecho 'test' > message.txtopenssl dgst -sha256 -sign device-signing-private-key.pem -out message.sig message.txtopenssl dgst -sha256 -verify device-signing-public-key.pem -signature message.sig message.txt

Endpoints

Production:

POST /tms/v2/devicesPOST /tms/v2/tokenized-cards/{id}/bindingsPOST /tms/v2/tokens/{id}/payment-credentialsDELETE /tms/v2/tokenized-cards/{id}/bindings/{clientDeviceID}POST /pts/v2/payments

Test:

POST /tms/v2/devicesPOST /tms/v2/tokenized-cards/{id}/bindingsPOST /tms/v2/tokens/{id}/payment-credentialsDELETE /tms/v2/tokenized-cards/{id}/bindings/{clientDeviceID}POST /pts/v2/payments

Bind a Device

This section contains the information required to bind a device to a network token.

Device Binding Workflow

1. The customer sends a request to the merchant that they consent to bind the device.
2. If the device is not enrolled, the merchant sends a request to to enroll the device.
   • Test: POST {{token:api-test-url-rest}}/tms/v2/devices
3. If the device is enrolled, the merchant sends a request to to bind the device using the device ID.
   • Test: POST {{token:api-test-url-rest}}/tms/v2/tokenized-cards/{id}/bindings
4. sends a binding request to the issuer with the binding ID.
5. The issuer sends a response to with the binding status.
6. If authentication is valid, binds the token to the device.
7. The issuer notifies that binding was successful.
8. sends a response to the merchant that the binding is completed.
9. The merchant notifies the customer that their device binding is complete.

{  "clientDeviceID": "<CLIENT_DEVICE_ID>",  "clientDeviceName": "U0lUIERldmljZSBqV0JW",  "category": "PHONE",  "manufacturer": "Apple",  "brand": "iPhone",  "model": "iPhone 15 Pro Max",  "operatingSystem": {    "type": "IOS",    "version": "26.1",    "buildId": "23B5044I"  },  "certificates": [    {      "usage": "SIGNATURE",      "format": "X509_PEM",      "value": "<DEVICE_CERTIFICATE>"    },    {      "usage": "ENCRYPTION",      "format": "X509_PEM",      "value": "<DEVICE_CERTIFICATE>"    }  ]}

{  "authenticatedIdentities": [    {      "data": "<JWS>",      "provider": "CLIENT_DEVICE_CERT_JWS"    }  ],  "deviceInformation": {    "platformType": "WEB"  }}

{  "action": "BINDING_COMPLETED"}

{  "action": "STEP_UP_AUTHENTICATE",  "stepUpOptions": [    { "method": "OTP_SMS", "value": "...", "source": "...", "id": "..." },    { "method": "OTP_EMAIL", "value": "...", "source": "...", "id": "..." },    { "method": "OTP_ONLINE_BANKING", "value": "...", "source": "...", "id": "..." },    { "method": "APP_TO_APP", "value": "...", "source": "...", "id": "...", "requestPayload": "..." },    { "method": "CUSTOMER_SERVICE", "value": "...", "id": "..." },    { "method": "OUTBOUND_CALL", "value": "...", "id": "..." }  ]}

Bind a Device with Step-Up Authentication

This section contains the information required to bind a device to a network token with step-up authentication.

Device Binding Workflow with Step-Up Authentication

1. The customer sends a request to the merchant that they consent to bind the device.
2. If the device is not enrolled, the merchant sends a request to to enroll the device.
   • Test: POST {{token:api-test-url-rest}}/tms/v2/devices
3. If the device is enrolled, the merchant sends a request to to bind the device using the device ID.
   • Test: POST {{token:api-test-url-rest}}/tms/v2/tokenized-cards/{id}/bindings
4. sends a binding request to the issuer with the binding ID.
5. The issuer sends a response to with a step-up authentication binding status.
6. sends a request to the issuer for authentication methods.
7. The issuer sends a list of authentication methods that are passed on to the customer.
8. The customer selects their authentication method and it is sent to the issuer.
9. The issuer initiates authentication method.
10. If authentication is valid, binds the token to the device.
11. The issuer notifies that binding was successful.
12. sends a response to the merchant that the binding is completed.
13. The merchant notifies the customer that their device binding is complete.

Step-Up Authentication Flow

This workflow shows the possible options for step-up authentication after you send a request to /tokenized-cards/{id}/bindings.

This table lists every step-up method and the authenticatorType value that identifies it:

Select the step-up method that matches the authenticatorType value returned in your binding response to see its complete flow.

{  "clientCorrelationId": "aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX",  "stepUpOption": {    "id": "YWEwMjFhZmFkZDU4ZWI0NDJjYTM0MzY4OTY1YjdhMDE="  },  "otp": "456789",  "issuerAuthCode": "HTZlY2YwOWQ3MDZmYWZj4GMww2Y0YjllZWFkODZkHJI="}

{  "action": "AUTHENTICATION_REGISTRATION"}

{  "clientCorrelationId": "aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX",  "stepUpOption": {    "id": "YWEwMjFhZmFkZDU4ZWI0NDJjYTM0MzY4OTY1YjdhMDE="  }}

{  "maxRequestsAllowed": 0,  "maxVerificationAllowed": 0,  "codeExpiration": 0}

{  "clientCorrelationId": "aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV3wX",  "stepUpOption": {    "id": "YWEwMjFhZmFkZDU4ZWI0NDJjYTM0MzY4OTY1YjdhMDE="  },  "otp": "456789",  "issuerAuthCode": "HTZlY2YwOWQ3MDZmYWZj4GMww2Y0YjllZWFkODZkHJI="}

{  "action": "AUTHENTICATION_REGISTRATION"}

Create Payment Credentials with Device Signed JWS

This section describes how to create payment credentials with device-signed JSON Web Signature (JWS).

Endpoint

{  "clientReferenceInformation": {    "code": "abc"  },  "paymentInformation": {    "customer": {      "id": "<id in payment-credentials url>"    }  },  "orderInformation": {    "amountDetails": {      "totalAmount": "<orderInformation.amountDetails.totalAmount>",      "currency": "<orderInformation.amountDetails.currency>"    },    "billTo": {      "firstName": "<orderInformation.billTo.firstName>",      "lastName": "<orderInformation.billTo.lastName>",      "address1": "<orderInformation.billTo.address1>",      "locality": "<orderInformation.billTo.locality>",      "administrativeArea": "<orderInformation.billTo.administrativeArea>",      "postalCode": "<orderInformation.billTo.postalCode>",      "country": "<orderInformation.billTo.country>",      "email": "<orderInformation.billTo.email>",      "phoneNumber": "<orderInformation.billTo.phoneNumber>"    }  },  "deviceInformation": {    "ipAddress": "<deviceInformation.ipAddress>"  },  "merchantInformation": {    "merchantDescriptor": {      "name": "<merchantInformation.merchantDescriptor.name>",      "url": "<merchantInformation.merchantDescriptor.url>"    }  },  "tokenInformation": {    "tokenAuthenticationInformation": {      "authenticatedIdentities": [        {          "data": "<authenticatedIdentities[].data>",          "provider": "CLIENT_DEVICE_CERT_JWS",          "userAuthenticationMethod": "<authenticatedIdentities[].userAuthenticationMethod>"        }      ]    }  }}

Delete Binding

This section describes how to delete a device binding.

Endpoint

The {id} is the identifier of the tokenized card and {clientDeviceID} is the identifier of the device.

Create Payment Credentials with Payment Passkey

This section describes how to create tokenized card payment credentials with Payment Passkey.

Endpoint

{  "processingInformation": {    "authorizationOptions": {      "aftIndicator": "<true = transactionType: AFT>"    }  },  "paymentInformation": {    "customer": {      "id": "<id in payment-credentials url>"    }  },  "orderInformation": {    "amountDetails": {      "totalAmount": "<orderInformation.amountDetails.totalAmount>",      "currency": "<orderInformation.amountDetails.currency>"    },    "billTo": {      "firstName": "<orderInformation.billTo.firstName>",      "lastName": "<orderInformation.billTo.lastName>",      "address1": "<orderInformation.billTo.address1>",      "locality": "<orderInformation.billTo.locality>",      "administrativeArea": "<orderInformation.billTo.administrativeArea>",      "postalCode": "<orderInformation.billTo.postalCode>",      "country": "<orderInformation.billTo.country>",      "email": "<orderInformation.billTo.email>",      "phoneNumber": "<orderInformation.billTo.phoneNumber>"    }  },  "deviceInformation": {    "ipAddress": "<deviceInformation.ipAddress>",    "httpAcceptContent": "<deviceInformation.httpAcceptContent>",    "httpBrowserLanguage": "<deviceInformation.httpBrowserLanguage>",    "httpBrowserJavaEnabled": "<deviceInformation.httpBrowserJavaEnabled>",    "httpBrowserJavaScriptEnabled": "<deviceInformation.httpBrowserJavaScriptEnabled>",    "httpBrowserColorDepth": "<deviceInformation.httpBrowserColorDepth>",    "httpBrowserScreenHeight": "<deviceInformation.httpBrowserScreenHeight>",    "httpBrowserScreenWidth": "<deviceInformation.httpBrowserScreenWidth>",    "httpBrowserTimeDifference": "<deviceInformation.httpBrowserTimeDifference>",    "userAgentBrowserValue": "<deviceInformation.userAgentBrowserValue>"  },  "merchantInformation": {    "merchantDescriptor": {      "name": "<merchantInformation.merchantDescriptor.name>",      "url": "<merchantInformation.merchantDescriptor.url>"    }  },  "tokenInformation": {    "clientCorrelationId": "<clientCorrelationId>",    "tokenAuthenticationInformation": {      "authenticatedIdentities": [        {          "data": "<authenticatedIdentities[].data>",          "provider": "<authenticatedIdentities[].provider>",          "id": "<authenticatedIdentities[].id>",          "relyingPartyId": "<authenticatedIdentities[].relyingPartyId>",          "userAuthenticationMethod": "<authenticatedIdentities[].userAuthenticationMethod>"        }      ]    }  }}