Contact us

BOOK A PRESENTATION

Integration Guidelines
We put a great effort into developing our developer's toolkit, which has a robust development library allowing easy integration of any 3-D Secure program. It makes it easy for you to activate the authentication process into your checkout flow, providing a great user experience to your customers.

3DS API integration

This page describes the Asseco 3DS Service and the integration procedure with the 3DS Server.

Introduction

Service methods

The service consists of the following methods:

  • v2Supported – method that will check the supported version of the 3D Secure protocol for a card. The use of this method is optional and could be used in environments where fallback to 3DS 1.0.2 should be supported.
  • createTransaction – method that performs the AReq/ARes part of the flow and returns the status of the check for browser-initiated transactions.
  • authenticationResult – method that returns the authentication status for a specific 3D Secure transaction.

Security

All communication between 3DS Requestor and 3DS Service is done through a mutually authenticated TLS1.2 channel. SSL and other versions of TLS are not supported.

Integration

In order to successfully perform 3DS2 transactions, PGW’s should integrate themselves with the Asseco 3DS Server.

There are two types of 3DS2 transactions:

Transactions where the Issuer has determined that Challenge isn’t necessary. Issuer will determine whether the transaction should be authorized or not, depending on the status of the transaction.

Interactions in Frictionless flow

Transactions where the cardholder will have to authenticate himself in order to successfully finish the transaction.

Interactions in the Challenge flow

Fallback to 3DS v1

Fallback to v1 is not in the scope of this document since 3DS Server doesn’t handle fallback to v1 internally. It is up to the 3DS Requestors to implement the fallback functionality based on the response received from 3DS Server.

  1. User enters card details and selects checkout
  2. 3DS Requestor initializes the transaction and calls the v2Supported method of 3DS Server.
  3. 3DS Server checks the cache and returns the response to v2Supported
  4. 3DS Requestor checks the status of the response v2Supported method
  5. If status equals V1_SUPPORTED the 3DS Requestor should fallback to v1. Optionally, since status ERROR means that some unexpected error occurred 3DS requestors can also fallback to v1.
    1. 3DS Requestor should call MPI to check the enrollment of card in 3DS v1
    2. MPI sends the VEReq to Directory Server for v1
    3. Directory Server checks the enrollment and returns the VERes to MPI
    4. MPI evaluates the received VERes and returns the enrollment response to 3DS Requestor
    5. 3DS Requestor handles the transaction according to the received enrollment status.
Fallback to 3DS v1

3DS Method Handling

The 3DS Method allows for additional browser information to be gathered by an ACS prior to receipt of the AReq message to help facilitate the transaction risk assessment. The use of the 3DS Method by an ACS is optional.

  1. If the response of the v2Supported method has the 3dsMethodUrl set the 3DS Requestor should invoke the 3DS Method URL.
    1. Create a JSON object with the 3DS Method Data elements, then Base64url encode the JSON object.
    2. Render a hidden HTML iframe in the Cardholder browser and send a form with a field named threeDSMethodData containing the JSON Object via HTTP POST to the ACS 3DS Method URL.
    3. If the 3DS Method completes within 10 seconds, then the 3DS Requestor will notify the 3DS Server to set the 3DS Method Completion Indicator = Y. If the 3DS Method does not complete in 10 seconds, set the 3DS Method Completion Indicator to = N.
  2. Otherwise, the 3DS Requestor will use the value U for 3DS Method Completion Indicator parameter of createTransaction method.

Allowed values for 3DS Method Completion Indicator are:

  • Y - Successfully completed
  • N - Did not successfully complete
  • U - Unavailable - 3DS Method URL was not present in the PRes message data for the card range associated with the Cardholder Account Number.

The following table defines the data elements sent in the 3DS Method. The data is exchanged between the 3DS Requestor via the cardholder browser.

The HTTP field name is threeDSMethodData.

The property is a JSON object that consists of two parameters:

Data Element/Field NameDescription
threeDSMethodNotificationURLThe URL that will receive the notification of 3DS Method completion from the ACS. This is sent in the initial request to the ACS from the 3DS Requestor executing the 3DS Method.
threeDSServerTransIDA unique identifier for the transaction that will be the same as the 3DS Server Transaction ID in the AReq message.

3DS Server transaction ID: 25c1b02f-ec99-4b95-bc74-f257fd66b2ee

3DS Method Notification URL: https://nestpay.tr/core/tdsMethodCallback

Generated threeDSMethodData object:

{
    "threeDSMethodNotificationURL":https://nestpay.tr/core/tdsMethodCallback",
    "threeDSServerTransID":"25c1b02f-ec99-4b95-bc74-f257fd66b2ee"
}

Base64 encoded threeDSMethodData:

base64Encoded(Generated threeDSMethodData)

Generated HTML form containing the threeDSMethodData:

<form name="MethodForm" action="<3dsMethodUrl>" method="POST">
    <input type="hidden" name="threeDSMethodData" value="base64Encoded(Generated threeDSMethodData)">
