To enroll in VPP the user’s device must have platform authenticators such as Face ID or Touch ID and the browser in use must be VPP compatible. Currently, Cardinal can only enroll Visa branded cards.rds.

Both the Enrollment Flow and the Authentication Flow use the same endpoints, the difference between the flows is not the endpoints but the order in which the steps are taken.

1 1. Compatibility Check
- 1.1 Generating the iframe
  - 1.1.1 FIDO Initialize Session code sample
- 1.2 POST to /FIDO/Init with JWT
- 1.3 /FIDO/Init Response with JWT
2 2. Registration Check
- 2.1 Data Exchange Request
- 2.2 Handling the Data Exchange Response
3 4. EMV 3DS Strong Customer Authentication
4 5. Enrolling the User

1. Compatibility Check

To do a compatibility check the integrator will generate an iframe and use Cardinal's new endpoint to ensure that users meet the basic requirements for Visa Payment Passkey, after enrollment Cardinal will be able to store device information for future VPP calls.

Compatibility Check workflow

Generating the iframe

Below is a simple way to generate an iframe while meeting Cardinal’s requirements.

Cardinal requires a JWT to be generated on the backend.
The backend will then render the JWT in the hidden JWT field.
The page loads in the browser and auto-submits the form to the iframe.

Once the form is submitted, the parent page can’t read the content loaded within the iframe.

FIDO Initialize Session code sample

 <iframe name='fidoInitializeIFrame' height="10" width="10" style="visibility: hidden; position: absolute; top: -1000px; left: -1000px;"> </iframe>
<form id="fidoInitializeForm" target="fidoInitializeIFrame" name="fidoInitialize" method="POST" action="
https://centinelapistag.cardinalcommerce.com/V2/FIDO/Init">
 <input type="hidden" name="JWT" value="Transactional JWT generated per specification" />
</form>
<script>window.onload = function () {
    // Auto submit form on page load
    document.getElementById('fidoInitializeForm').submit();
  }
</script>

This is an HTML snippet that contains an iframe, a form, and a JavaScript. This example shows a simple way to inject an iframe on page load.

<iframe>: It's a HTML element used to embed another HTML document within the current HTML document. The given iframe is named 'fidoInitializeIFrame' and is hidden from view (with visibility set to 'hidden' and positioned off-screen).
<form>: The form is configured to POST to the URL 'https://centinelapistag.cardinalcommerce.com/V2/FIDO/Init', and the target of this form submission is the previously mentioned iframe. This form includes a hidden input field named 'JWT' and the value is set as 'Transactional JWT generated per specification'. This suggests that a JSON Web Token should be generated and inserted into this field as part of the form submission data.
<script>: When the window is loaded, the script automatically submits the form with id 'fidoInitializeForm'. This means that as soon as the HTML page loads, the form will be submitted automatically without any user interaction.

In summary, when this HTML page is loaded, it automatically submits a form containing a JWT to a specified URL, and the response from that submission will be loaded into a hidden iframe.

POST to /FIDO/Init with JWT

The /FIDO/Init request uses the same JWT request format as other Cardinal Cruise endpoints. See our existing JWT documentation for instructions on creating and formatting the base JWT.
When the customer lands on the merchant page, the integrator should create a hidden iframe and call the new /FIDO/Init endpoint with the new field merchantorigin located in the payload.

MerchantOrigin is required to match the window.origin and must include:

A scheme of https
A top-level domain
If an integrator sends a port, it must be 443

{
  "iss": "ApiKeyId",
  "jti": "6325c60f-d31c-4450-8184-30699ebac69c",
  "iat": 1448997865,
  "OrgUnitId": "MyOrgUnit",
  "ReturnUrl": "https://onlinestore.com/myreturn",
  "ObjectifyPayload": true,
  "Payload": {
     "MerchantOrigin": "https://onlinestore.com"
  }
}

This call only supports SHA-256 algorithm when generating a signature for the JWT.

For more information on origins go here: Origin - MDN Web Docs Glossary: Definitions of Web-related terms | MDN

/FIDO/Init Response with JWT

Receiving a successful response on the ReturnUrl will include a JWT payload with a ReferenceId value used for all subsequent calls in a VPP transaction.

{
  "iss": "5f0780aeadf32541e357357a",
  "iat": 1715173482,
  "exp": 1715180682,
  "jti": "6325c60f-d31c-4450-8184-30699ebac69c",
  "aud": "739debe0-799e-43fd-8bab-e254340cd745",
  "Payload": {
    "ReferenceId": "1234-12345-1234-1234",
    "ErrorNumber": 0,
    "ErrorDescription":"Success"
  }
}

2 . Registration Check

Integrators use the Data Exchange API (DX API) to determine whether a user is enrolled in Visa Payment Passkey (VPP). The DX API is a versatile set of endpoints that provide additional information and real-time insights into the transaction process prior to authentication. In the context of VPP, the DX API’s /Encrypted/GetInfo endpoint is leveraged to determine the VPP enrollment status of the cardholder, as well as what authentication programs are supported by the PAN’s ACS.

