{"_id":"5bbf93937ef195000329c61b","category":{"_id":"5bbf93937ef195000329c600","version":"5bbf93937ef195000329c63e","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-11-03T20:45:01.593Z","from_sync":false,"order":7,"slug":"topics","title":"Guides"},"project":"57336fd5a6a9c40e00e13a0b","user":"560d5913af97231900938124","parentDoc":null,"version":{"_id":"5bbf93937ef195000329c63e","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"5b8ec56484303f0003a1145f","createdAt":"2018-04-23T14:36:48.535Z","releaseDate":"2018-04-23T14:36:48.535Z","categories":["5bbf93937ef195000329c5f9","5bbf93937ef195000329c5fa","5bbf93937ef195000329c5fb","5bbf93937ef195000329c5fc","5bbf93937ef195000329c5fd","5bbf93937ef195000329c5fe","5bbf93937ef195000329c5ff","5bbf93937ef195000329c600"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"3.27.1 Release","version_clean":"8976.0.0-Basics","version":"8976-Basics"},"githubsync":"","__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-12-29T15:04:53.922Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"BlueSnap's Payment API supports 3D Secure, a tool that provides an additional layer of security for online card transactions. A lookup performed during checkout determines if the issuer requires shopper identity verification. If required, a popup will appear, which typically prompts the shopper to enter a password. \n\nThis guide covers the following topics: \n* [3D Secure flow](#section-3d-secure-flow)\n* [Supported cards](#section-supported-cards)\n* [Implementing 3D Secure](#section-implementing-3d-secure)\n* [Processing payments with data from external Merchant Plug-In (MPI)](#section-processing-payments-with-data-from-external-merchant-plug-in-mpi-)\n* [Sandbox testing](#section-sandbox-testing)\n\n# 3D Secure flow\n[block:html]\n{\n  \"html\": \"<div class=\\\"outer-container container\\\">\\n  <div class=\\\"outer col-md-4\\\">\\n    <div class=\\\"inner\\\">\\n    \\t<i class=\\\"fa fa-credit-card fa-lg\\\"></i>\\n      <p><strong>1</strong>. Shopper enters card information.\\n      </p>\\n    </div>\\n  </div>\\n  <div class=\\\"outer col-md-4\\\">\\n  \\t<div class=\\\"inner\\\">\\n    \\t<i class=\\\"fa fa-search fa-lg\\\"></i>\\n      <p><strong>2</strong>. A lookup determines if shopper authentication is required.</p>\\n    </div>\\n  </div>\\n  <div class=\\\"outer col-md-4\\\">\\n  \\t<div class=\\\"inner\\\">\\n    \\t<i class=\\\"fa fa-external-link-square fa-lg\\\"></i>\\n      <p><strong>3</strong>. If required, a popup appears asking shopper for credentials.</p>\\n    </div>\\n  </div>\\n  <div class=\\\"outer col-md-4\\\">\\n  \\t<div class=\\\"inner\\\">\\n    \\t<i class=\\\"fa fa-key fa-lg\\\"></i>\\n      <p><strong>4</strong>. Shopper enters credentials and finalizes payment.</p>\\n    </div>\\n  </div>\\n  <div class=\\\"outer col-md-4\\\">\\n  \\t<div class=\\\"inner\\\">\\n\\t\\t\\t<i class=\\\"fa fa-code fa-lg\\\"></i>\\n      <p><strong>5</strong>. Merchant gets 3D Secure result and processes payment.</p>\\n    </div>\\n  </div>\\n  <div class=\\\"outer col-md-4\\\">\\n  \\t<div class=\\\"inner\\\">\\n    \\t<i class=\\\"fa fa-check fa-lg\\\"></i>\\n      <p><strong>6</strong>. Shopper gets confirmation of successful payment.</p>     \\n    </div>\\n  </div>\\n</div>\\n\\n<style>\\n  .outer-container {\\n    text-align: center;\\n  }\\n  .outer {\\n    padding: 2px; \\n  }\\n  .inner {\\n    height: 100%; \\n    width: 100%; \\n    border: 1px solid #dddddd;\\n    border-radius: 6px;\\n    padding: 11px 8px 2px 8px;\\n  }\\n  .inner > i {\\n    font-size: 25px;\\n    margin-bottom: 5px;\\n  }\\n</style>\"\n}\n[/block]\n# Supported cards\nAmerican Express, Diner's Club, Discover, Mastercard, Visa\n\n# Implementing 3D Secure\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Before you get started:\",\n  \"body\": \"1. Make sure you've implemented the latest version of [Hosted Payment Fields](/v8976-Tools/docs/hosted-payment-fields) or [Client-Side Encryption](/docs/client-side-encryption).\\n\\n2. Contact [Merchant Support](https://bluesnap.zendesk.com/hc/en-us/requests/new?ticket_form_id=360000127087) and ask for 3D Secure to be enabled for your account. \\n\\n3. After it has been enabled, activate 3D Secure in your BlueSnap Console by going to **Settings > Fraud Settings** and selecting **Enable 3D Secure**.\"\n}\n[/block]\nFollow the steps in the applicable section to learn how to implement 3D Secure.   \n\n* [3D Secure in Hosted Payment Fields](#section-3d-secure-in-hosted-payment-fields)\n* [3D Secure in Client-Side Encryption](#section-3d-secure-in-client-side-encryption)\n\n## 3D Secure in Hosted Payment Fields\nIf you're using Hosted Payment Fields, implementing 3D Secure will consist of these steps:\n\n* [Step 1: Prevent shopper from submitting form during 3D Secure setup](#section-step-1-prevent-shopper-from-submitting-form-during-3d-secure-setup)\n* [Step 2: Allow 3D Secure usage in the transaction](#section-step-2-allow-3d-secure-usage-in-the-transaction)\n* [Step 3: Account for 3D Secure errors](#section-step-3-account-for-3d-secure-errors)\n* [Step 4: Create 3D Secure object with transaction data](#section-step-4-create-3d-secure-object-with-transaction-data)\n* [Step 5: Determine 3D Secure result](#section-step-5-determine-3d-secure-result)\n* [Step 6: Process the transaction with Hosted Payment Fields token](#section-step-6-process-the-transaction-with-hosted-payment-fields-token)\n\n### Step 1: Prevent shopper from submitting form during 3D Secure setup\nIf the shopper submits the payment form while BlueSnap is setting up 3D Secure, an error may occur. It's important to allow BlueSnap to deactivate your submit button during this time to avoid any errors. To do this, add a `data-bluesnap` attribute to your submit button element and set its value to **submitButton**. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<button data-bluesnap=\\\"submitButton\\\" type=\\\"submit\\\" id=\\\"submit-button\\\">Pay Now</button>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nPlease note: It's very important you define the `data-bluesnap` value exactly as shown above. Otherwise, BlueSnap will not be able to properly deactivate the button. \n\n### Step 2: Allow 3D Secure usage in the transaction\nAllow 3D Secure usage in the transaction by adding the property `'3DS'` to `bsObj` and set its value to **true**.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var bsObj = {\\n  ... \\n  '3DS': true\\n}; \",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n### Step 3: Account for 3D Secure errors\nBlueSnap will pass 3D Secure error codes and descriptions (listed below) to your `onError` callback function as the `errorCode` and `errorDescription` parameters. Update your `onError` callback function to account for these errors. \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Code\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"How to resolve\",\n    \"0-2\": \"Make sure 3D Secure is enabled\",\n    \"0-0\": \"14100\",\n    \"0-1\": \"3D Secure is not enabled\",\n    \"1-0\": \"14101\",\n    \"1-1\": \"3D Secure authentication was failed because the shopper did not enter correct credentials\\n\\n*Inform the shopper to try a different payment method*\",\n    \"2-0\": \"14102\",\n    \"2-1\": \"3D Secure object is missing required fields { ... }\\n\\n\\n*See Step 4 for more details on the 3D Secure object and its requirements*\",\n    \"1-2\": \"Inform shopper to try again with a different payment method.\",\n    \"2-2\": \"Add the required properties to your 3D Secure object.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n### Step 4: Create 3D Secure object with transaction data\nCreate a 3D Secure object with at least the transaction amount and currency, as shown in the code below. You'll pass your object as an additional parameter to `bluesnap.submitCredentials` (shown in Step 5). \n\nWhen the shopper hits the submit button, the data you provide within your object will be sent to the issuer during the lookup and they will decide if shopper authentication is required. In some cases, the issuer may authenticate the transaction (and assume fraud chargeback liability) without requiring the shopper to enter their credentials in the popup screen, making the 3D Secure flow entirely transparent. \n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"Provide as much transaction data as possible to improve the issuer's ability to authenticate the transaction without requiring the shopper to enter their credentials during checkout (see [Supported 3D Secure object properties](#section--supported-3d-secure-object-properties-)).\",\n  \"title\": \"Provide as much transaction data as possible\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var threeDSecureObj = {\\n  amount: 35.75, \\n  currency: 'USD'\\n  ...\\n}; \",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n###### **Supported 3D Secure object properties**\n`amount` &nbsp;&nbsp;&nbsp; *decimal* &nbsp;&nbsp;&nbsp;<span style=\"color:#F37500\">**required**</span>\n`currency` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;<span style=\"color:#F37500\">**required**</span>\n`billingFirstName` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`billingLastName` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`billingCountry` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`billingState` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`billingCity` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`billingAddress` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`billingZip` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`shippingFirstName` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`shippingLastName` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`shippingCountry` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`shippingState` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`shippingCity` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`shippingAddress` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`shippingZip` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`email` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n`phone` &nbsp;&nbsp;&nbsp; *string* &nbsp;&nbsp;&nbsp;optional\n\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n### Step 5: Determine 3D Secure result\nBlueSnap will pass the 3D Secure result to your purchase function callback as `cardData.threeDSecure.authResult`, which will have one of the values in the table below. Configure your purchase function callback to determine the 3D Secure result and take appropriate action (see code below for a simple `bluesnap.submitCredentials` call with the changes from Steps 4 and 5). \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Value\",\n    \"h-1\": \"Description\",\n    \"2-0\": \"AUTHENTICATION_SUCCEEDED\",\n    \"0-0\": \"AUTHENTICATION_UNAVAILABLE\",\n    \"1-0\": \"AUTHENTICATION_BYPASSED\",\n    \"2-1\": \"3D Secure authentication was successful because the shopper entered their credentials correctly or the issuer authenticated the transaction without requiring shopper identity verification. This transaction is eligible for a 3D Secure chargeback liability shift. \\n\\n*[Process the 3D Secure transaction](#section-step-6-process-the-transaction-with-hosted-payment-fields-token).*\",\n    \"0-1\": \"3D Secure is unavailable for this card or a technical error occurred. \\n\\n*[Process the transaction without 3D Secure](#section-step-6-process-the-transaction-with-hosted-payment-fields-token).*\",\n    \"1-1\": \"3D Secure authentication was bypassed due to the merchant's configuration. \\n\\n*[Process the transaction without 3D Secure](#section-step-6-process-the-transaction-with-hosted-payment-fields-token).*\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nThe below code calls `bluesnap.submitCredentials` with a simple purchase callback function and the 3D Secure object from Step 4.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"bluesnap.submitCredentials(function(cardData) {\\n  console.log(\\\"Card type is \\\" + cardData.ccType + \\n              \\\". Last 4 digits are \\\" + cardData.last4Digits + \\n              \\\". Exp is \\\" + cardData.exp + \\n              \\\". Issuing country is \\\" + cardData.issuingCountry + \\n              \\\". 3D Secure result is \\\" + (cardData.threeDSecure != null ? cardData.threeDSecure.authResult : null) + \\\".\\\");\\n  // submit form to server & process transaction\\n}, threeDSecureObj);\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n### Step 6: Process the transaction with Hosted Payment Fields token\nProcess 3D Secure transactions (or save shopper payment details) from your server the same way you handle regular card payments - by including your token within the `pfToken` property in the request. See the [Hosted Payment Fields guide](/v8976-Tools/docs/hosted-payment-fields#section-in-the-payment-api) for Payment API code samples with `pfToken`.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"When the shopper's account is debited for the transaction, the Charge IPN will be sent with the `3DStatus` parameter, which will allow you to verify the 3D Secure result. Make sure to [enable IPNs for your account](https://support.bluesnap.com/docs/ipn-setup).\",\n  \"title\": \"Verifying 3D Secure result\"\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n## 3D Secure in Client-Side Encryption \nIf you're using Client-Side Encryption, implementing 3D Secure will consist of these steps:\n\n* [Step 1: Add data-bluesnap attributes](#section-step-1-add-data-bluesnap-attributes)\n* [Step 2: Obtain 3D Secure token for the session](#section-step-2-obtain-3d-secure-token-for-the-session)\n* [Step 3: Call bluesnap.init3DS to set up 3D Secure](#section-step-3-call-bluesnap-init3ds-to-set-up-3d-secure)\n* [Step 4: Create a 3D Secure object with transaction data](#section-step-4-create-a-3d-secure-object-with-transaction-data)\n* [Step 5: Call bluesnap.encrypt with 3D Secure object and callback function](#section-step-5-call-bluesnap-encrypt-with-3d-secure-object-and-callback-function)\n* [Step 6: Process the transaction with encrypted data](#section-step-6-process-the-transaction-with-encrypted-data)\n\n### Step 1: Add data-bluesnap attributes\nAdd `data-bluesnap` attributes to the expiration month and year fields on your checkout form and set the values to **expirationMonth** and **expirationYear**, respectively (shown below). This will allow BlueSnap to access these fields during checkout, which are required as part of the 3D Secure authentication flow. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"  <div>\\n    <label for=\\\"Expiration\\\">Exp. (MM/YYYY)</label>\\n      <input data-bluesnap=\\\"expirationMonth\\\" type=\\\"text\\\" name=\\\"exp-month\\\" id=\\\"exp-month\\\" size=\\\"2\\\">\\n      <span> / </span>\\n      <input data-bluesnap=\\\"expirationYear\\\" type=\\\"text\\\" name=\\\"exp-year\\\" id=\\\"exp-year\\\" size=\\\"4\\\">\\n  </div>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\nAdd a `data-bluesnap` attribute to your submit button element and set its value to **submitButton** (shown below). This will allow BlueSnap to deactivate your button during the 3D Secure setup process, which you'll begin in Step 3 by calling `bluesnap.init3DS`. The shopper will be prevented from submitting the payment form during the setup process, eliminating the potential for any errors that could result.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<button data-bluesnap=\\\"submitButton\\\" type=\\\"submit\\\" id=\\\"submit-button\\\">Pay Now</button>\",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n### Step 2: Obtain 3D Secure token for the session\nObtain the 3D Secure token for the session by sending a [Create 3D Secure Token](/v8976-Tools/docs/create-3d-secure-token) request, which is a server-to-server POST request sent to:\n`/services/2/threeDSecure`\n\nThe response will provide the token as the value of the `threeDSecureToken` property (shown below). Grab the token and send it to the client for the next step.   \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"threeDSecureToken\\\": \\\"eyJhbGciOiJIU...\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Create 3D Secure Token Response\"\n    }\n  ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n### Step 3: Call bluesnap.init3DS to set up 3D Secure\nAfter the checkout page has been loaded, begin the 3D Secure setup process by calling `bluesnap.init3DS` with the following parameters: \n1. The 3D Secure token (obtained in the prior step)\n2. A callback function to handle an error if it occurs\n\nWhen `bluesnap.init3DS` is called, BlueSnap will disable the submit button (which is possible since you added the `data-bluesnap` attribute in Step 1) and set up 3D Secure. When the process is complete, BlueSnap will re-enable the button and call the provided function. \n\nThe below code calls `bluesnap.init3DS` with its required parameters. Note that `result` will always be empty. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"bluesnap.init3DS(threeDSecureToken, function(result, error) {\\n  if (error != null) {\\n    // Handle the error. See below. \\n  } else {\\n    // 3D Secure setup was a success. No further action is required. \\n    return; \\n  }\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n###### **Handling setup errors**\nIf an error occurs during the setup process, `error` will have the following format. Handle the error by calling `bluesnap.init3DS` with a valid token.       \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"errorCode\\\": \\\"14102\\\",\\n  \\\"errorDescription\\\": \\\"3D Secure object is missing required fields { threeDSecureToken }\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Error example\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"To disable 3D Secure for a specific transaction, remove the `bluesnap.init3DS` call.\",\n  \"title\": \"Disabling 3D Secure for a specific transaction\"\n}\n[/block]\n### Step 4: Create a 3D Secure object with transaction data  \nCreate a 3D Secure object with at least the transaction amount and currency (shown below). In the next step, you'll call `bluesnap.encrypt` with your object (in addition to other parameters), which will allow BlueSnap to send this information to the card issuer to consider as part of their decision whether shopper authentication is required.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"Provide as much transaction data as possible because it can improve the issuer's ability to authenticate the transaction (and assume fraud chargeback liability) without requiring the shopper to enter their credentials in the popup screen, making the 3D Secure flow entirely transparent and reducing checkout friction (see [Supported 3D Secure object properties](#section--supported-3d-secure-object-properties-)).\",\n  \"title\": \"Provide as much transaction data as possible\"\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var threeDSecureObj = {\\n  amount: 35.75, \\n  currency: 'USD'\\n  ...\\n}; \",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n### Step 5: Call bluesnap.encrypt with 3D Secure object and callback function\nWhen the shopper hits the submit button, call `bluesnap.encrypt` like you would normally, but add two additional parameters: \n1. The 3D Secure object (created in the prior step) \n2. A callback function to handle the authentication result (or error)\n\nWhen the shopper submits their payment and `bluesnap.encrypt` is called, BlueSnap will send the 3D Secure object to the issuer and they will decide whether shopper authentication is required. After the authentication process is complete, BlueSnap will encrypt the payment form and call the provided function with the authentication result (or error).  \n\nThe below code calls `bluesnap.encrypt` with its required parameters. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"bluesnap.encrypt(\\\"formID\\\", threeDSecureObj, function(result, error) {\\n  if (error != null) {\\n    // Handle the error. See below. \\n  } else {\\n    // Handle the authentication result. See below.\\n  }\\n}); \",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n###### **Handling authentication errors**\nIf an error occurs during the authentication process, `error` will have the format of the following example and it will contain a set of values from the table below, which explains how to handle the error accordingly.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"errorCode\\\": \\\"14101\\\",\\n  \\\"errorDescription\\\": \\\"3D Secure authentication was failed because the shopper did not enter correct credentials\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Error example\"\n    }\n  ]\n}\n[/block]\nPossible error values: \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Code\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"14101\",\n    \"0-1\": \"3D Secure authentication was failed because the shopper did not enter correct credentials\\n\\n*Inform the shopper to try a different payment method*\",\n    \"1-0\": \"14102\",\n    \"1-1\": \"3D Secure object is missing required fields { ... }\\n\\n*Make sure 3D Secure object has both transaction amount and currency*\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\n###### **Handling authentication results**\nIf no errors occur during the authentication process, `result` will have the format of the following example and `authResult` will contain one of the values from the table below, which explains how to process the transaction accordingly.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"threeDSecure\\\":{\\n    \\\"authResult\\\":\\\"AUTHENTICATION_SUCCEEDED\\\",\\n    \\\"threeDSecureResultToken\\\":\\\"eyJhbGciOiJIU...\\\"\\n  },\\n  \\\"encryptedCardNumber\\\":\\\"$bsjs_1_0_3$odPj3U+Ap98...\\\",\\n  \\\"encryptedSecurityCode\\\":\\\"$bsjs_1_0_3$a4jfpzZVitf...\\\",\\n  \\\"ccLast4Digits\\\":\\\"0002\\\",\\n  \\\"expirationYear\\\":\\\"2020\\\",\\n  \\\"expirationMonth\\\":\\\"01\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Result example\"\n    }\n  ]\n}\n[/block]\n Possible `authResult` values: \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Value\",\n    \"h-1\": \"Description\",\n    \"2-0\": \"AUTHENTICATION_SUCCEEDED\",\n    \"0-0\": \"AUTHENTICATION_UNAVAILABLE\",\n    \"1-0\": \"AUTHENTICATION_BYPASSED\",\n    \"2-1\": \"3D Secure authentication was successful because the shopper entered their credentials correctly or the issuer authenticated the transaction without requiring shopper identity verification. This transaction is eligible for a 3D Secure chargeback liability shift. \\n\\n*Send `result.threeDSecure.threeDSecureResultToken` to your server and [process the 3D Secure transaction](#section--processing-3d-secure-payments-with-encrypted-data-).*\",\n    \"0-1\": \"3D Secure is unavailable for this card or a technical error occurred. \\n\\n*[Process the transaction without 3D Secure](#section--processing-regular-card-payments-with-encrypted-data-).*\",\n    \"1-1\": \"3D Secure authentication was bypassed due to the merchant's configuration. \\n\\n*[Process the transaction without 3D Secure](#section--processing-regular-card-payments-with-encrypted-data-).*\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n### Step 6: Process the transaction with encrypted data\n###### **Processing 3D Secure payments with encrypted data**\nTo process 3D Secure payments from your server, include the `threeDSecure` object in the request and set its `threeDSecureResultToken` property to the 3D Secure result token (obtained in the last step). \n\nSample Auth Capture request: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"amount\\\": 11,\\n  \\\"softDescriptor\\\": \\\"DescTest\\\",\\n  \\\"cardHolderInfo\\\": {\\n    \\\"firstName\\\": \\\"test first name\\\",\\n    \\\"lastName\\\": \\\"test last name\\\", \\n    \\\"zip\\\": \\\"123456\\\"\\n  },\\n  \\\"currency\\\": \\\"USD\\\",\\n  \\\"creditCard\\\": {\\n    \\\"expirationYear\\\": 2023,\\n    \\\"encryptedCardNumber\\\": \\\"$bsjs_1_0_3$odPj3U+Ap98...\\\",\\n    \\\"encryptedSecurityCode\\\": \\\"$bsjs_1_0_3$a4jfpzZVitf...\\\",\\n    \\\"expirationMonth\\\": \\\"07\\\"\\n  },\\n  \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\",\\n  \\\"threeDSecure\\\": {\\n    \\\"threeDSecureResultToken\\\": \\\"eyJhbGciOiJIUzI1NiJ9.eyJqdG...\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"JSON\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"Verifying 3D Secure result\",\n  \"body\": \"When the shopper's account is debited for the transaction, the Charge IPN will be sent with the `3DStatus` parameter, which will allow you to verify the 3D Secure result. Make sure to [enable IPNs for your account](https://support.bluesnap.com/docs/ipn-setup).\"\n}\n[/block]\n###### **Processing regular card payments with encrypted data**\nTo process regular card payments (without 3D Secure authentication), follow the code samples in the [Client-Side Encryption guide](doc:client-side-encryption). \n\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n# Processing payments with data from external Merchant Plug-In (MPI)\nIf you're using an external Merchant Plug-In (MPI) for 3D Secure and you only want to process the payment through BlueSnap, first [contact Merchant Support](https://bluesnap.zendesk.com/hc/en-us/requests/new?ticket_form_id=360000127087) and inform them you're using an external MPI so that your account can be configured appropriately. \n\nTo process the payment, include the `threeDSecure` object with the following properties in the request:\n  * `eci`: ECI value. Pass **00**, **01**, or **02** for Mastercard, or **05**, **06**, or **07** for all other card types. \n  * `cavv`: Base64 encoded CAVV obtained from the external MPI. \n  * `xid`: Base64 encoded XID obtained from the external MPI. \n\nSample Auth Capture request: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"amount\\\": 11,\\n  \\\"recurringTransaction\\\": \\\"ECOMMERCE\\\",\\n  \\\"softDescriptor\\\": \\\"DescTest\\\",\\n  \\\"cardHolderInfo\\\": {\\n    \\\"firstName\\\": \\\"test first name\\\",\\n    \\\"lastName\\\": \\\"test last name\\\", \\n    \\\"zip\\\": \\\"123456\\\"\\n  },\\n  \\\"currency\\\": \\\"USD\\\",\\n  \\\"creditCard\\\": {\\n    \\\"expirationYear\\\": 2019,\\n    \\\"securityCode\\\": 111,\\n    \\\"expirationMonth\\\": \\\"07\\\",\\n    \\\"cardNumber\\\": 4012000033330026\\n  },\\n  \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\",\\n  \\\"threeDSecure\\\": {\\n    \\\"eci\\\": \\\"05\\\",\\n    \\\"cavv\\\": \\\"AAABAWFlmQAAAABjRWWZEEFgFz+A\\\",\\n    \\\"xid\\\": \\\"MGpHWm5ZWVpKclo0aUk0VmltVDA=\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"When the shopper's account is debited for the transaction, the Charge IPN will be sent with the `3DStatus` parameter, which will allow you to verify the 3D Secure result. Make sure to [enable IPNs for your account](https://support.bluesnap.com/docs/ipn-setup).\",\n  \"title\": \"Verifying 3D Secure result\"\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n# Sandbox testing \nYou may use the following cards, with any random 3-digit CVV code, to test various 3D Secure results. \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Card Type\",\n    \"h-1\": \"Card Number\",\n    \"h-2\": \"Exp. Date\",\n    \"h-3\": \"3D Secure Authentication Result\",\n    \"0-0\": \"Visa\",\n    \"0-3\": \"Success\",\n    \"0-1\": \"4000000000000002\",\n    \"0-2\": \"01/2020\",\n    \"1-2\": \"01/2020\",\n    \"2-2\": \"01/2020\",\n    \"3-2\": \"01/2020\",\n    \"4-2\": \"01/2020\",\n    \"5-2\": \"01/2020\",\n    \"1-0\": \"Visa\",\n    \"1-3\": \"Failed\",\n    \"1-1\": \"4000000000000028\",\n    \"2-0\": \"Visa\",\n    \"2-3\": \"Unavailable\",\n    \"2-1\": \"4000000000000069\",\n    \"3-0\": \"Mastercard\",\n    \"4-0\": \"Mastercard\",\n    \"5-0\": \"Mastercard\",\n    \"3-3\": \"Success\",\n    \"3-1\": \"5200000000000007\",\n    \"4-3\": \"Failed\",\n    \"4-1\": \"5200000000000023\",\n    \"5-1\": \"5200000000000064\",\n    \"5-3\": \"Unavailable\",\n    \"h-4\": \"3D Secure Authentication Result\",\n    \"0-4\": \"Success\",\n    \"1-4\": \"Failed\",\n    \"2-4\": \"Unavailable\",\n    \"3-4\": \"Success\",\n    \"4-4\": \"Failed\",\n    \"5-4\": \"Unavailable\"\n  },\n  \"cols\": 4,\n  \"rows\": 6\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>","excerpt":"","slug":"3d-secure","type":"basic","title":"3D Secure"}

BlueSnap's Payment API supports 3D Secure, a tool that provides an additional layer of security for online card transactions. A lookup performed during checkout determines if the issuer requires shopper identity verification. If required, a popup will appear, which typically prompts the shopper to enter a password.

This guide covers the following topics:

3D Secure flow

1. Shopper enters card information.

2. A lookup determines if shopper authentication is required.

3. If required, a popup appears asking shopper for credentials.

4. Shopper enters credentials and finalizes payment.

5. Merchant gets 3D Secure result and processes payment.

6. Shopper gets confirmation of successful payment.

Supported cards

American Express, Diner's Club, Discover, Mastercard, Visa

Implementing 3D Secure

Before you get started:

  1. Make sure you've implemented the latest version of Hosted Payment Fields or Client-Side Encryption.

  2. Contact Merchant Support and ask for 3D Secure to be enabled for your account.

  3. After it has been enabled, activate 3D Secure in your BlueSnap Console by going to Settings > Fraud Settings and selecting Enable 3D Secure.

Follow the steps in the applicable section to learn how to implement 3D Secure.

3D Secure in Hosted Payment Fields

If you're using Hosted Payment Fields, implementing 3D Secure will consist of these steps:

Step 1: Prevent shopper from submitting form during 3D Secure setup

If the shopper submits the payment form while BlueSnap is setting up 3D Secure, an error may occur. It's important to allow BlueSnap to deactivate your submit button during this time to avoid any errors. To do this, add a data-bluesnap attribute to your submit button element and set its value to submitButton.

<button data-bluesnap="submitButton" type="submit" id="submit-button">Pay Now</button>

Please note: It's very important you define the data-bluesnap value exactly as shown above. Otherwise, BlueSnap will not be able to properly deactivate the button.

Step 2: Allow 3D Secure usage in the transaction

Allow 3D Secure usage in the transaction by adding the property '3DS' to bsObj and set its value to true.

var bsObj = {
  ... 
  '3DS': true
}; 

Back to Top

Step 3: Account for 3D Secure errors

BlueSnap will pass 3D Secure error codes and descriptions (listed below) to your onError callback function as the errorCode and errorDescription parameters. Update your onError callback function to account for these errors.

Code
Description

14100

3D Secure is not enabled

14101

3D Secure authentication was failed because the shopper did not enter correct credentials

Inform the shopper to try a different payment method

14102

3D Secure object is missing required fields { ... }

See Step 4 for more details on the 3D Secure object and its requirements

Step 4: Create 3D Secure object with transaction data

Create a 3D Secure object with at least the transaction amount and currency, as shown in the code below. You'll pass your object as an additional parameter to bluesnap.submitCredentials (shown in Step 5).

When the shopper hits the submit button, the data you provide within your object will be sent to the issuer during the lookup and they will decide if shopper authentication is required. In some cases, the issuer may authenticate the transaction (and assume fraud chargeback liability) without requiring the shopper to enter their credentials in the popup screen, making the 3D Secure flow entirely transparent.

Provide as much transaction data as possible

Provide as much transaction data as possible to improve the issuer's ability to authenticate the transaction without requiring the shopper to enter their credentials during checkout (see Supported 3D Secure object properties).

var threeDSecureObj = {
  amount: 35.75, 
  currency: 'USD'
  ...
}; 
Supported 3D Secure object properties

amount     decimal    required
currency     string    required
billingFirstName     string    optional
billingLastName     string    optional
billingCountry     string    optional
billingState     string    optional
billingCity     string    optional
billingAddress     string    optional
billingZip     string    optional
shippingFirstName     string    optional
shippingLastName     string    optional
shippingCountry     string    optional
shippingState     string    optional
shippingCity     string    optional
shippingAddress     string    optional
shippingZip     string    optional
email     string    optional
phone     string    optional

Back to Top

Step 5: Determine 3D Secure result

BlueSnap will pass the 3D Secure result to your purchase function callback as cardData.threeDSecure.authResult, which will have one of the values in the table below. Configure your purchase function callback to determine the 3D Secure result and take appropriate action (see code below for a simple bluesnap.submitCredentials call with the changes from Steps 4 and 5).

Value
Description

AUTHENTICATION_UNAVAILABLE

3D Secure is unavailable for this card or a technical error occurred.

Process the transaction without 3D Secure.

AUTHENTICATION_BYPASSED

3D Secure authentication was bypassed due to the merchant's configuration.

Process the transaction without 3D Secure.

AUTHENTICATION_SUCCEEDED

3D Secure authentication was successful because the shopper entered their credentials correctly or the issuer authenticated the transaction without requiring shopper identity verification. This transaction is eligible for a 3D Secure chargeback liability shift.

Process the 3D Secure transaction.

The below code calls bluesnap.submitCredentials with a simple purchase callback function and the 3D Secure object from Step 4.

bluesnap.submitCredentials(function(cardData) {
  console.log("Card type is " + cardData.ccType + 
              ". Last 4 digits are " + cardData.last4Digits + 
              ". Exp is " + cardData.exp + 
              ". Issuing country is " + cardData.issuingCountry + 
              ". 3D Secure result is " + (cardData.threeDSecure != null ? cardData.threeDSecure.authResult : null) + ".");
  // submit form to server & process transaction
}, threeDSecureObj);

Step 6: Process the transaction with Hosted Payment Fields token

Process 3D Secure transactions (or save shopper payment details) from your server the same way you handle regular card payments - by including your token within the pfToken property in the request. See the Hosted Payment Fields guide for Payment API code samples with pfToken.

Verifying 3D Secure result

When the shopper's account is debited for the transaction, the Charge IPN will be sent with the 3DStatus parameter, which will allow you to verify the 3D Secure result. Make sure to enable IPNs for your account.

Back to Top

3D Secure in Client-Side Encryption

If you're using Client-Side Encryption, implementing 3D Secure will consist of these steps:

Step 1: Add data-bluesnap attributes

Add data-bluesnap attributes to the expiration month and year fields on your checkout form and set the values to expirationMonth and expirationYear, respectively (shown below). This will allow BlueSnap to access these fields during checkout, which are required as part of the 3D Secure authentication flow.

  <div>
    <label for="Expiration">Exp. (MM/YYYY)</label>
      <input data-bluesnap="expirationMonth" type="text" name="exp-month" id="exp-month" size="2">
      <span> / </span>
      <input data-bluesnap="expirationYear" type="text" name="exp-year" id="exp-year" size="4">
  </div>

Add a data-bluesnap attribute to your submit button element and set its value to submitButton (shown below). This will allow BlueSnap to deactivate your button during the 3D Secure setup process, which you'll begin in Step 3 by calling bluesnap.init3DS. The shopper will be prevented from submitting the payment form during the setup process, eliminating the potential for any errors that could result.

<button data-bluesnap="submitButton" type="submit" id="submit-button">Pay Now</button>

Step 2: Obtain 3D Secure token for the session

Obtain the 3D Secure token for the session by sending a Create 3D Secure Token request, which is a server-to-server POST request sent to:
/services/2/threeDSecure

The response will provide the token as the value of the threeDSecureToken property (shown below). Grab the token and send it to the client for the next step.

{
  "threeDSecureToken": "eyJhbGciOiJIU..."
}

Back to Top

Step 3: Call bluesnap.init3DS to set up 3D Secure

After the checkout page has been loaded, begin the 3D Secure setup process by calling bluesnap.init3DS with the following parameters:

  1. The 3D Secure token (obtained in the prior step)
  2. A callback function to handle an error if it occurs

When bluesnap.init3DS is called, BlueSnap will disable the submit button (which is possible since you added the data-bluesnap attribute in Step 1) and set up 3D Secure. When the process is complete, BlueSnap will re-enable the button and call the provided function.

The below code calls bluesnap.init3DS with its required parameters. Note that result will always be empty.

bluesnap.init3DS(threeDSecureToken, function(result, error) {
  if (error != null) {
    // Handle the error. See below. 
  } else {
    // 3D Secure setup was a success. No further action is required. 
    return; 
  }
});
Handling setup errors

If an error occurs during the setup process, error will have the following format. Handle the error by calling bluesnap.init3DS with a valid token.

{
  "errorCode": "14102",
  "errorDescription": "3D Secure object is missing required fields { threeDSecureToken }"
}

Disabling 3D Secure for a specific transaction

To disable 3D Secure for a specific transaction, remove the bluesnap.init3DS call.

Step 4: Create a 3D Secure object with transaction data

Create a 3D Secure object with at least the transaction amount and currency (shown below). In the next step, you'll call bluesnap.encrypt with your object (in addition to other parameters), which will allow BlueSnap to send this information to the card issuer to consider as part of their decision whether shopper authentication is required.

Provide as much transaction data as possible

Provide as much transaction data as possible because it can improve the issuer's ability to authenticate the transaction (and assume fraud chargeback liability) without requiring the shopper to enter their credentials in the popup screen, making the 3D Secure flow entirely transparent and reducing checkout friction (see Supported 3D Secure object properties).

var threeDSecureObj = {
  amount: 35.75, 
  currency: 'USD'
  ...
}; 

Back to Top

Step 5: Call bluesnap.encrypt with 3D Secure object and callback function

When the shopper hits the submit button, call bluesnap.encrypt like you would normally, but add two additional parameters:

  1. The 3D Secure object (created in the prior step)
  2. A callback function to handle the authentication result (or error)

When the shopper submits their payment and bluesnap.encrypt is called, BlueSnap will send the 3D Secure object to the issuer and they will decide whether shopper authentication is required. After the authentication process is complete, BlueSnap will encrypt the payment form and call the provided function with the authentication result (or error).

The below code calls bluesnap.encrypt with its required parameters.

bluesnap.encrypt("formID", threeDSecureObj, function(result, error) {
  if (error != null) {
    // Handle the error. See below. 
  } else {
    // Handle the authentication result. See below.
  }
}); 
Handling authentication errors

If an error occurs during the authentication process, error will have the format of the following example and it will contain a set of values from the table below, which explains how to handle the error accordingly.

{
  "errorCode": "14101",
  "errorDescription": "3D Secure authentication was failed because the shopper did not enter correct credentials"
}

Possible error values:

Code
Description

14101

3D Secure authentication was failed because the shopper did not enter correct credentials

Inform the shopper to try a different payment method

14102

3D Secure object is missing required fields { ... }

Make sure 3D Secure object has both transaction amount and currency

Handling authentication results

If no errors occur during the authentication process, result will have the format of the following example and authResult will contain one of the values from the table below, which explains how to process the transaction accordingly.

{
  "threeDSecure":{
    "authResult":"AUTHENTICATION_SUCCEEDED",
    "threeDSecureResultToken":"eyJhbGciOiJIU..."
  },
  "encryptedCardNumber":"$bsjs_1_0_3$odPj3U+Ap98...",
  "encryptedSecurityCode":"$bsjs_1_0_3$a4jfpzZVitf...",
  "ccLast4Digits":"0002",
  "expirationYear":"2020",
  "expirationMonth":"01"
}

Possible authResult values:

Value
Description

AUTHENTICATION_UNAVAILABLE

3D Secure is unavailable for this card or a technical error occurred.

Process the transaction without 3D Secure.

AUTHENTICATION_BYPASSED

3D Secure authentication was bypassed due to the merchant's configuration.

Process the transaction without 3D Secure.

AUTHENTICATION_SUCCEEDED

3D Secure authentication was successful because the shopper entered their credentials correctly or the issuer authenticated the transaction without requiring shopper identity verification. This transaction is eligible for a 3D Secure chargeback liability shift.

Send result.threeDSecure.threeDSecureResultToken to your server and process the 3D Secure transaction.

Back to Top

Step 6: Process the transaction with encrypted data

Processing 3D Secure payments with encrypted data

To process 3D Secure payments from your server, include the threeDSecure object in the request and set its threeDSecureResultToken property to the 3D Secure result token (obtained in the last step).

Sample Auth Capture request:

{
  "amount": 11,
  "softDescriptor": "DescTest",
  "cardHolderInfo": {
    "firstName": "test first name",
    "lastName": "test last name", 
    "zip": "123456"
  },
  "currency": "USD",
  "creditCard": {
    "expirationYear": 2023,
    "encryptedCardNumber": "$bsjs_1_0_3$odPj3U+Ap98...",
    "encryptedSecurityCode": "$bsjs_1_0_3$a4jfpzZVitf...",
    "expirationMonth": "07"
  },
  "cardTransactionType": "AUTH_CAPTURE",
  "threeDSecure": {
    "threeDSecureResultToken": "eyJhbGciOiJIUzI1NiJ9.eyJqdG..."
  }
}

Verifying 3D Secure result

When the shopper's account is debited for the transaction, the Charge IPN will be sent with the 3DStatus parameter, which will allow you to verify the 3D Secure result. Make sure to enable IPNs for your account.

Processing regular card payments with encrypted data

To process regular card payments (without 3D Secure authentication), follow the code samples in the Client-Side Encryption guide.

Back to Top

Processing payments with data from external Merchant Plug-In (MPI)

If you're using an external Merchant Plug-In (MPI) for 3D Secure and you only want to process the payment through BlueSnap, first contact Merchant Support and inform them you're using an external MPI so that your account can be configured appropriately.

To process the payment, include the threeDSecure object with the following properties in the request:

  • eci: ECI value. Pass 00, 01, or 02 for Mastercard, or 05, 06, or 07 for all other card types.
  • cavv: Base64 encoded CAVV obtained from the external MPI.
  • xid: Base64 encoded XID obtained from the external MPI.

Sample Auth Capture request:

{
  "amount": 11,
  "recurringTransaction": "ECOMMERCE",
  "softDescriptor": "DescTest",
  "cardHolderInfo": {
    "firstName": "test first name",
    "lastName": "test last name", 
    "zip": "123456"
  },
  "currency": "USD",
  "creditCard": {
    "expirationYear": 2019,
    "securityCode": 111,
    "expirationMonth": "07",
    "cardNumber": 4012000033330026
  },
  "cardTransactionType": "AUTH_CAPTURE",
  "threeDSecure": {
    "eci": "05",
    "cavv": "AAABAWFlmQAAAABjRWWZEEFgFz+A",
    "xid": "MGpHWm5ZWVpKclo0aUk0VmltVDA="
  }
}

Verifying 3D Secure result

When the shopper's account is debited for the transaction, the Charge IPN will be sent with the 3DStatus parameter, which will allow you to verify the 3D Secure result. Make sure to enable IPNs for your account.

Back to Top

Sandbox testing

You may use the following cards, with any random 3-digit CVV code, to test various 3D Secure results.

Card Type
Card Number
Exp. Date
3D Secure Authentication Result

Visa

4000000000000002

01/2020

Success

Visa

4000000000000028

01/2020

Failed

Visa

4000000000000069

01/2020

Unavailable

Mastercard

5200000000000007

01/2020

Success

Mastercard

5200000000000023

01/2020

Failed

Mastercard

5200000000000064

01/2020

Unavailable