</form>

Transaction flow

The flow of a 3DS2 transaction is as follows, this doesn’t include steps before checkout, but only after it has been determined that 3DS2 is necessary.

  1. Call the v2Supported method in order to check whether 3DS2 is supported for the card identified by PAN and channel on which the transaction is being executed.
    • If the response has been received check the received status:
      • V2_VERSION_NOT_SUPPORTED – The supported version of 3DS2 by the Issuer is not supported by the 3DS Server. Because of that the processing should stop and the transaction should not be authorized.
      • ERROR – There has been some error on the 3DS Server. It is up to 3DS Requestor to decide whether they want to terminate the transaction or fallback to 3DS v1.
      • V1_SUPPORTED – Card is not found inside of 3DS Servers cache, meaning v2 is not supported, so it is assumed that v1 is supported. 3DS Requestor sholud fallback to 3DS v1.
  2. V2_SUPPORTED – 3DS2 is possible for the card and the processing should continue.
    • If 3dsMethodUrl parameter is set, do the steps described in 3DS Method Handling chapter
    • Fetch the cardholder and transaction data necessary for createTransaction method.
    • Call the createTransaction method.
    • If the call returned the response, check the returned transactionStatus
      • If the transStatus != C, Challenge isn’t necessary, fetch the authentication data from the response.
        • If transStatus == Y or transStatus == A, fetch the authenticationValue and eci values and use them in authorization request for the transaction.
        • Otherwise
          • terminate the processing and don’t authorize the transaction.
          • fetch the cardholderInfo, and if it contains any data, show that information to the cardholder on the merchant’s site.
      • Otherwise perform the challenge of the cardholder
        • Generate and prepare the response as described in chapter CReq request
        • Send the generated request to the cardholder
      • If the response is received on the Notification URL, call the authenticationResult method of the 3DS Server
        • If the method returned a result, check the authenticated parameter
          • If authenticated == true, fetch the authenticationValue and eci values and use them in authorization request for the transaction.
          • Otherwise, terminate the processing and don’t authorize the transaction.
        • Otherwise, terminate the processing and don’t authorize the transaction.
      • In case of timeout, also call the authenticationResult method of the 3DS Server
        • If the method returned a result, check the authenticated parameter
          • If authenticated == true, fetch the authenticationValue and eci values and use them in authorization request for the transaction.
          • Otherwise, terminate the processing and don’t authorize the transaction.
        • Otherwise, terminate the processing and don’t authorize the transaction.
      • Otherwise, terminate the processing and don’t authorize the transaction.
    • Otherwise, terminate the processing and don’t authorize the transaction.

Note: Only transactions with transStatus A or Y are considered authenticated and should have the authenticationValue and eci set.

In case of transactions with Mastercard cards, eci flag will be set for all transaction statuses except status E.

When checking the Authentication results of a transaction the following procedure should be done:

Check authentication results

Cardholder info

If the transaction is declined during the initial AReq/ARes exchange, meaning there haven’t been any authentication requests towards users, issuers can set the cardholderInfo property of the ARes response which contains additional information for cardholders that might be necessary for the successful execution of 3DS2 transaction.

3DS Server will return cardholderInfo in the response of the authenticationResult method.

The recommendation is to show this information, if available, to users on the merchant’s screen.

Request timeouts

Since at one point in the transaction the processing will be done between ACS and the cardholder, timeouts for requests/responses should be enforced.

This is especially important when waiting for a response from the ACS on the Notification endpoint.

PGW’s should have the option to define a timeout, so that after it has been reached the authentication light box/iframe should be closed/hidden, and authenticationResult of the 3DS Server should be called.

The further processing should depend on the returned authentication status.

Methods

Method v2Supported

The method that checks whether the card can be used to perform a 3DS2 transaction or not. The method will also return the 3DS Method URL if defined by the Issuer of the card.

Depending on the received status, 3DS Requestor should continue with the 3DS v2 transaction, fallback to v1 or end processing.

Path/v2Supported/check
Supported methodsPOST
Consumesapplication/json
Producesapplication/json
ParameterTypeDescription
panString13-19 digit string representing a valid card PAN.
deviceChannelStringIndicates the type of channel interface being used to initiate the transaction. Values accepted:
01 = App-based (APP)
02 = Browser (BRW)
03 = 3DS Requestor Initiated (3RI)

The response code when the input (PAN) is invalid should be 405. Otherwise, the service should return the status and the URL of the 3DS Server Transaction ID and 3DS Method.

