Once FIDO has been configured and integrated, customers can be enrolled in FIDO using the FIDO enrollment flow. The enrollment flow follows four general steps, outlined below:

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 false, 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.
Successful transaction using Strong Customer Authentication (SCA)
A FIDO enrollment requires that a successful SCA through Cardinal occurs immediately before enrollment is run. This will be tied to the rest of the process by using the same Email, AccountNumber, and ReferenceId from Step 2.
FIDO Enroll
The user is prompted for FIDO enrollment, which triggers a FIDO Enroll request to the Centinel API using the ReferenceId from step 2 and CentinelTransactionId from Step 4. Biometric data is gathered from the client in this step.

This article will focus primarily on step 5, the FIDO Enroll endpoint, which is handled through the Centinel API. FIDO compatibility and the DataExchange API call that checks prior enrollment are dealt with in separate pages in FIDO. Step 3, the SCA transaction, is not substantially different from a normal Cardinal EMVCo 3DS authentication.

From the time that the registration check returns, the FIDO session represented by the ReferenceId is valid for 20 minutes. After this time, FIDO enrollment cannot continue.

Table of Contents

Table of Contents
1 Device Data Collection (DDC) 2 Centinel API FIDO Enroll Endpoint 2.1 Connection URLS 2.2 Endpoints 3 Enroll Request JWT Fields 3.1 Payload Object Fields 3.2 Sample Enroll Request 4 Enroll Response JWT 4.1 Response Payload Object 4.2 Sample Enroll Response 5 Completing Enrollment 5.1 completeEnrollment Function 5.1.1 Sample completeEnrollment Function 5.2 completeEnrollment Responses

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 Enroll Endpoint

The final stage of the FIDO enrollment flow should be triggered by the user opting into the FIDO program via an “enroll in FIDO” prompt. Note that the opt-in screen is something that you will need to put in place. Once the user opts in, a call will need to be made to the Enroll endpoint. Like many other endpoints in the Centinel API, the Enroll endpoint takes in and returns a JWT.

When the POST is made to Enroll, the Centinel API will make a basic eligibility check before moving forward, which checks that the first two stages of the FIDO enrollment flow have occurred:

User must be on a FIDO-compatible device.
The user should not previously be registered with FIDO with this email/PAN combination. This will be reflected in the DX API response "Registered": false (see Checking for FIDO Enrollment)
The user’s transaction prior to enrollment must go through Strong Consumer Authentication (SCA)

Below is a simplified sequence diagram of the flow of FIDO enrollment once the Enroll endpoint is called:

Fido Enrollment Process

Connection URLS

Environment	URL

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

Endpoints

Endpoint	Path

Endpoint	Path
Enroll	/V1/Fido/Enroll

Enroll Request JWT Fields

The Enroll 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 Enroll JWT has a Payload object that contains Transact-specific claims, as well as two extra claims in the main body: ReferenceId and ReturnURL.

Field	Type	Description	Required

Field	Type	Description	Required
jti	String	JWT Id - A unique identifier for this JWT. This field should change each time a JWT is generated.	N
iat	String	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. JWTs are good for no more than 4 hours.	Y
iss	String	Issuer - An identifier of who is issuing the JWT. This should be your API Key.	Y
OrgUnitId	String	Your SSO OrgUnitId	Y
ReferenceId	String	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	String	A URL you will define that specifies the location where you will receive the consumer session back after the Enroll call has finished	Y
Payload	Object	See Below	Y

Payload Object Fields

Field	Description	Required

Field	Description	Required
CentinelTransactionId	The TransactionId for the transaction immediately preceding enrollment. This transaction needs to use Strong Customer Authentication (SCA) for FIDO enrollment to proceed.	Y

Sample Enroll Request

{
    "jti": "a5a59bfb-ac06-4c5f-be5c-351b64ae608e",
    "iat": 1448997865,
    "iss": "56560a358b946e0c8452365ds",
    "OrgUnitId": "565607c18b946e058463ds8r",
    "ReferenceId": "074fda80-5048-11e6-8c35-8789b865ff15",
    "ReturnUrl": "https://mywebsite.com/confirmHandler",
    "Payload": {
        "CentinelTransactionId" : "asxacavcasvaevvwv"
    }
}

Enroll Response JWT

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

Response Payload Object

Field	Type	Description

Field	Type	Description
ErrorNumber	Integer	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	Error description for the corresponding `ErrorNumber` Possible Values: 0: `"Success"` 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
UserEnrolled	Boolean	Indicates whether the user has been successfully enrolled in FIDO
ReferenceId	String	This is echoed back from the POST
UserId	String	A value used to link the customer’s device in future transactions. It will be passed on to the completeEnrollment function in the next step to become part of the cookie information.

Sample Enroll Response

{
    "iss": "MyMerchant-Api-Key-Id",
    "iat": 1643744051,
    "exp": 1643751251,
    "jti": "2817edaf-0735-4d28-93fb-85265f104df8",
    "aud": "ed380500-8395-11ec-9bed-0b198567a5f0",
    "Payload": {
        "ErrorNumber": 0,
        "ErrorDescription": "Success",
        "UserEnrolled": true,
        "ReferenceId": "074fda80-5048-11e6-8c35-8789b865ff15",
        "UserId": "abc123ish2826"
    }
}

Completing Enrollment

The FIDO SDK is used to finalize device enrollment. The SDK inserts a cookie value into the customer’s browser to identify them in future transactions. Cookies are not the only method used to identify the browser, but they are the most consistent. Failure to complete this step can result in previously enrollment users being forced down the enrollment flow again.

completeEnrollment Function

The completeEnrollment function is a promise that takes in a single argument, UserId.

Field	Type	Description	Required

Field	Type	Description	Required
UserId	String	This is the `UserId` field returned in the Enroll Response above.	Y

Sample completeEnrollment Function

Promise = CardinalFido.completeEnrollment({ UserId: "" })

completeEnrollment Responses

A successful completeEnrollment response will simply resolve the promise. If an error occurs, the promise will be rejected along with an error message.

Error Message	Error Type	Description

Error Message	Error Type	Description
Invalid enrollment object	Input Validation	Argument passed to function was not an object as expected
Invalid UserId	Input Validation	The UserId property on the argument object was not formatted as expected
Unexpected exception: <Exception Message>	Exception	An unexpected exception was thrown and caught. The exception message will be concatenated to the end of the error message

Cardinal Cruise

Enrolling Users in FIDO