Checking for FIDO Enrollment

Cardinal Commerce FIDO uses our Data Exchange API (DX API) to determine whether a user is already enrolled in FIDO. 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 FIDO, the DX API’s GetInfo endpoint is leveraged to determine the FIDO enrollment status of a Device/PAN combination, as well as what authentication programs are supported by the PAN’s ACS.

For a more complete discussion of DX API, see the following article: Data Exchange API

 

DX API GetInfo Endpoint

GetInfo will be the primary endpoint used in the FIDO process. A POST to this endpoint will consist of identifying information and a payload containing both account information as well as a special FidoSetupPayload specifying additional information needed to determine FIDO status.

Connection URLs

Endpoints

Endpoint

Path

Endpoint

Path

GetInfo

/V1/AccountNumber/GetInfo

 

GetInfo Request Fields for FIDO

Field

Description

Required

Field

Description

Required

Signature

A mathematical scheme for verifying the authenticity of digital messages or documents.

For more information on generating this signature, see Data Exchange API: Signature

Y

Timestamp

This value can be a standard date/time format or, Java Epoch time in milliseconds

Example:"2017-07-21T17:32:28Z" or, 1626113191

Y

Identifier

API Key Identifier or Name value

Y

Algorithm

The hashing algorithm used to generate the Signature value. Valid options include:

  • SHA-256

  • SHA-512

Y

TransactionId

A unique alphanumeric identifier. Will be echoed back in the response in Payload.RequestId

5-55 characters in length

Y

OrgUnitId

Merchant level OrgUnitId

Y

Payload

The Payload for FIDO transactions will contain a card number and possibly a card brand like all GetInfo calls. FIDO calls will have two extra pieces of information as well: an email address, and a fidoSetupPayload. See below for more details on the Payload

Y

Sample GetInfo Request

{ "Algorithm": "SHA-256", "Identifier": "59c2745f2f3e7357b4aa516a", "OrgUnitId": "564cdcbcb9f63f0c48d6387f", "Signature": "4LeQr8F0bzh0f7XKesH9D7EIjT+s/Inx+eO1TrwMKNI=", "Timestamp": "2017-07-21T17:32:28Z", "TransactionId": "265d92d0-3868-4704-8731-b850d42ce00a", "Payload": { "AccountNumber": "4000090000000094", "CardType": "CB", "FidoSetupPayload": "Setup_Payload_Here", "Email": "test@cardinal.com" } }

 

Payload Details

Field

Description

Required

Field

Description

Required

AccountNumber

This will either be the full PAN or full network token of the card for the transaction

Y

CardType

Type of card used in the transaction

Possible Values:

CB - Cartes Bancaires
UPI - UnionPay International

ITMX - National ITMX

For all other brands, CardType should not be sent

Visa is currently the only network to have adopted FIDO. The DX API is a general purpose API and has uses outside FIDO. When these networks begin using FIDO, these CardType values will need to be sent. Until then, CardType will not be sent in FIDO transactions.

Conditional (see Description)

Email

Email address of the cardholder

Y

FidoSetupPayload

This portion of the payload is a Base64 encoded string received as a response back to CardinalFido.Setup(). This field will only be passed back if the device is detected as FIDO compatible

Y

 

GetInfo Response Fields for FIDO

Field

Description

Type

Required

Field

Description

Type

Required

RequestId

A request identifier returned back from Cardinal

String

Y

ErrorNumber

Application error number; a non-zero value represents the error encountered while attempting the process the message request. See ErrorDescription below for possible values.

String

Y

ErrorDescription

Application error description for the associated error number

Possible Values:

  • 0 : Success

  • 2000 : AccountNumber is not valid

  • 1000 : An error has occurred in the Service

 

 

String

 

 

Y

Payload

The Payload for the Data Exchange API response will contain:

  1. ReferenceId field

  2. Issuer object

  3. Account object

    1. Fido object

Note that the FIDO object is only returned if several conditions are met. Browser and hardware compatibility has been previously checked, but two more checks are made during this stage to determine whether a Fido object will be included in the response:

  • The card issuer must support Delegated Authentication

  • Both the acquirer and the issuer must be in a region supported by Cardinal FIDO

 

 

Payload Object

 

 

Y

Sample GetInfo Response

{ "ErrorNumber": 0, "ErrorDescription": "Success", "RequestId": "265d92d0-3868-4704-8731-b850d42ce00a", "Payload": { "Account": { "CardBrand": "Visa", "LastFour": "0094", "Fido": { "FlowType": "ENROLLMENT" } }, "Issuer": { "SupportedVersions": [ { "Version": "2.1.0", "Capabilities": [ "AuthenticationAvailableAtACS" ], "MethodURLPresent": true }, { "Version": "2.2.0", "Capabilities": [ "AuthenticationAvailableAtACS", "DataOnly", "DelegatedAuthentication" ], "MethodURLPresent": true } ] }, "ReferenceId": "12d203e1-9a71-45b8-a3f0-1ee509c42f46" } }

 

Payload Details

Field

Description

Type

Required

Field

Description

