FIDO Authentication

When you use a gateway token which is associated to an network token for payments or create a gateway token associated with an network token, EVO Cloud supports FIDO authentication.

What is FIDO Authentication

• Developed by the FIDO Alliance that sets the global authentication standard based on public key cryptography.
• Token Authentication is a FIDO compliant solution to support consumer authentication using passkeys.

FIDO solution

A transaction that qualifies for FIDO Authentication can go through either a registration flow or a identification flow, depending on whether the user's device has the corresponding passkey stored.

FIDO Authentication Registration Flow

When users link a token to their device and use FIDO authentication for the first time, they will be asked to verify their identity (e.g., through 3DS authentication). Once the authentication is successful, the page will prompt the cardholder to store the passkey on their device for future authentication.

FIDO Authentication Registration Flow is applicable for creating a token through a paymentMethod request and creating a token when making a payment through a payment request.

FIDO Authentication Identification Flow

When a user initiates a transaction using a token already linked with a passkey, FIDO will authenticate their identity directly through biometric technology.

FIDO Authentication Implementation

Step 1: Collect additional parameters

Except the basic parameters collected in Payment / Tokenization, you need to collect additional information from your user to perform FIDO authentication. See Step 2 in chapter for more details.

Step 2: Make a payment or tokenization

With the additional parameters collected, make an HTTP POST request from your server to EVO Cloud endpoint /g2/v1/payment/mer/{sid}/payment for payment. Or to /g2/v1/payment/mer/{sid}/paymentMethod for tokenization.

Here are the additional parameters required in the request for FIDO authentication:

Body parameter	Required	Description
authentication	M	The information used for user authentication before payment or tokenization.
transInitiator	C	Mandatory for payment. The information used for user authentication before payment or tokenization.
userInfo	C	Mandatory for payment. The information used for user authentication before payment or tokenization.
returnURL	M	The URL to redirect your customer back to after your customer completes the authentication.
allowAuthentication	O	Applied when your store is configured as Optional-Authentication. In POST /g2/v1/payment/mer/{sid}/payment request or POST /g2/v1/payment/mer/{sid}/paymentMethod request to indicate whether the payment needs to conduct authentication.

More details about the authentication object:

1. authentication.type: The authentication mode applied for this payment, optional. You need to specify it as FIDOPage, threeDSPageOrFIDOPage or threeDSIntegratorOrFIDOPage to inform EVO Cloud that you want to use the redirection solution for FIDO Authentication.

   authentication.type	Description
   FIDOPage	This transaction is applied to Mastercard SCOF(Secure Card on Filed) TAS(Token Authentication Services) using EVO Cloud authentication page.
   threeDSPageOrFIDOPage	This transaction is applied 3DS authentication using EVO Cloud authentication page or Mastercard SCOF(Secure Card on Filed) TAS(Token Authentication Services) using EVO Cloud authentication page. EVO Cloud will auto determine which is applied to this transaction.
   threeDSIntegratorOrFIDOPage	This transaction is applied 3DS authentication using full API connection with EVO Cloud or Mastercard SCOF(Secure Card on Filed) TAS(Token Authentication Services) using EVO Cloud authentication page. EVO Cloud will auto determine which is applied to this transaction.

More details about the transInitiator object:

1. transInitiator.userCreateIP: Unique string of characters that identifies a device. Support V4 or V6.
2. transInitiator.latitude and transInitiator.longitude: These fields are optional. These fields should contain the latitude and longitude coordinates of the device where user is attempting to payment. Required for FIDO Authentication unless the consumer has declined to share his/her location.

More details about the userInfo object:

1. userInfo.mobilePhone: User's phone number. Mandatory if no email address(userInfo.email) is provided.
2. userInfo.email: User's email address. Mandatory if no phone number(userInfo.mobilePhone) is provided.

Here is an example of making a 10 USD payment with Gateway token requiring FIDO authentication:

curl -L 'https://hkg-online-uat.everonet.com/g2/v1/payment/mer/S003770/evo.e-commerce.payment' \
-H 'Content-Type: application/json' \
-H 'DateTime: 2024-09-20T15:30:49+08:00' \
-H 'SignType: SHA256' \
-H 'Authorization: 7d12db50addafe79c2dc91001768952ae2d1042c23871c72a7a62cbd11aa20bd' \
-H 'MsgID: M202409201726817449809' \
-H 'Cookie: acw_tc=0bdd894a17266535114292492e618e5540f5852f3134e66b6b2ed7005974cf' \
--data-raw '{
    "allowAuthentication":true,
    "returnURL": "https://www.xunliandata.com",
    "merchantTransInfo": {
        "merchantTransID": "T409201726817442425",
        "merchantTransTime": "2024-09-20T15:30:42+08:00"
    },
    "transAmount": {
        "currency": "HKD",
        "value": "1.00"
    },
    "captureAfterHours":"0",
    "paymentMethod": {
        "type": "token",
        "token":{
            "value":"pmt_74ed444f29ac4421a169db61cc6ee95e"
        }
    },
        "authentication":{
        "type":"FIDOPage"
    },
    "userInfo":{
        "email":"evocloud@cardinfolink.com"
    },
    "transInitiator": {
        "platform": "WEB",
        "userCreateIP":"140.206.99.254"
    },
    "metadata": "This is a metadata",
    "webhook": "https://YOUR_COMPANY.com/WEBHOOK"
}'

