--- updatedAt: 2025-09-23T21:11:32.000Z agentTools: projectIndex: https://developers.berkeleypayment.com/llms.txt --- # Introduction ## 3D Secure EMV® Three-Domain Secure (3DS) is a messaging protocol developed by EMVCo (Europay, Mastercard, Visa and some other card schemes) to enable consumers to authenticate themselves with their card issuer when making card-not-present (CNP) e-commerce purchases. The additional security layer helps prevent unauthorized CNP transactions and protects the merchant from CNP exposure to fraud. This service is available in Canada as well as in USA. Berkeley's implementation of 3D Secure allow our clients to take the advantage of risk-based authentication and liability shift that 3D Secure offers with the benefits of DirectSend real-time transactions. > 📘 In order to call the 3DS endpoints a cardholder and financial account need to be created. All versions of 3D Secure supports 'risk based authentication\`. This is where the consumer's bank (the issuer) uses information gathered from the user as well as the user's device information to authenticate the user. If they are able to do so without soliciting additional info from the consumer this is considered 'risk based authentication' and the process continues seamlessly without additional input from the consumer ### Step 1 - Tokenize card Tokenize an existing card using the [V1](https://developers.berkeleypayment.com/reference/createtokenpaymentcard) or [V2 ](https://developers.berkeleypayment.com/reference/createtokenpaymentcard1) tokenization endpoints ### Step 2 - Create account holder Create an account holder using You will need the *id* of the response in the next step ### Step 3 - Create financial account This links the cardholder to the financial account. Use passing the id from the *Create account holder* step into *account\_holder\_id* You will need the *id* of the response in the next step, this the financial account token. ### Step 4 - Authenticate browser Call [AuthenticateBrowser](https://bps.readme.io/reference/3dsauthenticatebrowser) passing in the *id* from step 3 into the *financial\_account* parameter. The first payment request creates the 3DS authentication transaction, giving us the required data to communicate with the ACS performing risk based authentication. When securing card payments in the browser, the response from the `/authenticate/browser` determines which ACS (bank or bank partner) does a risk assessment of the transaction. The data returned will be different for 1.0 and 2.0 responses. * The response should be used to setup the iFrame that will handle the device fingerprinting. * Key response fields: * `method_url`: This is the url used to gather device information. * `three_ds_method_data`: Base64 encoded json with the notificationUrl, transactionId to send to the ACS for device fingerprinting. This should be setup in a 1x1 iframe. * There are two types of responses. * Most cases, the 2.0 responses will have a `method_url` that indicates an iframe needs to be created for fingerprinting. Follow the next steps in order to move forward. * In rare occasions the response will return without a `method_url`. In that case, fingerprinting will not need to happen but instead, take the transaction ID and make the call straight to get the [results](https://bps.readme.io/docs/berkeley-api-documentation#card-issuing-1). ### Step 5 **Device Fingerprinting** A URL and data is returned in the authenticate/browser. The URL is the where you will post the iframe and pass in the data that was given. This is the fingerprinting portion. The ACS will connect to the browser and extract meta data that will be cross referenced with the clients purchase history. Based on that information the transaction will be authenticated. In your browser, you need to create a hidden iframe and POST with the appropriate content based on the protocol version you received in the previous call. * `three_ds_method_data` and `method_url` > 🚧 > > Browser ONLY\ > This portion of the flow needs to happen in a browser. There is no other way around it. Browser ONLY This portion of the flow needs to happen in a browser. There is no other way around it. ```HTML ``` ### Step 6 **Make[Get 3DS Status](https://bps.readme.io/reference/3dsgetstatus) API call** After the fingerprinting is finished, a GET call will need to be made. The response returned will advise if the transaction got authenticated, not authenticated, or challenged. > 📘 > > Your request to retrieve tokens can last up to **15 seconds**. During that time, we continually listen for updates. Therefore, you will get the authentication results as soon as they are available! * Check for the status of the device fingerprinting with the **ACS** using the Get Status API request * Key response fields: * `status`: Current status of **3DS authentication.** * `acs_url`: Fully qualified URL of the ACS to be used for the challenge. * `creq`: Base64 encoded CReq that needs to be sent to the ACS when the status is C (challenge required) * In the case that status is `authenticated` this is the final step for a successful authentication. The **3DS** authentication id can be attached to an associated transaction request. > 📘 Information > > For the purposes of DirectPull transactions, the following properties are important > > You will need to pass the 3DS authentication `id` in the `three_d_secure_id` field of the DirectSend [Create Pull Transaction](https://bps.readme.io/reference/createpulltransaction) ### Step 7 **Challenge Request** In case of status is `challenge_required` we know that the ACS requires a challenge. As such, there are a couple more steps to respond to a 2.0 challenge. #### Open the Challenge Request URL in an iframe From the previous response, we need to extract the `acs_url` and the `creq` properties. In the browser, we will setup an iframe which sends the CReq to the ACS URL (similar to the device fingerprinting) The ACS will then present a UI within that iframe for the user to complete. Example of a ACS challenge iframe form: ```HTML ``` In 2.0, the challenge flow requires 2 iframe: * The initial browser fingerprinting for sending the `three_ds_method_data` * The challenge UI for sending the CReq and responding to the challenge This is **different from 1.0** . In 3DS version 1, only one iframe is required. When integrating, ensure that two separate iframes can be used! #### Retrieving Results for a Challenge After completing the challenge requests, we make another [Get Status](https://developers.berkeleypayment.com/#29a64276-3db9-4836-81ae-c375a13e6a35) request. *** **Recurring Transactions** In general, for the very first transaction when a customer sets up a recurring payment, it is recommended that you establish a secure authentication by requesting a cardholder challenge (**challenge\_indicator** = *03*).  Any subsequent transactions are out of scope from the 3D Secure requirements. > ❗️ > > Original 3-D Secure only provided chargeback protection against the first transaction whereas EMV 3DS protects all recurring transactions.\ > By applying 3D Secure to the first transaction or verification, you signal to the card issuer that you have established a mandate between you and your customer to charge their payment method for subsequent recurring payments as detailed in your terms and conditions. Such subsequent transactions are out of scope from PSD2 SCA requirements. > 📘 Related pages > > [3DS Status Codes](https://bps.readme.io/docs/3ds-status-codes)\ > [3DS Test Cards](https://bps.readme.io/docs/3ds-test-cards)\ > [Test Cards](https://bps.readme.io/docs/test-cards)