Once a user has been enrolled, integrators can now authenticate using Visa Payment Passkey (VPP). This is done through the Authentication Flow which consists of 5 steps

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 Generate 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 3. Device Data Collection
4 4. Passkey Authentication
5 5. cmpi_Lookup Request

1. Compatibility Check

To do a compatibility check the integrator will use Cardinal's new endpoint to ensure that users meet the basic requirements for VPP.

Compatibility Check Workflow

Generate the iframe

This step is required for a compatibility check for both flows. Below is a code sample that the integrator can refer to for creating an 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>

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 of the sample below:

{
  "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 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. 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 Visa Payment Passkey:

Payment Object:

Amount- The total transaction amount formatted with a decimal.
CurrencyCode- A 3-digit alpha ISO 4217 currency code for the sale amount.
MerchantName- The name of the merchant requesting the FIDO 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 FIDO.
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 "Authentication" for an enrollment flow as shown in the sample code below:

3. 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.

4. Passkey Authentication

Integrator Generates the Challenge Pop-up

Integrators must initiate a popup to our /Challenge endpoint for the VPP Authentication flow.

Our MVP solution allows the integrator to test the pop-up flow in the Firefox browser. Integrators can expect to receive a response from Cardinal similar to what is returned on the /FIDO/Init response and the /FIDO/Challenge response for a VPP Enrollment Flow.

Popup Code Sample:

Listed below is a simple popup code sample that Cardinal has provided for the integrators convenience.

For in-depth recommendations on creating a pop-up got to: Creating and Customizing Popups

Popup Blockers

All major browsers have built-in popup blockers that prevent popups unless triggered by a user action. Often, browsers notify users in the address bar when a popup is blocked, but not all do. Integrators must ensure their popups comply with browser restrictions by avoiding programmatic openings and only triggering them through user actions. Since popup blocking criteria differ across browsers, cross-browser testing is recommended to ensure popups are not blocked.

Visa Payment Passkey Authenticate Request with JWT

The /FIDO/Challenge endpoint 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 two extra claims in the main body, both ReferenceId and ReturnURL.

Example Request:

Visa Payment Passkey Authenticate Response with JWT

The /FIDO/Challenge endpoint will return as a JWT. This section details the payload claim within the response JWT, which contains information unique to this endpoint. Please refer to the existing documentation on JWTs for more information on handling JWT responses.

Sample Authenticated Challenge Response:

Note: For field definitions refer to the API reference

The expected response for a VPP authentication flow is a ChallengeState of "AUTHENTICATED." With a ChallengeState of "AUTHENTICATED", the integrator will then create a cmpi_lookup request with the same ReferenceId value used for all previous steps of the Visa Payment Passkey transaction.

5. cmpi_Lookup Request

The cmpi_lookup request 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 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 .

When the cmpi_Lookup Request is sent with the DFReferenceId, Cardinal retrieves the results of VPP authentication and maps the assertion data on the EMV 3DS message to share the VPP authentication evidence with the issuer.

Authenticating a User