# 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](/apis/payments-platform-rest/openapi/3d-secure/3dsecurestandalone) 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](/guides/advanced-concepts/3d-secure#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](/guides/advanced-concepts/3d-secure#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](/apis/payments-platform-rest/openapi/transactions/transactionsauthorization) or [Sale/Purchase](/apis/payments-platform-rest/openapi/transactions/transactionssale) 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](/apis/payments-platform-rest/openapi/3d-secure/3dsecurecompletion) 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](/guides/advanced-concepts/3d-secure#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](/guides/advanced-concepts/3d-secure#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" } } ] } ```