The status can be one of the following values:

  • V2_VERSION_NOT_SUPPORTED – The supported version of 3DS2 by the Issuer is not supported by the 3DS Server. Because of that the processing should stop and the transaction should not be authorized.
  • ERROR – There has been some error on the 3DS Server. It is up to 3DS Requestor to decide whether they want to terminate the transaction or fallback to 3DS v1.
  • V1_SUPPORTED – Card is not found inside of 3D Servers cache, meaning v2 is not supported, so it is assumed that v1 is supported. 3DS Requestor should fallback to 3DS v1.
  • V2_SUPPORTED – 3DS2 is possible for the card and the processing should continue.
{
    "pan": 4308331682827506,
    "deviceChannel": "02"
}
{
    “versionStatus”: “V2_SUPPORTED”,
    “3dsMethodUrl”: “https://nekiurl.con/3dsmethod”,
    “3dssTransactionId”: “123e4567-e89b-12d3-a456-556642440000”
}

Method createTransaction

The method that generates the AReq message and forwards it to the Directory Server to see if Frictionless or Challenge flow should be performed.

Path/createTransaction
Path with transaction id/createTransaction/{3DSS_TRANSACTION_ID}
Supported methodsPOST
Consumesapplication/json
Producesapplication/json

3DSS_TRANSACTION_ID is an optional parameter. If set the same value as received in the response of v2Supported method should be used. Otherwise, 3DSS will generate and return the value for 3DSS_TRANSACTION_ID in the response.

Values for some arguments of createTransaction are derived from functionalities and/or values available in 3DS requestor environment.

Those values should be generated by the 3DS Requestor the following way:

  • addrMatch is a parameter that defines whether the billing and shipping addresses are the same.

The parameter can have the following values:

  • Y = Shipping Address matches Billing Address
  • N = Shipping Address does not match Billing Address

3DS Requestor should compare the two addresses and set the appropriate value for addrMatch.

  • payTokenInd is an optional flag that says whether the Cardholder’s PAN has been de-tokenized by the 3DS Requestor.

The only accepted value for payTokenInd is true.

If there hasn’t been any de-tokenization of Account Number on 3DS Requestor side, this parameter should not be included in the call of the createTransaction method.

ParameterTypeMandatoryDescription
messageCategoryintMandatoryMessage category. Can have one of two values: Payment AuthenticationNon Payment Authentication
deviceChannelStringMandatoryIndicates the type of channel interface being used to initiate the transaction. Values accepted:
01 = App-based (APP)
02 = Browser (BRW)
03 = 3DS Requestor Initiated (3RI)
threeRiDataJSON ObjectOptionalIndicates the type of 3RI
request.
threeDSCompIndStringMandatoryIndicates whether the 3DS Method successfully completed. Values accepted:
Y = Successfully completed
N = Did not successfully complete
U = Unavailable - 3DS Method URL was not present in the PRes message data for the card range associated with the Cardholder Account Number.
panStringMandatory13-19 digit string representing a valid card PAN.
cardExpiryStringMandatoryExpiry date of the card or token.
String, 4 characters
Format accepted: YYMM
payTokenIndStringMandatoryA value of True indicates that the transaction was de-tokenised prior to being received by the ACS. This data element will be populated by the system residing in the 3-D Secure domain where the de-tokenisation occurs (i.e., the 3DS Server or the DS).
Note: The Boolean value of true is the only valid response for this field when it is present.
3dsrMerchantIdStringDeprecated3DS Requestor assigned Merchant identifier. String, maximal length 35 characters. Unused
merchantId StringMandatoryMerchant identifier registered at directory server. String, maximal length 40 characters.
acquirerBinStringMandatoryAcquiring institution identification code as assigned by the DS. String, maximal length 11 characters.
threeDSRequestorJSON objectMandatoryJSON Object containing 3DS requestor info.
billingAddressJSON objectMandatory (if available), unless market or regional mandate restricts sending this information.JSON object containing the billing address for the transaction.
shippingAddressJSON objectMandatory (if available), unless market or regional mandate restricts sending this information.JSON object containing the shipping address for the transaction.
addrMatchStringMandatoryA parameter that defines whether the billing and shipping addresses are the same.
Y: Shipping Address matches Billing Address
N: Shipping Address does not match Billing Address
emailStringMandatory (if available), unless market or regional mandate restricts sending this information.Email of the Cardholder. String, maximum 254 characters Value accepted: Shall meet requirements of Section 3.4 of IETF RFC 5322.
cardholderName StringMandatory (if available), unless market or regional mandate restricts sending this information.Name of the Cardholder, 2 – 45 characters.
homePhoneJSON ObjectMandatory (if available), unless market or regional mandate restricts sending this information.JSON Object containing information about Cardholders home phone.
mobilePhone JSON ObjectMandatory (if available), unless market or regional mandate restricts sending this information.JSON Object containing information about Cardholders mobile phone.
workPhoneJSON ObjectMandatory (if available), unless market or regional mandate restricts sending this information.JSON Object containing information about Cardholders work phone.
merchantJSON ObjectMandatoryJSON object containing Merchant data.
purchaseJSON ObjectMandatoryJSON object containing Purchase data.
transTypeStringMandatoryIdentifies the type of transaction being authenticated. String 2 characters.
acctTypeStringMandatoryIndicates the type of account. Length: 2 characters Values accepted:
01 = Not Applicable
02 = Credit
03 = Debit
acctIDStringOptionalAdditional information about the account optionally provided by the 3DS Requestor. String, maximum 64 characters.
accountJSON ObjectMandatoryRefer to Table A.8 of the Protocol and Core Functions Specification for data elements.
purchaseInstalDataStringConditional Required if 3DS Requestor Authentication Indicator = 03. Omitted if not an instalment payment authentication.Three numerical characters. Value should be greater than 1.
merchantRiskIndicatorJSON ObjectOptionalMerchant’s assessment of the level of fraud risk for the specific authentication for both the cardholder and the authentication being conducted.
Refer to Table A.9 of the Protocol and Core Functions Specification for data elements.
recurringExpiryStringConditional Required if 3DS Requestor Authentication Indicator = 02 or 03.Date after which no further authorizations shall be performed.
recurringFrequencyStringConditional Required if 3DS Requestor Authentication Indicator = 02 or 03.Indicates the minimum number of days between authorizations.
browser JSON ObjectMandatory (if available), unless market or regional mandate restricts sending this information.JSON object containing browser data.
notificationUrlStringMandatoryNotification URL is the URL of an endpoint in the 3DS Requestor environment which will receive the requests from ACS containing the final CRes message. The endpoint is usually a part of the Merchant/PGW site.
challengeWindowSizeStringMandatoryDimensions of the challenge window that has been displayed to the Cardholder. Values accepted:
01 - 250 x 400
02 - 390 x 400
03 - 500 x 600
04 - 600 x 400
05 - Full screen
protocolVersionStringMandatoryVersion of 3DS protocol to be used.
ParameterTypeMandatoryDescription
transStatusStringMandatoryCharacter value defining the status of the execution. In case a valid ARes has been received the value should be equal to transStatus of the ARes message, or in case of an error the status should be E.
threeDSServerTransIDStringMandatoryIdentifier of the 3DS Server transaction.
additionalDataJSON ObjectOptionalOptional transaction data that might be returned.
errorCodeStringOptionalCode defining the type of error that as occurred.
errorDescriptionStringOptionalTextual description of the error.
eci StringOptionalElectronic Commerce Indicator. In case of Visa cards, should be only present in case status is A, Y or C. But in case of Mastercard cards can be present for all returned statuses.
authValueStringOptionalAuthentication value generated by the ACS for the transaction, should be only present in case status is A or Y, should be only present in case status is A or Y.
dsTransIDStringOptionalDirectory Server identifier of the transaction.
cardholderInfoStringOptionalShort text, 128 characters, provided by the ACS/Issuer to Cardholder during a Frictionless transaction that was not authenticated by the ACS. The Issuer can optionally provide information to Cardholder. For example, "Additional authentication is needed for this transaction, please contact (Issuer Name) at xxx-xxx-xxxx."
creqStringOptionalBase64url encoded value of the CReq message that should be sent to the ACS.
acsURLStringOptionalURL of ACS endpoint to which the CReq message should be sent.

