Once a user has been enrolled, FIDO can be used to authenticate that client on future transactions. This is done through the Centinel API’s FIDO Transaction Confirmation Flow.

Broadly speaking, the Transaction Confirmation Flow uses the same starting steps as the Enrollment Flow, branching off at the result of the registration check:

Compatibility Check
A call is made to the FIDO SDK to check browser and device compatibility.
Registration Check
A registration check through the Data Exchange API (DX API). An Email and AccountNumber (PAN) will need to be passed. These values cannot change for the rest of the flow. The call will return a Registered status of true, along with a session ReferenceId.
Device Data Collection (DDC)
DDC is completed using the ReferenceId from step 2. There are special considerations for DDC when used in a FIDO flow that will be discussed below.
Transact Request
A Transact request is made to Centinel API using the Email, AccountNumber, and ReferenceId from step 2. FIDO authentication of the customer occurs in this step.
CMPI Lookup
A cmpi_lookup request is made to the Centinel API using the Email, AccountNumber, and ReferenceId from step 2, completing the 3DS Flow.

This article will focus on step 3-5, with a special emphasis on step 4. Steps 3 and 5 are covered in greater detail in their own articles, with caveats that will be covered here.

Notes

Steps 3 and 4 can and should be completed simultaneously, but step 5 must be started after 3 and 4 have completed. For more information on why steps 3 and 4 should be simultaneous, see the Important Notes section below.
From the time that the registration check returns, the FIDO session represented by the ReferenceId is valid for 20 minutes. After this time, FIDO authentication cannot continue.

Table of Contents

Table of Contents
1 Important Notes on Integration and Call Order 2 Device Data Collection (DDC) 3 Centinel API FIDO Transact Endpoint 3.1 ConnectionURLs 3.2 Endpoints 4 Transact Request JWT 4.1 Transact Request JWT Fields 4.2 Request Payload Object 4.3 Sample Transact Request 5 Transact Response JWT 5.1 Response Payload Object 5.2 Sample Transact Response 6 CMPI Lookup 6.1 Conditional FIDO Fields for cmpi_lookup

Important Notes on Integration and Call Order

In general, the single most time-intensive step of the process is Device Data Collection (DDC). This is largely down to the presence of a Method URL. Method URL is a tool that allows the card issuer to gather data on the transaction to facilitate risk-based authentication. The benefits of Method URL are significant, including higher success and much lower challenge rates. This is balanced against an increased time cost incurred: when a Method URL is present, a DDC call may take up to ten seconds to complete depending on the card issuer. Nevertheless, the benefits of Method URL make it worth accommodating in your implementation.

From testing with various configurations, we’ve come up with a set of implementation recommendations to make incorporating DDC as smooth as possible:

The FIDO registration check can only be started once a PAN is entered (or selected if already stored). This will usually be at some point in the order finalization process. We suggest that the DDC call be run as soon as the registration check is complete.
The DDC call and the Transact request do not need to be completed in order, but the difference in processing time between the two calls means that the DDC request should generally be made first. Both calls must complete before moving to the CMPI lookup.
We recommend calling the Transact request be made when the customer finalizes their transaction, usually when a “Buy Now” or “Checkout” button is pressed.
In an ideal situation, the DDC request would be made on completion of the Registration check, and the Transact request would begin after the DDC call is complete.
If the issuer’s Method URL is slow to respond, the transact call can begin before the DDC response is received.

The Transact request can overlap the DDC request if the MethodURL is taking too long to respond.

Device Data Collection (DDC)

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

When using DDC with FIDO, the ReferenceId in the DDC call must be the same ReferenceId returned by the DX API GetInfo call in step 2.

This differs from the normal DDC process where the ReferenceId can be arbitrarily chosen. With this in mind, see the Device Data Collection articles for more information on how to implement this process.

Centinel API FIDO Transact Endpoint

ConnectionURLs

Environment	URL

Environment	URL
Staging	https://centinelapiwpstag.cardinalcommerce.com/
Production	https://centinelapi.cardinalcommerce.com/

Endpoints

Endpoint	Path

Endpoint	Path
Transact	/V1/Fido/Transact

Transact Request JWT

