Skip to main content

Authentications

Passing transaction and cardholder data for authentication

The Authentications request body is the heart of the authentication process. It can contain information about the merchant, cardholder, transaction, client browser, and preferences for how the authentication and a potential challenge is to be handled. The smallest authentication request body is about the same size as what is necessary for an authorization or purchase request to payment gateway and those requests share a lot of the same data. The data elements required for an authentication request are determined by the transaction type (Message Categories), authentication type (Requestor Authentication Indicator), transaction origination (Device Channel), and which (3DS version) of the EMVCo specification is to be used.

Message Categories​

All authentication requests are either a Payment Authentication (PA) or Non-Payment Authentication (NPA). Examples of PA requests are purchases for goods or services, account funding, prepaid activation and load, check acceptance, or quasi-cash transactions. NPA requests are for situations where identity verification and account confirmation are desired, but no monetary transaction is occurring. An example of an NPA request is adding a card to a mobile wallet, where the authentication can happen outside the payment process.

Requestor Authentication Indicator​

The Authentication Indicator goes further than the Message Category to specify what type of authentication is being requested: a one-time payment transaction, a recurring transaction, installment transaction, adding a card to a mobile wallet, maintaining card information on file, or cardholder verification. This data element provides additional context for the ACS to determine the best approach for handling an authentication request.

Device Channel​

The device channel is the source of the authentication request. There are three device channels: App, Browser (BRW), and 3DS Requestor Initiated (3RI). TokenEx currently supports Browser and 3RI.

  • App - transaction is originating from a mobile app provided by the 3DS requestor.
  • Browser - transaction is originating from a website utilizing a browser.
  • 3RI - merchant-initiated confirmation of account information and cardholder authentication with no direct cardholder present. For example, a subscription-based merchant confirming an account is still valid prior to a recurring purchase.

3DS Version​

TokenEx supports EMVCo 3-D Secure versions 2.1.0 and 2.2.0. The full specifications for these versions can be downloaded as PDFs here.
When building your request body, use the TokenEx property corresponding to the EMVCo spec's property. If additional research is needed to build a specific request body, the TokenEx : EMVCo Property Mapping can be used to assist.

Version 2.2.0 introduces additional data elements, support for Decoupled Authentication, Delegated Authentication, and low-exemption requests based off transaction risk analysis (TRA) or Trusted Merchant (whitelist) status.

TokenEx is unable to perform 3DS authentication for cards not enrolled in 3DS versions 2.1.0 or 2.2.0,
Use Supported Versions to check a card's enrollment status before building the authentication request.

Version Validations​

TokenEx will validate the request against the version specified by the MessageVersion property before 3DS processing, returning an error response specific to the version when necessary. If the MessageVersion property is omitted, TokenEx will attempt validation against 2.2.0 first, falling back to 2.1.0 if unsuccessful. If 2.1.0 validations are also unsuccessful, an error response specifying the issue will be returned.

Construct Request​

Test URI: https://test-api.tokenex.com/v2/ThreeDSecure/Authentications
Prod URI: https://api.tokenex.com/v2/ThreeDSecure/Authentications

Required Permissions: ThreeDSecureGeneralAccess

Request Headers: Authentication and Authorization* denotes a required field

HTTP Request HeaderDescription
tx-tokenex-id*Like a username, this ID logically segments your tokenized data.
tx-apikey*Controls access to individual functions of the API
tx-token-schemeEither the name or the numerical value of the Token Scheme to be used
tx-tokenizeTrue/False. Defaults to False. If False, a TokenEx token can be provided in the "number" parameter within the "CardDetails" object. If True, a PAN can be provided, and a TokenEx token will be returned in the response using the token scheme as indicated by the tx-token-scheme header.

Request Body Creation​

When building the authentication request there are a couple best practices:

  • If the data is available, send it. More data reduces the risk of a challenge.
  • Never send junk data. Junk data can prompt unnecessary challenges and authentication failures.

All Authentications request properties (TokenEx : EMVCo)

Linking Device Fingerprint to Authentication

Link a device fingerprint to the authentication by sending the threeDSServerTransID from either the SupportedVersions threeDSecureResponse or Iframe Tokenize event's threeDSecureResponse in the ServerTransactionId parameter.

Request Examples​

POST /[Test|Prod]/ThreeDSecure/Authentications HTTP/1.1
Content-Type: application/json
tx-tokenex-id:YourTokenExID
tx-apikey:YourAPIKey
tx-token-scheme:GUID
tx-tokenize:false