Example request when calling the method with the 3DS Server identifier e.g. createTransaction/050d09cc-f096-4f97-8043-b34889837887.

{
    "messageCategory": "02",
    "deviceChannel": "02",
    "threeDSCompInd": "Y",
    "pan": "4308331682827506",
    "cardExpiry": "2212",
    "3dsrMerchantId": "3dsr Merchant Id",
    "merchantId": "merchant Id",
    "threeDSRequestor": {
        "id": "239",
        "name": "EMVCo 3DS Test Requestor",
        "url": "http://www.ul.com/144213bb-f034-410d-84fe-42723ff028b6",
        "threeDSRequestorAuthenticationInd": "01"
    },
    "billingAddress": {
        "line1": "Bill Address Line 1",
        "line2": "Bill Address Line 2",
        "line3": "Bill Address Line 3",
        "city": "Bill City Name",
        "postalCode": "Bill Post Code",
        "state": "USA",
        "country": "840"
    },
    "shippingAddress": {
        "line1": "Bill Address Line 1",
        "line2": "Bill Address Line 2",
        "line3": "Bill Address Line 3",
        "city": "Bill City Name",
        "postalCode": "Bill Post Code",
        "state": "USA",
        "country": "840"
    },
    "email": "x.y@mail.com",
    "cardholderName": "cardholderName",
    "homePhone": {
        "cc": "123",
        "subscriber": "123456789"
    },
    "workPhone": {
        "cc": "123",
        "subscriber": "123456789"
    },
    "mobilePhone": {
        "cc": "123",
        "subscriber": "123456789"
    },
    "merchant": {
        "mcc": "7922",
        "countryCode": "840",
        "name": "Test Merchant"
    },
    "purchase": {
        "amount": "19995",
        "currency": "191",
        "exponent": "2",
        "date": "20190523102223"
    },
    "transType": "01",
    "acctType": "03",
    "acctID": "acct ID",
    "account": {
        "chAccAgeInd": "05",
        "chAccDate": "20170101",
        "chAccChangeInd": "04",
        "chAccChange": "20170101",
        "chAccPwChangeInd": "05",
        "chAccPwChange": "20170101",
        "shipAddressUsageInd": "04",
        "shipAddressUsage": "20170101",
        "txnActivityDay": "1",
        "txnActivityYear": "1",
        "provisionAttemptsDay": "0",
        "nbPurchaseAccount": "1",
        "suspiciousAccActivity": "01",
        "shipNameIndicator": "01",
        "paymentAccInd": "05",
        "paymentAccAge": "20170101"
    },
    "purchaseInstalData": "555",
    "merchantRiskIndicator": {
        "shipIndicator": "01",
        "deliveryTimeframe": "02",
        "deliveryEmailAddress": "example@example.com",
        "reorderItemsInd": "01",
        "preOrderPurchaseInd": "01",
        "preOrderDate": "20300101",
        "giftCardAmount": "1",
        "giftCardCurr": "840",
        "giftCardCount": "01"
    },
    "recurringExpiry": "20170101",
    "recurringFrequency": "3",
    "browser": {
        "ip": "10.135.154.11",
        "language": "en",
        "javaEnabled": true,
        "acceptHeader": "text/html,application/xhtml+xml,application/xml;q=0.9,/;q=0.8",
        "userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101                 Firefox/47.0",
        "colorDepth": "32",
        "screenHeight": "800",
        "screenWidth": "600",
        "timeZone": "0"
    },
    "notificationURL": "https://3dsrequestor.asseco-see.hr/notification",
    "challengeWindowSize": "02",
    "protocolVersion": "2.1.0"
}
{
    "transStatus": "C",
    "threeDSServerTransID": "050d09cc-f096-4f97-8043-b34889837887",
    "errorCode": null,
    "errorDescription": null,
    "eci": null,
    "authValue": null,
    "dsTransID": null,
    "creq":                 "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjA1MGQwOWNjLWYwOTYtNGY5Ny04MDQzLWIzNDg4OTgzNzg4NyIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsImFjc1RyYW5zSUQiOiIyLjEuMCIsImNoYWxsZW5nZVdpbmRvd1NpemUiOiIwMiIsIm1lc3NhZ2VWZXJzaW9uIjoiMi4xLjAifQ==",
    "acsURL": "http://localhost:1234/dummy-acs-url",
    "cardholderInfo": null,
    "additionalData": {
        "ares": {
            "messageType": "ARes",
            "messageVersion": "2.1.0",
            "threeDSServerTransID": "050d09cc-f096-4f97-8043-b34889837887",
            "acsReferenceNumber": "00001ACS00001",
            "acsURL": "http://localhost:1234/dummy-acs-url",
            "acsTransID": "3cbd0751-24cd-44a2-80a9-c854e7edc3bd",
            "dsReferenceNumber": "MSIGNIA_MOCK_DS",
            "dsTransID": "1ad8dd99-cf08-405a-9607-f4a2414587af",
            "acsChallengeMandated": "Y",
            "acsOperatorID": "mX21mRFudf",
            "authenticationType": "02",
            "authenticationValue": "rsycufapnyqbdzebtdtaweekgida",
            "eci": "xs",
            "transStatus": "C"
        }
    }
}

