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

Table of Contents

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

Environment	URL
Staging	https://dataexchangestag.cardinalcommerce.com
Production	https://dataexchange.cardinalcommerce.com

Endpoints

Endpoint	Path
GetInfo	/V1/AccountNumber/GetInfo

GetInfo Request Fields for FIDO

Field	Description	Required
Signature	Base64 encoded SHA256 or SHA512 value that is a hash of timestamp, TransactionId, and API Key. 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
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
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: `ReferenceId` field `Issuer` object `Account` object `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": {
                "Registered": true
            }
        },
        "Issuer": {
            "SupportedVersions": [
                {
                    "Version": "2.1.0",
                    "Capabilities": [
                        "AuthenticationAvailableAtACS"
                    ],
                    "MethodURLPresent": true
                },
                {
                    "Version": "2.2.0",
                    "Capabilities": [
                        "AuthenticationAvailableAtACS",
                        "DataOnly",
                        "DelegatedAuthentication",
                        "DelegateTrustedAuthentication"
                    ],
                    "MethodURLPresent": true
                }
            ]
        },
        "ReferenceId": "12d203e1-9a71-45b8-a3f0-1ee509c42f46"
    }
}

Payload Details

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
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 with FIDO Sub-object

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` Note that currently, Visa is the only network supporting FIDO. As other networks adopt the protocol, this is how they will appear in this context.	String	Y
Fido	This sub-object contains a single Boolean field, "Registered" This object will only be returned if enrollment can move forward. As mentioned above, this step is checking two factors regarding FIDO capability: Card issuer must support Delegated Authentication Both the acquirer and the issuer must be in a region supported by Cardinal FIDO	Object	C
Fido.Registered	Indicates whether the PAN/device combination has already been enrolled in FIDO	Boolean	C

Checking for FIDO Enrollment

DX API GetInfo Endpoint

Connection URLs

Endpoints

GetInfo Request Fields for FIDO

Sample GetInfo Request

Payload Details

GetInfo Response Fields for FIDO

Sample GetInfo Response

Payload Details

Issuer Object

Account Object with FIDO Sub-object