{
  "ServerTransactionId": "value from prior threeDSecureResponse",
  "MethodCompletionIndicator": 2,
  "MessageVersion": "2.1.0",
  "BrowserInfo": {
    "AcceptHeaders": "*/*",
    "IpAddress": "Cardholder Browser Ip Address",
    "JavaEnabled": false,
    "Language": "en-us",
    "ColorDepth": "3",
    "ScreenHeight": "1080",
    "ScreenWidth": "1920",
    "TimeZone": "300",
    "UserAgent": "Cardholder Browser UserAgent"
  },
  "AcquirerBin": "0000000",
  "CardDetails": {
    "Number": "f9c2f006-71d0-4a7e-b678-3f094ab561ba", // TokenEx token
    "CardExpiryDate": "2112",
    "AccountType": 2
  },
  "CardholderDetails": {
    "Name": "Bobby Tables",
    "EmailAddress": "[email protected]"
  },
  "ChallengeWindowSize": 2,
  "DeviceChannel": 2,
  "DirectoryServerIdentifier": "SANDBOX_DS",
  "GenerateChallengeRequest": true,
  "MerchantDetails": {
    "AcquirerMerchantId": "Acquirer Merchant Id",
    "CategoryCode": "0001",
    "CountryCode": "840",
    "Name": "Merchant Name"
  },
  "MessageCategory": 1,
  "NotificationUrl": "https://merchant.endpoint-for-notifications.com",
  "AuthenticationIndicator": 1,
  "PurchaseDetails": {
    "Amount": 1000,
    "Currency": "840",
    "Exponent": 2,
    "Date": "20211201091950"
  },
  "TransactionType": 1
}

Response Body Examples​

Successful Authentication​

{
  "token": "f9c2f006-71d0-4a7e-b678-3f094ab561ba",
  "threeDSecureResponse": {
    "transStatus": "Y",
    "authenticationValue": "BwABApFSYyd4l2eQQFJjAAAAAAA=", // Mapped to threeDSecure.cavv.
    "eci": "02",
    "dsTransID": "76d5b612-ac0f-45a3-8166-3d5f99faf568",
    "acsTransID": "889d32d1-a9d1-45f2-b49c-824f4a9bd233",
    "messageVersion": "2.1.0",
    "acsReferenceNumber": "00001ACS00001",
    "acsOperatorID": "mX21mRFudf",
    "threeDSServerTransID": "7e01b292-b362-4a74-add5-9adccb7014f5"
  },
  "thirdPartyStatusCode": "200",
  "referenceNumber": "2112011518481842068",
  "success": true,
  "error": "",
  "message": "Authentications Successful!"
}

Not Authenticated​

{
  "token": "c87a186b-52d5-440b-8d8e-3f29ff87f98a",
  "threeDSecureResponse": {
    "acsTransID": "def3cb82-17df-4e91-9340-70dac4211d95",
    "dsTransID": "dd8167e4-7bf1-4599-8e4c-2ca95472aa1d",
    "eci": "00",
    "transStatus": "N",
    "transStatusReason": "01",
    "messageVersion": "2.1.0",
    "acsReferenceNumber": "3DS_LOA_ACS_MCTF_020200_05450",
    "acsOperatorID": "ACS-V220-MTF-ACS-60230",
    "threeDSServerTransID": "49261f3f-fddf-490b-8176-2af36f947bc4"
  },
  "referenceNumber": "23020211450569442058",
  "success": true,
  "error": "",
  "message": "Authentications Successful!",
  "thirdPartyStatusCode": "200"
}

Challenged Authentication​

{
  "token": "cc8114d2-1909-4131-94d3-7303a93e8d78",
  "threeDSecureResponse": {
    "transStatus": "C",
    "acsURL": "https://acs-server.mc.msignia-dev.tech/api/v1/browser_challenges",
    "acsChallengeMandated": "Y",
    "authenticationType": "02",
    "dsTransID": "480db009-6d17-4e59-829f-3e40b2c09b56",
    "acsTransID": "bbbf3392-5249-4d48-940e-8d7ca9d61988",
    "messageVersion": "2.1.0",
    "acsReferenceNumber": "00001ACS00001",
    "acsOperatorID": "mX21mRFudf",
    "encodedCReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjQ2YmUwNmM0LTdmOGYtNDYxNi1iZjQzLWFiNzU0YWJjM2YwOCIsImFjc1RyYW5zSUQiOiJiYmJmMzM5Mi01MjQ5LTRkNDgtOTQwZS04ZDdjYTlkNjE5ODgiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDIiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0",
    "threeDSServerTransID": "46be06c4-7f8f-4616-bf43-ab754abc3f08"
  },
  "thirdPartyStatusCode": "200",
  "referenceNumber": "21120115203951283022",
  "success": true,
  "error": "",
  "message": "Authentications Successful!"
}

Validation Examples​

{
  "referenceNumber": "23020211441297290046",
  "success": false,
  "error": "ChallengeWindowSize must be in the range of 1 to 5",
  "message": ""
}
Last updated on