The full list of possible transaction statuses. Some of the statuses might not be returned in the response of createTransaction response.

StatusDescription
YAuthentication/ Account Verification Successful
NNot Authenticated /Account Not Verified; Transaction denied
UAuthentication/ Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq
AAttempts Processing Performed; Not Authenticated/Verified, but proof of attempted authentication/verification is provided
CChallenge Required; Additional authentication is required using the CReq/CRes
RAuthentication/ Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorisation not be attempted.
E3DSS error; Technical or other problem

Error codes are divided into two categories:

  1. EMVCo 3D Secure protocol error codes
    • Returned by DS and part of Erro message in additionalData object
  2. 3DSS error codes
    • Returned by 3DSS in errorCode field
ValueError CodeError DescriptionError Detail
101Message Received InvalidOne of the following:
Message is not AReq, ARes, CReq, CRes, PReq, PRes, RReq, or RRes
Valid Message Type is sent to or from an inappropriate component (such as AReq message being sent to the 3DS Server) Message not recognised  
One of the following:
Invalid Message Type
Invalid Message for the receiving component
Invalid Formatted Message  
102Message Version Number Not SupportedMessage Version Number received is not valid for the receiving component.All supported Protocol Version Numbers in a comma-delimited list.
201Required Data Element MissingA message element defined as required is missing from the message.Name of required element(s) that was omitted; if more than one element is detected, this is a comma-delimited list.
Parent Example: messageType
Parent/Child Example: acctInfo.chAccAgeInd
202Critical Message Extension Not RecognisedCritical message extension not recognised.ID of critical Message Extension(s) that was not recognised; if more than one extension is detected, this is a comma-delimited list of message identifiers that were not recognised.
203Format of one or more Data Elements is Invalid according to the SpecificationData element not in the required format or value is invalid as defined in Table A.1
Message Version Number does not match the value set by the 3DS Server in the AReq message.  
Name of the invalid element(s); if more than one invalid data element is detected, this is a comma-delimited list.
204Duplicate Data ElementThe valid data element presents more than once in the message.Name of duplicated data element; if more than one duplicate data element is detected, this is a comma-delimited list.
301Transaction ID Not RecognisedTransaction ID received is not valid for the receiving component.The Transaction ID received was invalid.
302Data Decryption FailureData could not be decrypted by the receiving system due to technical or other reasons.Description of the failure.
303Access Denied, Invalid EndpointAccess denied, invalid endpoint.Description of the failure.
304ISO Code InvalidISO code not valid per ISO tables (for either country or currency), or code is one of the excluded values listed in Table A.5.Name of the invalid element(s); if more than one invalid element is detected this is a comma-delimited list
If Challenge Request, Purchase currency and Challenge Request.Purchase exponent form an invalid pair, list both as Error Description.
305Transaction data not validIf in response to an AReq message: Cardholder Account Number is not in a range belonging to Issuer
If in response to a CReq, and a CReq message was incorrectly sent, one of the following:
CReq message was received by the wrong ACS CReq message was not sent, based on the values in the ARes message CReq message with this ACS Transaction ID has already been received and processed
Name of element(s) that caused the ACS to decide that the AReq message or CReq message was incorrectly sent; if more than one invalid element is detected this is a comma-delimited list.
306Merchant Category Code (MCC) Not Valid for Payment SystemMerchant Category Code (MCC) not valid for Payment System.For example, Invalid MCC received in the AReq message.
307Serial Number not ValidSerial Number not valid.For example, Invalid Serial number in the PReq/PRes message (e.g., too old, not found).
402Transaction Timed OutTransaction timed-out.For example, Timeout expiry reached for the transaction.
403Transient System FailureTransient system failure.For example, a slowly processing back-end system.
404Permanent System FailurePermanent system failure.For example, a critical database cannot be accessed.
405System Connection FailureSystem connection failure.For example, the sending component is unable to establish the connection to the receiving component.
Error CodeError DescriptionError DetailAction
001Acquirer not definedThe acquirer sent in createTransaction request is not defined in TDSS_ACQUIRER_BIN table  Add the acquirer and assign it a DS  
003Invalid ResponseDS returned an unexpected responseExamine the EMVCo 3DS Erro in additionalData to determine the problem
004Transaction is not definedA caller attempted to recall a transaction with an ID that is not present in the systemCheck the ID being sent
005Transaction data missing or is not validA mandatory data element has not been provided or is in invalid formatExamine the EMVCo 3DS Erro or errorDescription and errorDetail fields to determine the problem
006Error generating CReq requestThe CReq request could not be generated because of the system failure  Examine the other fields describing the error
007Transaction timed out on DSThe timeout occurred when contacting DSCheck DS URL and if it is available to 3DSS
008General DS communication failureAll other communication problems while contacting DSCheck DS URL and if it is available to 3DSS
009Bad requestData in the request are not by specificationCorrect the request data
0103D Secure Version 2 is not availableAccount number (PAN) provided in createTransaction request is not participating in 3D Secure 2.0
011The card range cache is emptyNo information about card ranges participating in 3D Secure 2.0 is present in the databaseMake sure that 3DSS initiated and downloaded card range cache (PR cache) from DS

