Skip to content
Last updated

3D Secure

3D Secure is a protocol that adds an extra layer of security to online credit and debit card transactions. It involves a two-step authentication process, requiring cardholders to verify their identity with their issuing bank, typically by entering a one-time passcode or a security question.

Process Flow

You initiate the 3D Secure verification process by sending a 3D Secure Standalone request.

The 3D Secure Standalone response can result in one of the following options:

  1. Request Complete
    • The 3D Secure process determined that no challenge was necessary, resulting in a frictionless flow.
    • The ​transaction.​responseCode will return as A if the 3D Secure process was successful. If successful, the response includes the 3D Secure data including the cryptogram in the threeDSecure object.
    • The ​transaction.​responseCode will return as D if the 3D Secure process was unsuccessful. You should treat this as a decline and request a different form of payment.
  2. Device Fingerprint Required
    • The issuer is requesting additional information before determining whether to proceed with a frictionless flow or to prompt the cardholder for verification.
    • The ​transaction.​responseCode will return as H
    • See the Handling Device Fingerprint Response for details on how to handle this type of response.
  3. Challenge
    • The issuer is requesting to prompt the cardholder for verification.
    • The ​transaction.​responseCode will return as G
    • See the Handling Challenge Response for details on how to handle this type of response.

Once the 3D Secure Standalone process is complete you can send the threeDSecure data in the Authorization or Sale/Purchase request using the 3D Secure Using Card Number or 3D Secure Using GTV Token request bodies.

Handling Device Fingerprint Response

Handling the device fingerprint response will require your system to support handling webhooks. You will send an HTTP POST request to the issuer via the URL returned in the redirectUrl response field. The request sent to the issuer will include the URL the issuer can use to notify your system when the device fingerprint is complete. Once the issuer completes the device fingerprint they will then send a notification request back to your system using the URL you specified in the HTTP POST request.

Device Fingerprint Flow

  1. Your system will receive transaction.responseCode = H in the 3D Secure Standalone response.
  2. Create a JSON object with the following 3DS Method Data elements:
    • threeDSMethodNotificationURL = the URL to which the issuer will send its approval
    • threeDSServerTransID = threeDSecure.trxid from the 3D Secure Standalone response.
    {
  "threeDSMethodNotificationURL": "merchant_server",
  "threeDSServerTransID": "cc78c193-eaec-494f-9cf0-eb5fa3940b13"
}
  3. Base64 Encode the JSON object.
eyJ0aHJlZURTTWV0aG9kTm90aWZpY2F0aW9uVVJMIjoibWVyY2hhbnRfc2VydmVyIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJjYzc4YzE5My1lYWVjLTQ5NGYtOWNmMC1lYjVmYTM5NDBiMTMifQ==
  1. Render a hidden HTML iframe in the Cardholder’s browser and send an HTTP POST request with a query parameter named threeDSMethodData containing the Base64 encoded JSON Object to the redirectUrl you received from 3D Secure Standalone response.
  2. Wait for the device fingerprint completion notification webhook.

The webhook notification for device fingerprint completion is typically returned within a few seconds, however the card schemes recommend waiting up to 10 seconds.

  1. At this stage you should get the webhook notification for the completion of the fingerprint collection process. The information is a POST response to the notification URL you provided in the threeDSMethodNotificationURL parameter in step 2. It contains a single parameter called threeDSMethodData containing Base64 encoded JSON data.
  2. Base64 decode the threeDSMethodData parameter. The result will be JSON formatted data with the threeDSServerTransId field that matches the threeDSecure.trxId field from the initial response.
{
  "threeDSServerTransID": "cc78c193-eaec-494f-9cf0-eb5fa3940b13"
}
  1. Send the 3D Secure Completion request
    • If you received the device fingerprint notification response send threeDSecure.compInd = Y.
    • If you do not receive the device fingerprint response, send threeDSecure.compInd = N.

You must always send the 3D Secure Completion request whenever you receive the Device Fingerprint response in order for the 3D Secure process to continue

The 3D Secure Completion request can result in one of the following:

  1. Request Complete
    • The Device Fingerprint process determined that no challenge was necessary, resulting in a frictionless flow.
    • The ​transaction.​responseCode will return as A if the 3D Secure process was successful. If successful, the response includes the 3D Secure data including the cryptogram in the threeDSecure object.
    • The ​transaction.​responseCode will return as D if the 3D Secure process was unsuccessful. You should treat this as a decline and request a different form of payment.
  2. Device Fingerprint Required
    • The issuer is requesting additional information before determining whether to proceed with a frictionless flow or to prompt the cardholder for verification.
    • The ​transaction.​responseCode will return as H
    • See the Handling Device Fingerprint Response for details on how to handle this type of response.
  3. Challenge
    • The issuer is requesting to prompt the cardholder for verification.
    • The ​transaction.​responseCode will return as G
    • See the Handling Challenge Response for details on how to handle this type of response.

Handling Challenge Response

The Challenge response indicates the issuer wants to challenge the cardholder to authenticate using a one time password or a security question. The 3D Secure Standalone response will include a redirect URL where the cardholder's browser can be redirected to the issuer's website for the challenge.

Challenge Process Flow

  1. Your system will receive transaction.responseCode = G in the 3D Secure Standalone response indicating the issuer wants to further authenticate the cardholder.
  2. Redirect the browser to the URL specified in the redirectUrl response field.
  3. The cardholder will be redirected to the issuer site where the issuer will present the challenge.
  4. The cardholder will enter the One Time Password or answer the security question presented by the issuer.
  5. Once complete the browser will be redirected back to the completionUrl you sent in the 3D Secure Standalone request.
  6. The redirect will include the j query parameter that contains Base64 encoded JSON data.