If you are not already integrated to the Data Exchange API, we recommend going to: Data Exchange API.

Registration Check workflow

Data Exchange Request

Listed below is the Data Exchange request with the new Payment Object and the following listed fields added for VPP:

Payment Object:

Amount- The total transaction amount formatted with a decimal.
CurrencyCode- A 3-character alpha ISO 4217 currency code for the sale amount.
MerchantName- The name of the merchant requesting the VPP transaction.

New Fields not in the Payment Object:

LanguagePreference- An array to indicate the supported language preference with the ISO 639-1 alpha-2 code, which consists of two-letter codes for languages.
Email - The cardholder's email.

When sending to the /Encrypted/GetInfo endpoint be sure to include the same ReferenceId value returned by Cardinal from the /FIDO/Init response.

Handling the Data Exchange Response

When you receive a response that has the new FIDO sub-object with the following new fields:

FlowType -Determines whether the integrator can enroll or authenticate the cardholder using VPP.
ReasonCode - Present when failure is returned in the FlowType field.
ReasonDescription- Present when failure is returned in the FlowType field.

The integrator should expect to receive a Flow Type of "Enrollment" for an enrollment flow as shown in the sample code below:

4. EMV 3DS Strong Customer Authentication

For a user to be enrolled into Visa Payment Passkey Service, they will need to go through a successful 3DS SCA challenge. The steps for a challenge request are similar to Cardinal Consumer Authentication.

Every 3DS SCA transaction will require Device Data Collection, a cmpi_Lookup Request/Response, a Stepup URL, and the cmpi_Authenticate Request/Response. For more information on these steps go to Cardinal Cruise API

The following instructions will point out key differences from the Cruise Integration.

Device Data Collection

The Device Data Collection process remains unchanged from its implementation in normal 3DS authentication with one important caveat:

When using DDC with VPP, the ReferenceId in the DDC call must be the same ReferenceId returned by the Data Exchange API in step 2.

After Device Data Collection is complete, the integrator will then run the cmpi_ lookup request.

CMPI Lookup Request to Centinel

The cmpi_lookup request call is part of the Cardinal Cruise API. An overview of this request call and its responses can be found in our cmpi_lookup documentation. The cmpi_lookup request has required fields and extra, conditional fields that allow it to be configured for a specific purpose.

The following fields are required for Visa Payment Passkey on the cmpi_lookup request:

Email
CardNumber (PAN)
DFReferenceId
ChallengeIndicator
Currency Code
Amount

The Email, CardNumber (PAN), DFReferenceId, Amount and CurrencyCode are required fields in the cmpi_lookup, and these fields must match what was sent earlier in the registration check .

Conditional Field for CMPI Lookup

In the context of the VPP Enrollment Flow, the following conditional fields are required:

Field

Type

Required

Description

ChallengeIndicator

N(2)

Y

For VPP enrollment flow the Challenge Indicator should either be:

04 = Challenge requested (Mandate)

AlternateAuthenticationMethod

N(2)

Y

For VPP enrollment flow the Integrator should send the value of:

80

Handling the cmpi_Authenticate Response

After the cmpi_lookup request is sent with the required fields in the correct format then authentication continues as expected. A successful challenge is required to move forward with VPP enrollment. If the integrator does not receive a successful challenge response on the cmpi_lookup authenticate response, then the VPP enrollment flow cannot continue.

A new field has been added to the cmpi_authenticate response that is required for successful VPP enrollments. The new field is called FidoEligible and the integrator should expect a response of “This transaction is FIDO Eligible, please continue with FIDO Enrollment.” This new field can also be found in the Authenticate Response (cmpi_authenticate) spec.

At this point 3DS authentication is complete and the integrator completes the order, but the cardholder still needs to enroll in Visa Payment Passkey.

5. Enrolling the User

Integrator Generates the Challenge Iframe

Please review the code sample below for an example on how to best generate the Challenge iframe.

Visa Payment Passkey Enrollment Request with JWT

The /FIDO/Challenge request uses the same JWT request format as other Cardinal Cruise endpoints. See our existing JWT documentation for instructions on creating and formatting the base JWT. As with other specialized uses of JWTs in the API, the challenge JWT has a payload object that contains Enroll specific claims, as well as two extra claims in the main body: ReferenceId and ReturnURL.

After the request has been sent to Cardinal the cardholder will be prompted with enrollment and will fill out the form and complete the challenge. Cardinal then sends the challenge response.

Visa Payment Passkey Enrollment Response with JWT

The /FIDO/Challenge endpoint will return the response as a JWT like most Cardinal Cruise API endpoints. This section details the Payload claim within the enroll JWT, which contains information unique to this endpoint. Please refer to the existing documentation on JWTs for more information on handling JWT responses.

Sample Enrolled Challenge Response:

When the challenge is received the cardholder is both enrolled and authenticated with Visa Payment Passkey.

If a failure occurs, then Cardinal recommends continuing with a 3DS SCA transaction without Visa Payment Passkey.

Enrolling a User