If createTransaction method returned transStatus=C, that means that Challenge of the user should be performed.

When the deviceChannel=02 (Browser) i.e. the transaction is initiated through a browser and not through a mobile app the 3DS Requestor should generate a response that contains the returned CReq message that should be submitted to ACS.

Optional data used to accommodate the different methods 3DS Requestor systems handle session information.

If the 3DS Requestor system does not maintain a session for a given authentication session, the 3DS Requestor Session Data field can carry any data the 3DS Requestor needs to continue the session.

If the 3DS Requestor system can associate the final post with the original session without further assistance, the 3DS Requestor Session Data field may be missing.

Because the content of this field varies by 3DS Requestor implementation, the ACS must preserve the content unchanged and without assumptions.

After the authentication has been finished, the ACS will send information about the authentication status to the Notification endpoint located in the 3DS Requestor environment.

The URL of the endpoint is defined by createTransaction parameter notificationUrl.

When 3DS Requestor receives a request to the endpoint defined in notificationUrl it should call the authenticationResult method to get the final authentication results for the transaction.

Method authenticationResult

Method that returns the authentication result for the defined 3DS Server transaction id.
Depending on the type of 3DS transaction the method has an optional parameter cres which can contain a final CRes or Erro message.

Path/authenticationResult/{3DSS_TRANSACTION_ID}
Supported methodsGET
Consumesapplication/json
Producesapplication/json

3DSS_TRANSACTION_ID is the identifier of the 3DS Server transaction.