j=eyJyZXN1bHQiOlt7ImRhdGVUaW1lIjoiMjAyNS0wNC0xMFQxNzoxNzozOS42ODAtMDc6MDAiLCJjdXJyZW5jeUNvZGUiOiJVU0QiLCJjYXJkIjp7ImVudHJ5TW9kZSI6Ik0iLCJwcmVzZW50IjoiTiIsInRva2VuIjp7InZhbHVlIjoiODA1NDQ1NDAwMjQwMDAxNSJ9LCJ0eXBlIjoiTUMiLCJudW1iZXIiOiJYWFhYWFhYWFhYWFgwMDE1In0sImFtb3VudCI6eyJ0b3RhbCI6MTExfSwidHJhbnNhY3Rpb24iOnsiaW52b2ljZSI6IjE2MjUiLCJyZXNwb25zZUNvZGUiOiJBIiwiYXV0aFNvdXJjZSI6IkYifSwicmVjZWlwdCI6W3sia2V5IjoiQ2FyZEVudHJ5TW9kZSIsInByaW50TmFtZSI6IkVOVFJZIE1FVEhPRCIsInByaW50VmFsdWUiOiJLRVlFRCJ9LHsia2V5IjoiTWFza2VkUEFOIiwicHJpbnROYW1lIjoiUEFOIiwicHJpbnRWYWx1ZSI6IlhYWFhYWFhYWFhYWDAwMTUifSx7ImtleSI6IlRyYW5zYWN0aW9uUmVzcG9uc2UiLCJwcmludE5hbWUiOiJSZXNwb25zZSIsInByaW50VmFsdWUiOiJBUFBST1ZFRCJ9LHsia2V5IjoiVHJhbnNhY3Rpb25EYXRlIiwicHJpbnROYW1lIjoiOUEiLCJwcmludFZhbHVlIjoiMjUwNDEwIn0seyJrZXkiOiJUcmFuc2FjdGlvblRpbWUiLCJwcmludE5hbWUiOiI5RjIxIiwicHJpbnRWYWx1ZSI6IjE3MTczOSJ9LHsia2V5IjoiVHJhbnNhY3Rpb25DdXJyZW5jeUNvZGUiLCJwcmludE5hbWUiOiJDVVJSRU5DWSBDT0RFIiwicHJpbnRWYWx1ZSI6IlVTRCAkIn0seyJrZXkiOiJTaWduYXR1cmVSZXF1aXJlZCIsInByaW50TmFtZSI6IklTIFNJR05BVFVSRSBSRVFVSVJFRCIsInByaW50VmFsdWUiOiJZIn1dLCJ0aHJlZURTZWN1cmUiOnsidHJ4SWQiOiIyYmYwZTAyYi1mZmIyLTQzODgtOWQ0Yy1jMjY0MGNjMTBiOWIiLCJzZWN1cml0eUxldmVsSW5kaWNhdG9yIjoiMjEwIiwiY3J5cHRvZ3JhbSI6IlFtMTgxb2ttZHlxaDZ5UW1ZdXExODkwUUFBQT0iLCJlY29tbUluZGljYXRvciI6IjUiLCJwcm9ncmFtUHJvdG9jb2wiOiIxIiwidmVyc2lvbiI6IjIuMS4wIiwiZGlyZWN0b3J5U2VydmVyVHJhbklkIjoiODgyN2ZhOWMtZmQxNS00YTQ0LWE1MWQtM2MwY2RkZGY5M2JhIn0sInNlcnZlciI6eyJuYW1lIjoic29ja18wMC5maW5hcm9wcm9jLkNFLUFQTS1WMDEifX1dfQ%3D%3D
  1. Base64 decode the value. This will result in a standard JSON response including the threeDSecure object containing the cryptogram and other 3D Secure fields that are needed for processing via the Authorization or Sale/Purchange endpoint.
    {
 "result": [
     {
         "dateTime": "2025-04-10T17:17:39.680-07:00",
         "currencyCode": "USD",
         "card": {
             "entryMode": "M",
             "present": "N",
             "token": {
                 "value": "8054454002400015"
             },
             "type": "MC",
             "number": "XXXXXXXXXXXX0015"
         },
         "amount": {
             "total": 111
         },
         "transaction": {
             "invoice": "1625",
             "responseCode": "A",
             "authSource": "F"
         },
         "receipt": [
             {
                 "key": "CardEntryMode",
                 "printName": "ENTRY METHOD",
                 "printValue": "KEYED"
             },
             {
                 "key": "MaskedPAN",
                 "printName": "PAN",
                 "printValue": "XXXXXXXXXXXX0015"
             },
             {
                 "key": "TransactionResponse",
                 "printName": "Response",
                 "printValue": "APPROVED"
             },
             {
                 "key": "TransactionDate",
                 "printName": "9A",
                 "printValue": "250410"
             },
             {
                 "key": "TransactionTime",
                 "printName": "9F21",
                 "printValue": "171739"
             },
             {
                 "key": "TransactionCurrencyCode",
                 "printName": "CURRENCY CODE",
                 "printValue": "USD $"
             },
             {
                 "key": "SignatureRequired",
                 "printName": "IS SIGNATURE REQUIRED",
                 "printValue": "Y"
             }
         ],
         "threeDSecure": {
             "trxId": "2bf0e02b-ffb2-4388-9d4c-c2640cc10b9b",
             "securityLevelIndicator": "210",
             "cryptogram": "Qm181okmdyqh6yQmYuq1890QAAA=",
             "ecommIndicator": "5",
             "programProtocol": "1",
             "version": "2.1.0",
             "directoryServerTranId": "8827fa9c-fd15-4a44-a51d-3c0cdddf93ba"
         },
         "server": {
             "name": "sock_00.finaroproc.CE-APM-V01"
         }
     }
   ]
 }
Previous page
Next page