If you don't receive an action object in the response, use the result.code and payment.status / paymentMethod.token.status to present the payment / tokenization result to your user. Otherwise, additional steps are required to complete the payment / tokenization, you need to send the action object to your web frontend or client APP, then proceed to the next step. Here is an example of the response of the payment that requires a redirection:

{
    "action": {
        "redirectData": {
            "method": "GET",
            "url": "https://hkg-counter-uat.everonet.com/intermediate?FIDOPsp=Mastercard&evoTransID=99c8fda971c8483a902a401c72ee7384&merchantTransID=T409181726653634865&insCode=90000018&sid=S90000000000001&paymentString=eyJzcmNDbGllbnRJZCI6ImQ5ZDhkZGZhLWQwNzctNDJlZi05NjljLWMyMmIwOGIyZDNjOSIsInNlcnZpY2VJZCI6IlNFQ1VSRV9DT0ZfTUVSQ0hBTlRfT0JPI0VWT05FVF9TQ09GX09CTy1KT1JHX01FUkNIQU5UX1RFU1QwMiMwMSIsInNyY0NvcnJlbGF0aW9uSWQiOiJlZjU5N2IwYS0zNjFmLTRkNTMtYjhiZC04MmUxM2I4MmQ1YWMiLCJzcmNpVHJhbnNhY3Rpb25JZCI6IlQ0MDkxODE3MjY2NTM2MzQ4NjUiLCJhdXRoZW50aWNhdGlvbk1ldGhvZCI6eyJhdXRoZW50aWNhdGlvbk1ldGhvZFR5cGUiOiJNQU5BR0VEX0FVVEhFTlRJQ0FUSU9OIiwibWV0aG9kQXR0cmlidXRlcyI6eyJ1cmlEYXRhIjp7InVyaSI6Imh0dHBzOi8vc2FuZGJveC5zcmMubWFzdGVyY2FyZC5jb20vYXV0aCJ9fX0sImFjY291bnRSZWZlcmVuY2UiOnsic3JjRGlnaXRhbENhcmRJZCI6Ikh5bDBpLWU4VFJhSkFVSHZScHNlN3cwMDAwMDAwMDAwMDBVUyJ9LCJhdXRoZW50aWNhdGlvbkNvbnRleHQiOnsiYXV0aGVudGljYXRpb25SZWFzb25zIjpbIlRSQU5TQUNUSU9OX0FVVEhFTlRJQ0FUSU9OIl0sImFjcXVpcmVyTWVyY2hhbnRJZCI6IlMwMDAwMDAwMDAwMDQwMyIsImFjcXVpcmVyQklOIjoiMDMxNjQxIiwic3JjRHBhSWQiOiI5MDQ1MTkwMC1TMTIzNDU2NyIsImRwYVRyYW5zYWN0aW9uT3B0aW9ucyI6eyJtZXJjaGFudENhdGVnb3J5Q29kZSI6IjMwMDEiLCJtZXJjaGFudENvdW50cnlDb2RlIjoiSEsiLCJ0cmFuc2FjdGlvbkFtb3VudCI6eyJ0cmFuc2FjdGlvbkFtb3VudCI6IjEuMDAiLCJ0cmFuc2FjdGlvbkN1cnJlbmN5Q29kZSI6IkhLRCJ9fSwiZHBhRGF0YSI6eyJkcGFOYW1lIjoiSm9yZyBVQVQifX19&FIDOAuthURL=aHR0cHM6Ly9zYW5kYm94LnNyYy5tYXN0ZXJjYXJkLmNvbS9hdXRo&returnUrl=aHR0cHM6Ly93d3cueHVubGlhbmRhdGEuY29t"
        },
        "type": "redirectUser"
    },
    "authentication": {
        "type": "FIDOPage"
    },
    "metadata": "This is a metadata",
    "payment": {
        "evoTransInfo": {
            "evoTransID": "99c8fda971c8483a902a401c72ee7384",
            "evoTransTime": "2024-09-18T10:00:34Z",
            "retrievalReferenceNum": "426218633791",
            "traceNum": "633791"
        },
        "merchantTransInfo": {
            "merchantTransID": "T409181726653634865",
            "merchantTransTime": "2024-09-18T18:00:34+08:00"
        },
        "pspTransInfo": {
            "pspTransTime": "2024-09-18T10:00:34Z"
        },
        "status": "Verifying",
        "transAmount": {
            "currency": "HKD",
            "value": "1.00"
        }
    },
    "paymentMethod": {
        "card": {
            "first6No": "222300",
            "fundingType": "credit",
            "issuingCountry": "USA",
            "last4No": "4586",
            "paymentBrand": "Mastercard"
        },
        "isNetworkToken": true,
        "networkToken": {
            "expiryDate": "1027",
            "first6No": "222300",
            "last4No": "2087",
            "paymentAccountReference": "50018Q5LHFGJZDRKN3TB2FW568FIB",
            "status": "enabled",
            "supportDeviceBinding": false,
            "tokenID": "Hyl0i-e8TRaJAUHvRpse7w000000000000US",
            "tokenReferenceID": "DM4MMC1US0000000fb57e70d231c4faca20d54713f643a26"
        },
        "paymentMethodVariant": "COF",
        "token": {
            "createTime": "2024-09-12T16:43:31+08:00",
            "expiryDate": "2025-09-12T16:43:31+08:00",
            "first6No": "222300",
            "last4No": "2087",
            "status": "enabled",
            "updateTime": "2024-09-12T16:44:50+08:00",
            "userReference": "1234abcd",
            "value": "pmt_74ed444f29ac4421a169db61cc6ee95e",
            "vaultID": "0724"
        }
    },
    "pspData": {
        "merchantID": "S00000000000403",
        "name": "Mastercard"
    },
    "result": {
        "code": "S0000",
        "message": "Success"
    }
}