ParameterTypeMandatoryDescription
cresStringOptionalOptional argument that contains the Base64url encoded final CRes or Erro message received by 3DS requestor on the Notification endpoint.

The method returns the status of the authentication and in case of successful authentication the Authentication Value and ECI flag.

ParameterTypeMandatoryDescription
authenticatedbooleanMandatoryIndicates that the authentication was successful.
true – transaction authenticated
false – transaction not authenticated or Erro message received.
transStatusStringMandatoryThe final transaction status for the transaction.
The list of possible transaction statuses is described in the chapter Transaction statuses.
authenticationValueStringOptionalAuthentication value generated by the ACS for the transaction should be only present in case the status is A or Y.
eciStringOptionalElectronic Commerce Indicator.
dsTransIdStringOptionalDS Transaction Identifier, present if available.

Example request when calling the method with the 3DS Server transaction identifier identifier e.g. authenticationResult/050d09cc-f096-4f97-8043-b34889837887

{
    "authenticated": false,
    "transStatus": "N",
    "authenticationValue": "",
    "eci": "xs",
    "dsTransID": "1ad8dd99-cf08-405a-9607-f4a2414587af"
}

NOTE: After data is fetched the first time, the authentication value will be deleted from the database and an empty string will be returned every time after for the authentication value.

JSON objects

JSON object containing 3DS Requestor info consists of the following data:

  • id – identifier of the 3DS Requestor. String, maximum 35 characters.
  • name – 3DS requestor name. String, maximum 40 characters.
  • url – URL of the 3DS Requestor. String, should be a fully qualified URL, maximum 2048 characters
  • challengeIndicator – Optional, indicates whether a challenge is requested for this transaction. Possible values:
    • 01 = No preference
    • 02 = No challenge requested
    • 03 = Challenge requested: 3DS Requestor Preference
    • 04 = Challenge requested: Mandate
  • threeDSRequestorAuthenticationInd - Indicates the type of Authentication request. Possible values:
    • 01 = Payment transaction
    • 02 = Recurring transaction
    • 03 = Instalment transaction
    • 04 = Add card
    • 05 = Maintain card
    • 06 = Cardholder verification as part of EMV token ID&V
  • authInfo - Optional information about how the cardholder authenticated during login to their 3DS Requestor account.
  • priorAuthInfo - Optional information about a 3DS cardholder authentication that occurred prior to the current transaction.

Example:

“threeDSRequestor” : {
    "id":"az0123456789",
    "name":"Example Requestor name",
    "url":“https://threedsrequestor.adomainname.net“,
    "threeDSRequestorAuthenticationInd": "01”
}

JSON object containing optional information about how the cardholder authenticated during login to their 3DS Requestor account.

  • threeDSReqAuthData - Data that documents and supports a specific authentication process. In the current version of the specification, this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process. For example, for method:
    • 02 - field can carry generic 3DS Requestor authentication information
    • 03 - data element can carry information about the provider of the federated ID and related information
    • 04 - data element can carry the FIDO attestation data (including the signature). In future versions of the specification, these details are expected to be included.
    • Length: maximum 2048 bytes
    • JSON Data Type: String
    • Value accepted: Any
  • threeDSReqAuthMethod - Mechanism used by the Cardholder to authenticate to the 3DS Requestor.
    • Length: 2 characters
    • JSON Data Type: String
    • Values accepted:
      • 01 = No 3DS Requestor authentication occurred (i.e. cardholder “logged in” as guest)
      • 02 = Login to the cardholder account at the 3DS Requestor system using 3DS Requestor’s own credentials
      • 03 = Login to the cardholder account at the 3DS Requestor system using federated ID
      • 04 = Login to the cardholder account at the 3DS Requestor system using issuer credentials
      • 05 = Login to the cardholder account at the 3DS Requestor system using third-party authentication
      • 06 = Login to the cardholder account at the 3DS Requestor system using FIDO Authenticator
  • threeDSReqAuthTimestamp - Date and time in UTC of the cardholder authentication.
    • Length: 12 characters
    • JSON Data Type: String
    • Format accepted:
      • Date format = YYYYMMDDHHMM

JSON object containing optional information about a 3DS cardholder authentication that
occurred prior to the current transaction.

  • threeDSReqPriorAuthData - Data that documents and supports a specific authentication process.
    • In the current version of the specification this data element is not defined in detail, however the intention is that for each 3DS Requestor Authentication Method, this field carry data that the ACS can use to verify the authentication process. In future versions of the specification, these details are expected to be included.
    • Length: maximum 2048 bytes
    • Format: Any
  • threeDSReqPriorAuthMethod - Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor.
    • Length: 2 characters
    • JSON Data Type: String
    • Values accepted:
      • 01 = Frictionless authentication occurred by ACS
      • 02 = Cardholder challenge occurred by ACS
      • 03 = AVS verified
      • 04 = Other issuer methods
  • threeDSReqPriorAuthTimestamp - Date and time in UTC of the prior cardholder authentication.
    • Length: 12 characters
    • JSON Data Type: String
    • Format accepted:
      • Date format = YYYYMMDDHHMM
  • threeDSReqPriorRef - This data element provides additional information to the ACS to determine the best approach for handing a request.
    • Length: 36 characters
    • JSON Data Type: String
    • Value accepted:
      • This data element contains an ACS Transaction ID for a prior authenticated transaction (for example, the first recurring transaction that was authenticated with the cardholder).