The Transact Request uses the same JWT request format as other Centinel API 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 Transact JWT has a Payload object that contains Transact-specific claims, as well as two extra claims in the main body: ReferenceId and ReturnURL.

Transact Request JWT Fields

Field	Description	Required

Field	Description	Required
jti	JWT Id - A unique identifier for this JWT. This field should change each time a JWT is generated.	Y
iat	Issued At - The epoch time in seconds of when the JWT was generated. This allows us to determine how long a JWT has been around and whether we consider it expired or not.	Y
iss	Issuer - An identifier of who is issuing the JWT. This should be your API Key.	Y
OrgUnitId	Your SSO OrgUnitId	Y
ReferenceId	This is a reference identifier that allows Cardinal FIDO to match data between multiple calls. It should carry over from the enrollment check carried out previously. See Checking for FIDO Enrollment for more information.	Y
ReturnUrl	A URL you will define that specifies the location where you will receive the consumer session back after the Enroll call has finished	Y

Request Payload Object

Field	Type	Description	Required

Field	Type	Description	Required
Amount	String	The raw amount of the transaction that is being authenticated. This value will be displayed to the end user during authentication for verification.	Y
CurrencyCode	String	The ISO currency code that the transaction is being completed in. This value will be used to format the `Amount` field during authentication.	Y
MerchantName	String	The name of the merchant making the request. This value will be displayed to the end user during authentication for verification.	Y

Sample Transact Request

{
  "jti": "ed380500-8395-11ec-9bed-0b198567a5f0",
  "iat": 1643744049,
  "iss": "MyMerchant-Api-Key-Id",
  "OrgUnitId": "59c2745f2f3e7357b4aa516a",
  "ReferenceId": "c2ed0882-9c8e-482d-92bc-2d6c0c9658ef",
  "ReturnUrl": "https://myWebsite.com/fido/returnUrl",
  "Payload": {
    "Amount": "1000",
    "CurrencyCode": "840",
    "MerchantName": "My Test Merchant Name"
  }
}

Transact Response JWT

The transact endpoint will return the response as a JWT like many other Centinel API endpoints. 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 within the Centinel API for more information on handling JWT responses.

Response Payload Object

Field	Type	Description

Field	Type	Description
UserAuthenticated	boolean	A flag to indicate if the user successfully completed authentication
ReferenceId	String	This is echoed back from the POST
ErrorNumber	Number	Application error number; a non-zero value represents the error encountered while attempting the process the message request. See `ErrorDescription` below for possible values
ErrorDescription	String	A text description of the `ErrorNumber` field 0: `"Success"` 1000: `"Error processing request. We have encountered an unexpected error."` 6101: `"User Cancelled"` Indicates that a user cancelled out of the enrollment process 6100: `"Error during FIDO processing"` Indicates an internal error related to VLS or Cardinal integration 9000: `"Error in Service"` Indicates a service-level error 9999: `"System Error"`

Sample Transact Response

{
    "iss": "MyMerchant-Api-Key-Id",
    "iat": 1643744051,
    "exp": 1643751251,
    "jti": "2817edaf-0735-4d28-93fb-85265f104df8",
    "aud": "ed380500-8395-11ec-9bed-0b198567a5f0",
    "Payload": {
        "UserAuthenticated": true,
        "ErrorNumber": 0,
        "ErrorDescription": "Success",
        "ReferenceId": "c2ed0882-9c8e-482d-92bc-2d6c0c9658ef"
    }
}

CMPI Lookup

The cmpi_lookup call is part of the Centinel Core API. An overview of this request call and its responses can be found in our cmpi_lookup documentation. The cmpi_lookup has required fields and extra, conditional fields that allow it to be configured for a specific purpose. Both the Email and CardNumber (PAN) are already required fields in the cmpi_lookup, and these fields must match what was sent earlier in the registration check.

Conditional FIDO Fields for cmpi_lookup

In the context of the FIDO Confirmation Flow, two extra conditional fields will need to be sent. Note that, as with other conditional cmpi_lookup fields, these should not be incorporated globally into all cmpi_lookup requests.

Field	Type	Description	Required

Field

Type

Description

Required

DFReferenceId

String

The ReferenceId returned in the DX API call

Y

ChallengeIndicator