Type

Required

ReferenceId

This identifier represents the Device Data Collection session that has been started and must be passed in the Authentication JWT when invoking Device Data Collection

See Device Data Collection for more information on the Device Data Collection API.

 

String

 

Y

Issuer

Contains information related to the Issuer

Object

Y

Account

Contains information related to the Account. When fidoSetupPayload is sent in the request, this will contain an additional sub-object, “Fido”

Object

Y

RequestId

Echoes the TransactionId on the DX GetInfo request

String

Y

Issuer Object

Field

Description

Type

Required

Field

Description

Type

Required

SupportedVersions

Encompasses Issuer information based on the PRes received from each card network

Array of Objects

Y

SupportedVersions.Version

Specifies all active 3DS protocol versions supported by the Issuer ACS

String

Y

SupportedVersions.Capabilities

Provides information related to the Issuer Capabilities supported for each 3DS version

Array

O

SupportedVersions.MethodURLPresent

Indicates whether there is a 3DS Method associated with the Issuer Range

If the MethodUrlPresent flag returns ‘false’, you can elect to skip Device Data Collection and proceed with the Lookup Request call if you are able to capture the required browser fields on your own

Boolean

Y

Account Object

Field

Description

Type

Required

Field

Description

Type

Required

LastFour

Echoes the last four numbers of the AccountNumber field passed on the Data Exchange API request payload

String

Y

CardBrand

Type of card used for the purchase.

Possible Values:

  • Visa

  • Mastercard

  • Amex

  • CB

  • JCB

  • Discover

  • ELO

  • UPI

  • ITMX

  • EFTPOS

Cardinal FIDO authentication is currently only supported on Visa cards. More card networks will be onboarded in the future.

String

Y

Fido

This sub-object contains a single string field, "FlowType"

FlowType indicates whether the cardholder has previously been enrolled in FIDO, as well as what type of enrollment UI experience the cardholder may be guided through. In order for FIDO to move forward, the following must be true:

  • Card issuer must support Delegated Authentication

  • Both the acquirer and the issuer must be in a region supported by Cardinal FIDO

Object

C

Fido.FlowType

Indicates what type of flow the cardholder should be moved through. This is a key piece of information determining how to move forward in the transaction. The possible FlowType responses are outlined below.

String

C

FlowType Responses

The FlowType field in the FIDO object has several possible responses. The response returned will determine whether the you will need to invoke the Enroll or Transact endpoints. While only one response will result in the Transaction flow, several will result in being moved through the Enrollment flow, with the main difference being what UI details they should be shown.

In checking for FIDO enrollment, the cardholder email is used as the base identifier in a transaction. If a cardholder’s email has not previously been registered, the ENROLLMENT response will be given and a new enrollment will be required. However, if the cardholder’s email has been previously enrolled, both the device and PAN can change. In these cases, different versions of the enrollment flow will be followed to capture the new information and bind it to the cardholder’s existing email.

FlowType

Invoke Endpoint

Enrollment Status

Description

FlowType

Invoke Endpoint

Enrollment Status

Description

TRANSACTION

Transact

EMAIL: Enrolled
DEVICE: Enrolled
PAN: Enrolled

Cardholder has previously been enrolled in FIDO with this device/PAN/email combination. No further enrollment action is required, and they can be moved to a FIDO transaction using the Transact endpoint.

ENROLLMENT

Enroll

EMAIL: New
DEVICE: --
PAN: --

Cardholder has not previously been enrolled in FIDO.
Cardholder will need to be taken through an SCA transaction, then should be given a prompt to enroll in FIDO. If they accept, the Enroll endpoint should be invoked and they will be moved into the Enrollment flow.

ADD_NEW_DEVICE

Enroll

EMAIL: Enrolled
DEVICE: New
PAN: Enrolled

Cardholder has previously been through the enrollment flow and their email has been registered, but they are on a new device which will need to be registered. Cardholder will need to be taken through an SCA transaction, then should be given a prompt to add a new device/authenticator. If they accept, the Enroll endpoint should be invoked and they will be moved into the “Add New Device” flow.

ADD_PAN

Enroll

EMAIL: Enrolled
DEVICE: Enrolled
PAN: New

Cardholder has previously been through the enrollment flow and their email has been registered, but they are using a new PAN for this transaction which will need to be registered.
Cardholder will need to be taken through an SCA transaction, then should be given a prompt to add a new PAN. If they accept, the Enroll endpoint should be invoked and they will be moved into the “Add New PAN” flow.

ADD_NEW_DEVICE_AND_PAN

Enroll

EMAIL: Enrolled
DEVICE: New
PAN: New

Cardholder has previously been through the enrollment flow and their email has been registered, but they are using a new PAN and a new device for this transaction. Both the PAN and the device will need to be registered.
Cardholder will need to be taken through an SCA transaction, then should be given a prompt to add a new device/authenticator (the same prompt as ADD_NEW_DEVICE above). If they accept, the Enroll endpoint should be invoked and they will be moved into the “Add New Device and PAN” flow.

Flow Type Responses Flowchart