JSON object containing address info used for billingAddress and shippingAddress:

  • line1 – First line of the street address or equivalent local portion of the address. String, maximum 50 characters.
  • line2 – Second line of the street address or equivalent local portion of the Cardholder address. String, maximum 50 characters.
  • line3 – Third line of the street address or equivalent local portion of the address. String, maximum 50 characters.
  • city - The city of the Cardholder address. String, maximum 50 characters.
  • postalCode - ZIP or other postal code of the Cardholder address. String, maximum 16 characters.
  • state - The state or province of the Cardholder address. String, maximal 3 characters. Should be the country subdivision code defined in ISO 3166-2.
  • country - The country of the Cardholder address. ISO 3166-1 numeric three-digit country code, other than exceptions listed in the table below:
ISO CodeValue Not Permitted for 3-D SecureDefinition
ISO 4217955European Composite Unit
ISO 4217956European Monetary Unit
ISO 4217957European Unit of Account 9
ISO 4217958European Unit of Account 17
ISO 4217959Gold
ISO 4217960I.M.F.
ISO 4217961Silver
ISO 4217962Platinum
ISO 4217963Reserved for testing
ISO 4217964Palladium
ISO 4217999No currency is involved
ISO 4217901–999Reserved by ISO to designate country names not otherwise defined

Example:

“billingAddress” : {
    "line1":"Bill Address Line 1",
    "line2":"Bill Address Line 2",
    "line3":"Bill Address Line 3",
    "city":"Bill City Name",
    "postalCode":"Bill Post Code",
    "state":"CO",
    "country":"840"
}

JSON object defining the phone number. Consists of the following fields:

  • cc – Country code. String, 1 – 3 characters.
  • subscriber – Subscriber number. String, maximum 15 characters.

Example:

"mobilePhone": {
    "cc":"123",
    "subscriber":"123456789"
}

Refer to ITU-E.164 for additional information on format and length.

JSON object defining merchant. Consists of the following fields:

  • mcc - Merchant Category Code, String 4 characters.
  • countryCode - Merchant Country Code. String 3 characters, ISO 3166-1 numeric three-digit country code.
  • name - Merchant Name. String, maximal 40 characters.

JSON Object defining Purchase. Consists of the following fields:

  • amount - Purchase amount in minor units of currency with all punctuation removed. String, maximum 48 characters, e.g. If the purchase amount is USD 123.45, element will contain the value 12345.
  • currency - ISO 4217 three-digit currency code.
  • exponent - Minor units of currency as specified in the ISO 4217 currency exponent. 1 character.
  • date - Date and time of the purchase, expressed in UTC. String, 14 characters
    • Formatted: YYYYMMDDHHMMSS

JSON object containing Browser info. Consists of the following fields:

  • ip - IP address of the browser as returned by the HTTP headers to the 3DS Requestor. String, maximum 45 characters
  • language - Value representing the browser language as defined in IETF BCP47. String, 1–8 characters
  • javaEnabled - Boolean that represents the ability of the cardholder browser to execute Java. Accepted values are true or false.
  • acceptHeader - Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. String, maximum 2048 characters
  • userAgent - Value representing the bit depth of the color palette for displaying images, in bits per pixel. String, 1-2 characters.
  • colorDepth - Value representing the bit depth of the color palette for displaying images, in bits per pixel. String, 1-2 characters.
  • screenHeight - Total height of the Cardholder’s screen in pixels. String, 1–6 characters.
  • screenWidth - Total width of the cardholder’s screen in pixels. String, 1–6 characters.
  • timeZone - Time difference between UTC time and the Cardholder browser local time, in minutes. String, 1–5 numerical characters.

JSON object containing the 3RI Indicator.

3RI transaction is a 3-D Secure transaction initiated by the 3DS Requestor for the purpose of confirming an account is still valid. The main use case is recurrent transactions (TV subscriptions, utility bill payments, etc.) where the merchant wants to perform a Non-Payment transaction to verify that a subscription user still has a valid form of payment.

  • threeRIInd - Indicates the type of 3RI request.
    • Values accepted:
      • 01 = Recurring transaction
      • 02 = Instalment transaction
      • 03 = Add card
      • 04 = Maintain card information
      • 05 = Account verification

Example:

"threeRiData": {
    "threeRIInd": "01"
}

CyberSecurityhub

chevron-down linkedin facebook pinterest youtube rss twitter instagram facebook-blank rss-blank linkedin-blank pinterest youtube twitter instagram