Step 3: Process redirectUser

For the redirection solution for FIDOPage, usually the action.type you received in the response is redirectUser, meaning that you need to redirect the user to an EVO Cloud hosted page to complete the FIDO authentication with action.redirectData in the same response.

A. Redirect user to EVO Cloud hosted page

Redirect the user to the action.redirectUser.url with HTTP method specified in action.redirectUser.method.
Here is an example of performing redirectUser action on your frontend when action.redirectUser.method is GET:

curl {action.threeDSData.url}

Please note that the user is then redirected to an EVO Cloud hosted page, and then EVO Cloud will process the following FIDO authentication procedures with the user and card scheme.

B. Redirect back after user completes the authentication

The user will be redirected back by EVO Cloud to your returnURL, and then you can use the parameter merchantTransID in the response to match your initial request. If the parameter status in the response is finished, you can view the FIDO authentication is successful, and you need to obtain the transaction detail by requesting GET interface or receive the notification from EVO Cloud. If you don’t get any response within 10 minutes, or the parameter status is not finished, you can view the FIDO authentication is failed, and you need to obtain the transaction detail by requesting GET interface or receive the notification from EVO Cloud.

Step 4: Present the result

After the user completes the payment or tokenization and no further actions are required on the frontend or client APP, you can use the result.code and payment.status / paymentMethod.status to inform your user of the payment or tokenization status.

Result Code	Description
S0000	Success
V0007	Missing field {} when
B0025	Authentication not finished
B0026	3DS version not supported

For other possible result.code values and recommended messages to present to users, see the Appendix in the EVO Cloud API Specification.

If the result.code is S0000, you need to check the payment.status / paymentMethod.status to determine and inform your user of the payment or tokenization status.

Status (payment)	Description
Authorised	Used for card transactions; means the transaction authorization is successfully completed and pending for capture (merchant can submit cancel).
Captured	For card transaction, means transaction authorization and capture are successfully completed
Failed	Payment failed.

Status (paymentMethod)	Description
Success	Means the token is created.
Failed	Means token creation has failed.

For other possible payment.status / paymentMethod.status values and descriptions, see the payment.status / paymentMethod.status section in the EVO Cloud API Specification.

Error handling

For HTTP POST request to EVO Cloud: It is suggested to wait at least 45 seconds after the request is sent to EVO Cloud. If you don’t get the response within the time frame, you need to retrieve the result from EVO Cloud. See Step 6 in chapter Payment / Tokenization to initiate the request. For HTTP PUT request to EVO Cloud: The HTTP PUT request is idempotent, meaning that if you don’t get the response from EVO Cloud within a certain time frame, for example 45 seconds, you can resend the request with exactly the same request message. If you still fail to get the response after several times of the request, you can trigger another payment / tokenization request instead.