{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","results":{"codes":[]},"settings":"","params":[]},"next":{"description":"","pages":[]},"title":"3-D Secure for API","type":"basic","slug":"3-d-secure-for-api","excerpt":"","body":"This guide provides information for using 3-D Secure 2 with the BlueSnap API. \n\n* For general information about 3-D Secure and 3-D Secure 2, refer to the [3-D Secure Guide](https://support.bluesnap.com/docs/3d-secure).\n* For answers to specific questions related to BlueSnap and 3-D Secure 2, PSD2, and SCA, refer to [our 3-D Secure 2 FAQs page](https://support.bluesnap.com/docs/3ds2-faqs). \n* If you're using Client-Side Encryption, please follow the instructions [here](#section-3-d-secure-with-plain-text-cards) to implement 3-D Secure. \n\nThis guide provides the following information:\n* [3-D Secure in Hosted Payment Fields](#section-3-d-secure-in-hosted-payment-fields)\n* [3-D Secure with Plain Text cards](#section-3-d-secure-with-plain-text-cards)\n* [3-D Secure with Returning Shoppers](#section-3-d-secure-with-returning-shoppers)\n* [3-D Secure in Payment Request API (W3C)](#section-3-d-secure-in-payment-request-api-w3c-)\n* [3-D Secure in Secured Payment Collector](#section-3-d-secure-in-secured-payment-collector)\n* [Processing payments with data from external Merchant Plug-In (MPI)](#section-processing-payments-with-data-from-external-merchant-plug-in-mpi-)\n* [Supported 3-D Secure object properties](#section-supported-3-d-secure-object-properties)\n* [Error codes](#section-error-codes)\n* [Authentication results](#section-authentication-results)\n\n<hr />\n[block:callout]\n{\n \"type\": \"success\",\n \"title\": \"Note\",\n \"body\": \"You don't have to apply 3-D Secure to all transactions. If you want to apply 3DS only to EU-issued cards for PSD2, but not US-issued cards, you can do that. Refer to [Step 5](https://developers.bluesnap.com/v8976-Basics/docs/3-d-secure-for-api#section-step-5-determine-3-d-secure-result) for examples.\"\n}\n[/block]\n\n[block:callout]\n{\n \"type\": \"warning\",\n \"body\": \"Since 3-D Secure uses URLs that vary based on the credit card issuer, the Content-Security-Policy (CSP) should be as permissive as possible and leverage the ‘*’ (wildcard) token. Any other CSP will likely result in a failure.\\n\\nMerchant-initiated transactions are out of scope for 3-D Secure, provided they follow a 3-D Secure Customer Initiated Transaction ([learn more](https://support.bluesnap.com/docs/3d-secure#rules-for-mits)). To make sure your transaction is identified as merchant-initiated, you must use the Merchant Managed Subscription API. Refer to [Create Merchant-Managed Subscription](https://developers.bluesnap.com/v8976-JSON/docs/create-merchant-managed-subscription) and [Create Merchant-Managed Subscription Charge](https://developers.bluesnap.com/v8976-JSON/docs/create-merchant-managed-subscription-charge) for details. \\n\\nBlueSnap applies this out-of-scope exemption to applicable transactions only for merchants who are using the [BlueSnap Subscription Engine](https://support.bluesnap.com/docs/subscription-options) or our [Merchant Managed Subscription](https://support.bluesnap.com/docs/subscription-options#section-merchant-managed-subscriptions) feature. If you handle your own **subscriptions** (that is, you are sending straight auth‑capture requests ***not*** using the BlueSnap Subscription Engine or our merchant-managed subscription feature), follow the information in the [Rules for MITs](https://support.bluesnap.com/docs/3d-secure#rules-for-mits) for more information.\",\n \"title\": \"Important\"\n}\n[/block]\n# Before you begin\nIf applicable, make sure you've implemented the latest version of [Hosted Payment Fields](/v8976-Tools/docs/hosted-payment-fields). \n\n* Enable 3-D Secure\nTo get started, contact [Merchant Support](https://bluesnap.zendesk.com/hc/en-us/requests/new?ticket_form_id=360000127087) to request that BlueSnap enable 3DS for your account. After it has been enabled, you can activate it in your Merchant Portal by going to **Settings > Fraud Settings** and selecting **Enable 3D Secure**.\n\n* [Enable IPNs for your account](https://support.bluesnap.com/docs/ipn-setup). When the shopper's account is debited for the transaction, the Charge IPN is sent with the `3DStatus` parameter, which verifies the 3-D Secure result. \n\n<hr />\n\n# 3-D Secure in Hosted Payment Fields\nIf you're using Hosted Payment Fields, implementing 3DS consists of these steps:\n\n* [Step 1: Prevent your shopper from submitting the form during 3-D Secure setup](#section-step-1-prevent-your-shopper-from-submitting-the-form-during-3-d-secure-setup)\n* [Step 2: Enable 3-D Secure usage in the transaction](#section-step-2-enable-3-d-secure-usage-in-the-transaction)\n* [Step 3: Account for 3-D Secure errors](#section-step-3-account-for-3-d-secure-errors)\n* [Step 4: Create 3-D Secure object with transaction data](#section-step-4-create-3-d-secure-object-with-transaction-data)\n* [Step 5: Determine 3-D Secure result](#section-step-5-determine-3-d-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 your shopper from submitting the form during 3-D Secure setup\nIf the shopper submits the payment form while BlueSnap is setting up 3DS, an error may occur. You must let BlueSnap deactivate the submit button while setting up 3DS. To do this, add the `data-bluesnap` attribute to your submit button element and set the value to `submitButton`, as shown here\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\n[block:callout]\n{\n \"type\": \"warning\",\n \"title\": \"Important!\",\n \"body\": \"You must define the `data-bluesnap` value exactly as shown above; otherwise, BlueSnap cannot properly deactivate the button.\"\n}\n[/block]\n## Step 2: Enable 3-D Secure usage in the transaction\nEnable 3DS 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## Step 3: Account for 3-D Secure errors\nBlueSnap passes 3DS error codes and descriptions (shown [here](#section-error-codes)) to your `onError` callback function as the `errorCode` and `errorDescription` parameters. Update your `onError` callback function to account for these errors. \n\n## Step 4: Create 3-D Secure object with transaction data\nCreate a 3DS object with at least the transaction amount and currency, as shown in the code below. \nIf you want to submit the credentials and activate 3DS, pass your object as an additional parameter to `bluesnap.hostedPaymentFieldsSubmitData` (shown in Step 5). You can also decide not to activate 3DS and not pass the object.\n\nWhen the shopper hits the submit button, the data you provide within your object is sent to the issuer during the lookup and they 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 3DS 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 (refer to [Supported 3-D Secure object properties](#section-supported-3-d-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\n## Step 5: Determine 3-D Secure result\nBlueSnap passes the 3DS result to your purchase function callback as `callBack.threeDSecure.authResult`, which has one of the values shown [here](#section-authentication-results). Configure your purchase function callback to determine the 3DS result and take appropriate action. (Refer to the code below for a simple `bluesnap.hostedPaymentFieldsSubmitData` call with the changes from Steps 4 and 5.) \n[block:callout]\n{\n \"type\": \"success\",\n \"body\": \"`callBack.threeDSecure` also includes `threeDSecureReferenceId`, a reference to the 3DS authentication.\",\n \"title\": \"Note\"\n}\n[/block]\nThe code calls `bluesnap.hostedPaymentFieldsSubmitData` with a simple purchase callback function. Here you can decide if you want to activate 3DS by either including the `threeDSecureObj` in `bluesnap.hostedPaymentFieldsSubmitData` or you can decide not to activate 3DS and not pass the object.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"bluesnap.hostedPaymentFieldsSubmitData(function(callback) {\\n if (null != callback.cardData) {\\n console.log('Card type is ' + callback.cardData.ccType +\\n ', Last 4 digits are ' + callback.cardData.last4Digits +\\n ', Exp is ' + callback.cardData.exp + \\n ', Issuing Country is ' + callback.cardData.issuingCountry + \\n ', 3D Secure result is ' + (callback.threeDSecure != null ? callback.threeDSecure.authResult : null));\\n // submit form to server & process transaction\\n } else {\\n .\\n .\\n .\\n }\\n}, threeDSecureObj);\",\n \"language\": \"javascript\",\n \"name\": \"with threeDSecureObj\"\n },\n {\n \"code\": \"bluesnap.hostedPaymentFieldsSubmitData(function(callback) {\\n if (null != callback.cardData) {\\n console.log('Card type is ' + callback.cardData.ccType +\\n ', Last 4 digits are ' + callback.cardData.last4Digits +\\n ', Exp is ' + callback.cardData.exp + \\n ', Issuing Country is ' + callback.cardData.issuingCountry + \\n ', 3D Secure result is ' + (callback.threeDSecure != null ? callback.threeDSecure.authResult : null));\\n // submit form to server & process transaction\\n } else {\\n .\\n .\\n .\\n }\\n});\",\n \"language\": \"javascript\",\n \"name\": \"without threeDSecureObj\"\n }\n ]\n}\n[/block]\n## Step 6: Process the transaction with Hosted Payment Fields token\nProcess 3-D 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. Refer to the [Hosted Payment Fields guide](/v8976-Tools/docs/hosted-payment-fields#section-in-the-payment-api) for Payment API code samples with `pfToken`.\n\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n<hr />\n\n# 3-D Secure with Plain Text cards\nIf you're using plain text cards, implementing 3-D Secure consists of these steps:\n\n* [Step 1: Obtain the 3DS Payments token for the session](#section-step-1-obtain-the-3ds-payments-token-for-the-session)\n* [Step 2: Add the BlueSnap JavaScript file to your checkout form](#section-step-2-add-the-bluesnap-javascript-file-to-your-checkout-form)\n* [Step 3: Initialize 3DS](#section-step-3-initialize-3ds)\n* [Step 4: Activate 3DS Payments Submit Data function](#section-step-4-activate-3ds-payments-submit-data-function)\n* [Step 5: Process a transaction with the 3DS Reference ID](#section-step-5-process-a-transaction-with-the-3ds-reference-id)\n\n## Step 1: Obtain the 3DS Payments token for the session\nGet your 3DS Payments token by sending a server-to-server POST request.\n\n* For a card that is new on your website: \n`BLUESNAPDOMAINPATH/services/2/payment-fields-tokens`\n\n* For a saved card: \n`BLUESNAPDOMAINPATH/services/2/payment-fields-tokens/prefill`\n`{ \"ccNumber\":\"4111 1111 1111 1111\", \"expDate\" : \"01/2022\" }`\n\n[block:callout]\n{\n \"type\": \"info\",\n \"title\": \"Insert the domain for either Sandbox or Production\",\n \"body\": \"In all steps, replace the BLUESNAPDOMAINPATH with the relevant domain for either the BlueSnap Sandbox or Production environment, as follows:\\n* Sandbox: `https://sandbox.bluesnap.com`\\n* Production: `https://ws.bluesnap.com`\\n\\nFor example, the Hosted Fields token request (step 1) should be sent to `https://sandbox.bluesnap.com/services/2/payment-fields-tokens` on Sandbox and `https://ws.bluesnap.com/services/2/payment-fields-tokens` on Production.\"\n}\n[/block]\nThe response provides the token in the location header. For example:\n`BLUESNAPDOMAINPATH/services/2/payment-fields-tokens/PAYMENTFIELDTOKENID` \n\n**Note:** Secured Payments Token expires after 60 minutes.\n\n## Step 2: Add the BlueSnap JavaScript file to your checkout form\nIn your checkout page, call the BlueSnap JavaScript file by adding the following script:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"<script type=\\\"text/javascript\\\" src=\\\"BLUESNAPDOMAINPATH/web-sdk/4/bluesnap.js\\\"></script>\",\n \"language\": \"javascript\"\n }\n ]\n}\n[/block]\n## Step 3: Initialize 3DS \nTo initialize 3-D Secure, call `bluesnap.threeDsPaymentsSetup` with the following parameters: \n\n* The token from step 1\n* A callback function to handle the data submission results (this occurs in step 4)\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"<script>\\n //Run the following command after Document Object Model (DOM) is fully loaded\\n // and bluesnap script was loaded \\n bluesnap.threeDsPaymentsSetup(\\\"PAYMENTFIELDTOKENID\\\", function(sdkResponse){\\n \\tvar code = sdkResponse.code;\\n \\tif (code == 1){ // on Success\\n\\t var cardData = sdkResponse.cardData;\\n\\t var threeDSecure = sdkResponse.threeDSecure;\\n console.log('card type: ' + cardData.ccType\\n + ', last4digits: '\\n + cardData.last4Digits\\n + ', issuing Country: '\\n + cardData.issuingCountry\\n + ', is Regulated Card: '\\n + cardData.isRegulatedCard\\n + ', card Sub Type: '\\n + cardData.cardSubType\\n + ', bin Category: '\\n + cardData.binCategory\\n + ', cc bin: '\\n + cardData.ccBin\\n + ', 3D Secure result: '\\n + threeDSecure.authResult\\n + ', 3D Secure ReferenceId: '\\n + threeDSecure.threeDSecureReferenceId\\n + ', after that I can call final submit');\\n // SUBMIT THE FORM HERE!\\n } else {\\n // in case some errors occurred \\n var errorsArray = sdkResponse.info.errors;\\n // in case some warnings occurred\\n var warningsArray = sdkResponse.info.warnings;\\n }\\n });\\n</script>\\n\",\n \"language\": \"javascript\"\n }\n ]\n}\n[/block]\n \nReplace `PAYMENTFIELDTOKENID` with the token you obtained in Step 1.\n\nThe `SdkResponse` object contains:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"status\\\": STATUS,\\n \\\"code\\\": ERROR_CODE,\\n \\\"info\\\": { // if an error or warning occurred\\n \\\"errors\\\": [\\\"Some errors\\\"],\\n \\\"warnings\\\": ['Some warning']\\n },\\n \\\"cardData\\\": {\\n \\\"binCategory\\\": \\\"CONSUMER\\\",\\n \\\"ccBin\\\": \\\"411111\\\",\\n \\\"cardSubType\\\": \\\"CREDIT\\\",\\n \\\"ccType\\\": \\\"VISA\\\",\\n \\\"last4Digits\\\": \\\"0002\\\",\\n \\\"isRegulatedCard\\\": \\\"Y\\\",\\n \\\"issuingCountry\\\": \\\"us\\\"\\n },\\n \\\"threeDSecure\\\": {\\n \\\"authResult\\\": “AUTHENTICATION_SUCCEEDED”,\\n \\\"threeDSecureReferenceId\\\": \\\"12345\\\"\\n }\\n}\\n\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n \nThe `\"status\"` can have the following values: \n* `Success`\n* `Invalid Data` — Identifies issues with the jsonData provided from the merchant.\n* `Inner Error` — Identifies issues in the solution itself.\n* `Server Error` — Identifies issues with the BlueSnap server.\n<br />\n\nThe `\"code\"` field can have the following error codes:\n* `1` — On a status of `Success`\n* `10` — On a status of `Invalid Data` when an error prevents the process from continuing. For example: Invalid provided currency.\n* `15` — On a status of `Invalid Data` when an error does not prevent the process from continuing. (The callback is called with a warning array. The process continues and callback is called again on completion or another error). For example: Invalid billingFirstName.\n* Other codes are the BlueSnap server HTTP errors or generic server errors (400, 500). For example:\n * `22013` is `CC_TYPE_IS_NOT_SUPPORTED_BY_THE_MERCHANT`\n * `14040` is `TOKEN_IS_EXPIRED`\n * `14042` is `TOKEN_IS_NOT_ASSOCIATED_WITH_A_PAYMENT_METHOD`\n * `14104` is `SHOPPER_CC_NOT_FOUND`\n * `14102/10` is `THREE_D_SECURE_MISSING_REQUIRED_FIELDS`\n<br />\n\nThe `\"info\"` field is present if an error or warning occurred and will contain the `errors` and `warnings`. \n* The following are possible values for `errors`:\n * `Invalid amount: <given_amount>` — An invalid amount was given\n * `Amount is mandatory and must be of type number` — An amount wasn’t provided or provided not as a number\n * `Currency <given_currency> is not supported` — The given currency is not supported\n * `Currency is mandatory` — An amount wasn’t provided\n * `Invalid ccNumber` \n * `Invalid cvv`\n * `Invalid expDate`\n * `Invalid ccType`\n * `Invalid last4Digits`\n* The following is a possible value for `warnings`:\n * `Parameter <given_key> with value of <given_value> is invalid` — Keys verified through this process are: email, all shipping details, and all of the billing details.\nFor example: `Parameter shippingFirstName with value of 123 is invalid`\n\n\n## Step 4: Activate 3DS Payments Submit Data function\nTo activate 3DS Payments Submit Data function when the user presses the submit button and then wait for response before activating the submit form, add the script below into your checkout form:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"<script>\\n\\tvar newCard = {\\n\\t\\t\\\"ccNumber\\\":\\\"CREDIT CARD NUMBER\\\",\\n\\t\\t\\\"cvv\\\":\\\"CVV\\\", //Optional\\n\\t\\t\\\"expDate\\\":\\\"MM/YYYY\\\",\\n\\t\\t\\\"amount\\\": 10,\\n\\t\\t\\\"currency\\\": \\\"USD\\\"\\n\\t}\\n\\tbluesnap.threeDsPaymentsSubmitData(newCard);\\n</script>\\t\",\n \"language\": \"javascript\",\n \"name\": \"for a new card\"\n },\n {\n \"code\": \"<script>\\n\\tvar saveCardDirectly = {\\n\\t\\t\\\"cvv\\\":\\\"CVV\\\", //Optional\\n\\t\\t\\\"amount\\\": 10,\\n\\t\\t\\\"currency\\\": \\\"USD\\\"\\n\\t}\\n\\tbluesnap.threeDsPaymentsSubmitData(saveCardDirectly);\\n</script>\\t\",\n \"language\": \"javascript\",\n \"name\": \"for a saved card\"\n }\n ]\n}\n[/block]\nThis function should be activated when the shopper clicks the **Submit** button. This submits the credit card data to BlueSnap, where it is associated with the 3DS Payments Token. After the data submission is completed, BlueSnap calls your function from step 3 with the submission results. \n\n## Step 5: Process a transaction with the 3DS Reference ID\nProcess 3-D Secure transactions (or save shopper payment details) from your server the same way you handle regular card payments—by including the `threeDSecureReferenceId` within the `threeDSecure` property in the request. Refer to the [Auth-Capture section](https://developers.bluesnap.com/v8976-JSON/docs/auth-capture) for Payment API code samples with 3-D Secure.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Accept: application/json' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n{\\n \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\",\\n \\\"recurringTransaction\\\": \\\"ECOMMERCE\\\",\\n \\\"softDescriptor\\\": \\\"DescTest\\\",\\n \\\"amount\\\": 10,\\n \\\"currency\\\": \\\"USD\\\",\\n \\\"cardHolderInfo\\\": {\\n \\\"firstName\\\": \\\"Will\\\",\\n \\\"lastName\\\": \\\"Smith\\\"\\n },\\n \\\"creditCard\\\": {\\n \\\"cardNumber\\\": \\\"4012000033330026\\\",\\n \\\"securityCode\\\": \\\"123\\\",\\n \\\"expirationMonth\\\": \\\"07\\\",\\n \\\"expirationYear\\\":\\\"2019\\\"\\n },\\n \\\"threeDSecure\\\": {\\n \\t\\\"threeDSecureReferenceId\\\":\\\"4759\\\"\\n }\\n}'\",\n \"language\": \"curl\",\n \"name\": \"JSON Request\"\n }\n ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n<hr />\n# 3-D Secure with Returning Shoppers\nIf you're using 3-D Secure for returning shoppers, implementation consists of these steps:\n\n[Step 1: Obtain the 3DS Payments token for this session](#section-step-1-obtain-the-3ds-payments-token-for-this-session)\n[Step 2: Add the BlueSnap JavaScript file to your checkout page](#section-step-2-add-the-bluesnap-javascript-file-to-your-checkout-page)\n[Step 3: Initialize 3DS](#section-step-3-initialize-3ds)\n[Step 4: Activate 3DS Payments Submit Data function](#section-step-4-activate-the-3ds-payments-submit-data-function)\n[Step 5: Process the transaction with the 3DS Reference ID](#section-step-5-process-the-transaction-with-the-3ds-reference-id)\n\n## Step 1: Obtain the 3DS Payments token for this session\nGet your 3DS Payments token by sending a server-to-server POST request to:\n\n`BLUESNAPDOMAINPATH/services/2/payment-fields-tokens?shopperId=SHOPPERID`\n\nIf you have saved the shopper using your `sellerShopperId`, you can use that instead of `shopperId`.<br />\nThe response provides the token in the location header. For example:\n`BLUESNAPDOMAINPATH/services/2/payment-fields-tokens/PAYMENTFIELDTOKENID` \n[block:callout]\n{\n \"type\": \"info\",\n \"body\": \"In all steps, replace the BLUESNAPDOMAINPATH with the relevant domain for either the BlueSnap Sandbox or Production environment, as follows:\\n* Sandbox: `https://sandbox.bluesnap.com`\\n* Production: `https://ws.bluesnap.com`\\n\\nFor example, the Hosted Fields token request (step 1) should be sent to `https://sandbox.bluesnap.com/services/2/payment-fields-tokens` on Sandbox and `https://ws.bluesnap.com/services/2/payment-fields-tokens` on Production.\",\n \"title\": \"Insert the domain for either Sandbox or Production\"\n}\n[/block]\n**Note:** Secured Payments Token expires after 60 minutes.\n\n## Step 2: Add the BlueSnap JavaScript file to your checkout page\nIn your checkout page, call the BlueSnap JavaScript file by adding the following script:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"<script type=\\\"text/javascript\\\" src=\\\"BLUESNAPDOMAINPATH/web-sdk/4/bluesnap.js\\\"></script> \",\n \"language\": \"javascript\"\n }\n ]\n}\n[/block]\n## Step 3: Initialize 3DS \nTo initialize 3-D Secure, call `bluesnap.threeDsPaymentsSetup` with the following parameters: \n\n* The token from step 1\n* A callback function to handle the data submission results (this occurs in step 4)\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"<script>\\n //Run the following command after Document Object Model (DOM) is fully loaded\\n // and bluesnap script was loaded \\n bluesnap.threeDsPaymentsSetup(\\\"PAYMENTFIELDTOKENID\\\", function(sdkResponse){\\n \\tvar code = sdkResponse.code;\\n \\tif (code == 1){ // on Success\\n\\t var cardData = sdkResponse.cardData;\\n\\t var threeDSecure = sdkResponse.threeDSecure;\\n console.log('card type: ' + cardData.ccType\\n + ', last4digits: '\\n + cardData.last4Digits\\n + ', issuing Country: '\\n + cardData.issuingCountry\\n + ', is Regulated Card: '\\n + cardData.isRegulatedCard\\n + ', card Sub Type: '\\n + cardData.cardSubType\\n + ', bin Category: '\\n + cardData.binCategory\\n + ', cc bin: '\\n + cardData.ccBin\\n + ', 3D Secure result: '\\n + threeDSecure.authResult\\n + ', 3D Secure ReferenceId: '\\n + threeDSecure.threeDSecureReferenceId\\n + ', after that I can call final submit');\\n // SUBMIT THE FORM HERE!\\n } else {\\n // in case some errors occurred \\n var errorsArray = sdkResponse.info.errors;\\n // in case some warnings occurred\\n var warningsArray = sdkResponse.info.warnings;\\n }\\n });\\n</script>\\n\",\n \"language\": \"javascript\"\n }\n ]\n}\n[/block]\n Replace `PAYMENTFIELDTOKENID` with the token you obtained in Step 1.\n\nThe `SdkResponse` object contains:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"status\\\": STATUS,\\n \\\"code\\\": ERROR_CODE,\\n \\\"info\\\": { // if an error or warning occurred\\n \\\"errors\\\": [\\\"Some errors\\\"],\\n \\\"warnings\\\": ['Some warning']\\n },\\n \\\"cardData\\\": {\\n \\\"binCategory\\\": \\\"CONSUMER\\\",\\n \\\"ccBin\\\": \\\"411111\\\",\\n \\\"cardSubType\\\": \\\"CREDIT\\\",\\n \\\"ccType\\\": \\\"VISA\\\",\\n \\\"last4Digits\\\": \\\"0002\\\",\\n \\\"isRegulatedCard\\\": \\\"Y\\\",\\n \\\"issuingCountry\\\": \\\"us\\\"\\n },\\n \\\"threeDSecure\\\": {\\n \\\"authResult\\\": “AUTHENTICATION_SUCCEEDED”,\\n \\\"threeDSecureReferenceId\\\": \\\"12345\\\"\\n }\\n}\\n\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n \nThe `\"status\"` can have the following values: \n* `Success`\n* `Invalid Data` — Identifies issues with the jsonData provided from the merchant.\n* `Inner Error` — Identifies issues in the solution itself.\n* `Server Error` — Identifies issues with the BlueSnap server.\n\nThe `\"code\"` field can have the following error codes:\n* `1` — On a status of `Success`\n* `10` — On a status of `Invalid Data` when an error prevents the process from continuing. For example: Invalid provided currency.\n* `15` — On a status of `Invalid Data` when an error does not prevent the process from continuing. (The callback is called with a warning array. The process continues and callback is called again on completion or another error). For example: Invalid billingFirstName.\n* Other codes are the BlueSnap server HTTP errors or generic server errors (400, 500). For example:\n * `22013` is `CC_TYPE_IS_NOT_SUPPORTED_BY_THE_MERCHANT`\n * `14040` is `TOKEN_IS_EXPIRED`\n * `14042` is `TOKEN_IS_NOT_ASSOCIATED_WITH_A_PAYMENT_METHOD`\n * `14104` is `SHOPPER_CC_NOT_FOUND`\n * `14102/10` is `THREE_D_SECURE_MISSING_REQUIRED_FIELDS`\n\nThe `info` field is present if an error or warning occurred and will contain the `errors` and `warnings`.\n\n## Step 4: Activate the 3DS Payments Submit Data function\nTo activate 3DS Payments Submit Data function when the user presses the submit button and then wait for response before activating the submit form, add the script below into your checkout form:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"<script>\\n\\tvar previouslyUsedCard = {\\n\\t\\t\\\"last4Digits\\\": \\\"1111\\\",\\n\\t\\t\\\"ccType\\\": \\\"VISA\\\",\\n\\t\\t\\\"amount\\\": 10,\\n\\t\\t\\\"currency\\\": \\\"USD\\\"\\n\\t}\\n bluesnap.threeDsPaymentsSubmitData(previouslyUsedCard);\\n</script>\\t\",\n \"language\": \"javascript\"\n }\n ]\n}\n[/block]\nThis function should be activated when the shopper clicks the **Submit** button. This submits the credit card data to BlueSnap, where it is associated with the 3DS Payments Token. After the data submission is completed, BlueSnap calls your function from step 3 with the submission results. \n\n## Step 5: Process the transaction with the 3DS Reference ID\nProcess 3-D Secure transactions (or save shopper payment details) from your server the same way you handle regular card payments—by including the `threeDSecureReferenceId` within the `threeDSecure` property in the request. Refer to the [Auth-Capture section](https://developers.bluesnap.com/v8976-JSON/docs/auth-capture) for Payment API code samples with 3-D Secure.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Accept: application/json' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n{\\n\\t\\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\",\\n\\t\\\"softDescriptor\\\": \\\"DescTest\\\",\\n\\t\\\"amount\\\": 10,\\n\\t\\\"currency\\\": \\\"USD\\\",\\n\\t\\\"vaultedShopperId\\\":\\\"19574268\\\",\\n\\t\\\"creditCard\\\": {\\n\\t\\t\\\"cardLastFourDigits\\\": \\\"1111\\\",\\n\\t\\t\\\"cardType\\\": \\\"VISA\\\"\\n\\t\\t},\\n\\t\\\"threeDSecure\\\": {\\n\\t\\t\\\"threeDSecureReferenceId\\\":\\\"5303\\\"\\n\\t}\\n}'\",\n \"language\": \"curl\",\n \"name\": \"JSON Request\"\n }\n ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n<hr />\n\n#3-D Secure in Payment Request API (W3C)\nTo add 3-D Secure to Payment Request API (W3C), add `\"threeDS\": \"true\"` in the `sdkRequest` object. For more information, refer [here](https://developers.bluesnap.com/v8976-Basics/docs/payment-request-api). \n\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n<hr />\n\n#3-D Secure in Secured Payment Collector\nTo add 3-D Secure to the [Secured Payment Collector](/v8976-Tools/docs/secured-payment-collector), pass `true` to `bluesnap.securedPaymentCollectorSetup` ([Step 4](/v8976-Tools/docs/secured-payment-collector#section-4-initialize-the-secured-payment-collector) of the implementation process).\n\nTo process the transaction with 3-D Secure, send the value from `sdkResponse.threeDSecure.authResult` ([Step 4](/v8976-Tools/docs/secured-payment-collector#section-4-initialize-the-secured-payment-collector) of the implementation process) to your server. Include this value and your token in your API request to BlueSnap. For example: \n[block:code]\n{\n \"codes\": [\n {\n \"code\": \" curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \\\\\\n -H 'Content-Type: application/json' \\\\\\n -H 'Accept: application/json' \\\\ \\n -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n -d '\\n{\\n \\\"cardTransactionType\\\": \\\"AUTH_CAPTURE\\\",\\n \\\"amount\\\": 25.0,\\n \\\"currency\\\": \\\"USD\\\",\\n \\\"pfToken\\\": \\\"PAYMENT_TOKEN\\\",\\n \\\"threeDSecure\\\": {\\n \\\"threeDSecureReferenceId\\\": \\\"1234\\\"\\n }\\n}'\",\n \"language\": \"curl\",\n \"name\": \"Auth Capture - Request\"\n }\n ]\n}\n[/block]\nTo process the transaction without 3-D Secure, omit the `threeDSecure` object from the request. For details, see [Completing Tokenized Payments](doc:completing-tokenized-payments). \n\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n<hr />\n\n# Processing payments with data from external Merchant Plug-In (MPI)\nIf you're using an external Merchant Plug-In (MPI) for 3-D 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[block:callout]\n{\n \"type\": \"info\",\n \"body\": \"If you’re using an external merchant plugin you don’t need to set the flag in BlueSnap.\\n\\nAsk your implementation manager to provide the appropriate MIDs and BINs.\",\n \"title\": \"Note\"\n}\n[/block]\nTo process the payment, include the [`threeDSecure` object](https://developers.bluesnap.com/v8976-JSON/docs/threedsecure). \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\\\": 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 \\\"dsTransactionId\\\" : \\\"e08da266-b58d-45c9-a1f8-570b7fb80e30\\\",\\n \\\"threeDSecureVersion\\\" : \\\"2.1.0\\\"\\n }\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n<br />\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n<hr />\n\n#Supported 3-D Secure object properties\n`amount` *number* <span style=\"color:#F37500\">**required**</span>\n`currency` *string* <span style=\"color:#F37500\">**required**</span>\n`billingFirstName` *string* optional\n`billingLastName` *string* optional\n`billingCountry` *string* optional Value must be a two-letter country code (ISO 3166-1 alpha-2). Find a complete list of country codes [here](https://developers.bluesnap.com/docs/country-codes).\n`billingState` *string* \n optional Value must be the state/province portion of the ISO 3166-2 code, in all uppercase characters. For example, for **US-OH**, send **OH**, or for **GB-LND**, send **LND**. If you are uncertain of the format, it is recommended to not pass a value. \n`billingCity` *string* optional\n`billingAddress` *string* optional\n`billingZip` *string* optional\n`shippingFirstName` *string* optional\n`shippingLastName` *string* optional\n`shippingCountry` *string* optional\n optional Value must be a two-letter country code (ISO 3166-1 alpha-2). Find a complete list of country codes [here](https://developers.bluesnap.com/docs/country-codes).\n`shippingState` *string* optional\n optional Value must be the state/province portion of the ISO 3166-2 code, in all uppercase characters. For example, for **US-OH**, send **OH**, or for **GB-LND**, send **LND**. If you are uncertain of the format, it is recommended to not pass a value. \n`shippingCity` *string* optional\n`shippingAddress` *string* optional\n`shippingZip` *string* optional\n`email` *string* optional\n`phone` *string* optional\n\n\n<br />\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n<hr />\n\n#Error codes\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Error Code\",\n \"h-1\": \"Description\",\n \"0-0\": \"`14100`\",\n \"0-1\": \"**Problem**: 3-D Secure is not enabled\\n\\n**Resolution**: Enable 3-D Secure\",\n \"1-0\": \"`14101`\",\n \"2-0\": \"`14102/10`\",\n \"3-0\": \"`14103`\",\n \"1-1\": \"**Problem**: 3-D Secure authentication failed \\n\\n**Resolution**: Inform the shopper to try a different payment method\",\n \"2-1\": \"**Problem**: 3-D Secure object is missing required fields { ... }\\n\\n**Resolution**: Make sure 3-D Secure object has both transaction amount and currency\",\n \"3-1\": \"**Problem**: 3-D Secure client error\\n\\n**Resolution**: Continue without 3DS\"\n },\n \"cols\": 2,\n \"rows\": 4\n}\n[/block]\n<br />\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n<hr />\n\n# Authentication results\n###`AUTHENTICATION_BYPASSED`###\n* **Meaning**: 3-D Secure authentication was bypassed due to the merchant's configuration or the shopper’s credit card issuing bank configuration.\n* **To Proceed**: Process the transaction without 3-D Secure\n * [in Hosted Payment Fields](#section-step-6-process-the-transaction-with-hosted-payment-fields-token)\n * [in the Secured Payment Collector](/docs/completing-tokenized-payments)\n\n###`AUTHENTICATION_SUCCEEDED`###\n* **Meaning**: 3-D 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 3-D Secure [chargeback liability shift](https://support.bluesnap.com/docs/3d-secure#chargeback-liability-shift). \n* **To Proceed**: \n * In Hosted Payment Fields: [Process the 3-D Secure transaction](#section-step-6-process-the-transaction-with-hosted-payment-fields-token)\n * In the Secured Payment Collector: [Process the 3-D Secure transaction](#section-3-d-secure-in-secured-payment-collector)\n\n###`AUTHENTICATION_UNAVAILABLE`###\n* **Meaning**: 3-D Secure is unavailable for this card or a technical error occurred.\n* **To Proceed**: Process the transaction without 3-D Secure\n * [in Hosted Payment Fields](#section-step-6-process-the-transaction-with-hosted-payment-fields-token)\n * [in the Secured Payment Collector](/docs/completing-tokenized-payments)\n\n###`AUTHENTICATION_FAILED`###\n* **Meaning**: The card on the transaction could not be authenticated..\n* **To Proceed**: If the option **Process failed 3DS transactions** is enabled in **Settings > Fraud Settings** in the Merchant Portal, then the transaction can be processed.\n[block:callout]\n{\n \"type\": \"info\",\n \"title\": \"Note\",\n \"body\": \"The authentication result above is included in the Order Locator information for any order processed using 3-D Secure.\"\n}\n[/block]\n<br />\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n<hr />\n# Testing 3-D Secure \nFor information about Sandbox testing of 3-D Secure, refer [here](https://support.bluesnap.com/docs/3d-secure#section-sandbox-testing-of-3-d-secure).\n\n# Subscribing to Events\nBlueSnap uses an event-based system that helps you get insight into what’s happening in real-time. It allows you to subscribe to different events that are triggered internally by BlueSnap. You only have to subscribe to an event once per page load. After that, you won't need to re-subscribe. \n\nKeep in mind you should subscribe to events before you call the `bluesnap.threeDsPaymentsSetup` function. The code snippets below are currently only applicable to 3DS [with plain text cards](https://developers.bluesnap.com/docs/3-d-secure-for-api#section-3-d-secure-with-plain-text-cards) and [with returning shoppers](https://developers.bluesnap.com/docs/3-d-secure-for-api#section-3-d-secure-with-returning-shoppers).\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"bluesnap.on('setupComplete', () => {\\n\\n// setupComplete\\n\\n});\\n\\nbluesnap.on('threeDsChallengeExecuted', () => {\\n\\n// threeDsChallengeExecuted\\n\\n});\",\n \"language\": \"javascript\",\n \"name\": \"to subscribe to events\"\n }\n ]\n}\n[/block]","updates":[],"order":0,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"622623052699060013831dd8","project":"57336fd5a6a9c40e00e13a0b","version":{"version":"8976-Basics","version_clean":"8976.0.0-Basics","codename":"3.41 Release","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["622623052699060013831d9c","622623052699060013831d9d","622623052699060013831d9e","6183ed028202aa001610248b","622623052699060013831d9f","622623052699060013831da0","5beb278ac442ab0213f00990","622623052699060013831da1","5c3f542c12c4ac004bc51718","6183ed028202aa001610248f","5df806ccecebde0059f17225","5dfa8a8f340c2b007418eb8a","622623052699060013831da2","5e597199fd2b0200117c2c1c"],"_id":"622623052699060013831de5","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"6183ed028202aa00161024e9","createdAt":"2018-04-23T14:36:48.535Z","releaseDate":"2018-04-23T14:36:48.535Z"},"category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Guides","slug":"topics","order":7,"from_sync":false,"reference":false,"_id":"622623052699060013831da1","version":"622623052699060013831de5","project":"57336fd5a6a9c40e00e13a0b","createdAt":"2015-11-03T20:45:01.593Z","__v":0},"user":"5beb1b96bc2003003ecd645e","createdAt":"2019-10-15T18:25:11.120Z","__v":0,"parentDoc":null}
3-D Secure for API
This guide provides information for using 3-D Secure 2 with the BlueSnap API.
- For general information about 3-D Secure and 3-D Secure 2, refer to the 3-D Secure Guide.
- For answers to specific questions related to BlueSnap and 3-D Secure 2, PSD2, and SCA, refer to our 3-D Secure 2 FAQs page.
- If you're using Client-Side Encryption, please follow the instructions here to implement 3-D Secure.
This guide provides the following information:
- 3-D Secure in Hosted Payment Fields
- 3-D Secure with Plain Text cards
- 3-D Secure with Returning Shoppers
- 3-D Secure in Payment Request API (W3C)
- 3-D Secure in Secured Payment Collector
- Processing payments with data from external Merchant Plug-In (MPI)
- Supported 3-D Secure object properties
- Error codes
- Authentication results
Note
You don't have to apply 3-D Secure to all transactions. If you want to apply 3DS only to EU-issued cards for PSD2, but not US-issued cards, you can do that. Refer to Step 5 for examples.
Important
Since 3-D Secure uses URLs that vary based on the credit card issuer, the Content-Security-Policy (CSP) should be as permissive as possible and leverage the ‘*’ (wildcard) token. Any other CSP will likely result in a failure.
Merchant-initiated transactions are out of scope for 3-D Secure, provided they follow a 3-D Secure Customer Initiated Transaction (learn more). To make sure your transaction is identified as merchant-initiated, you must use the Merchant Managed Subscription API. Refer to Create Merchant-Managed Subscription and Create Merchant-Managed Subscription Charge for details.
BlueSnap applies this out-of-scope exemption to applicable transactions only for merchants who are using the BlueSnap Subscription Engine or our Merchant Managed Subscription feature. If you handle your own subscriptions (that is, you are sending straight auth‑capture requests not using the BlueSnap Subscription Engine or our merchant-managed subscription feature), follow the information in the Rules for MITs for more information.
Before you begin
If applicable, make sure you've implemented the latest version of Hosted Payment Fields.
Enable 3-D Secure
To get started, contact Merchant Support to request that BlueSnap enable 3DS for your account. After it has been enabled, you can activate it in your Merchant Portal by going to Settings > Fraud Settings and selecting Enable 3D Secure.Enable IPNs for your account. When the shopper's account is debited for the transaction, the Charge IPN is sent with the
3DStatus
parameter, which verifies the 3-D Secure result.
3-D Secure in Hosted Payment Fields
If you're using Hosted Payment Fields, implementing 3DS consists of these steps:
- Step 1: Prevent your shopper from submitting the form during 3-D Secure setup
- Step 2: Enable 3-D Secure usage in the transaction
- Step 3: Account for 3-D Secure errors
- Step 4: Create 3-D Secure object with transaction data
- Step 5: Determine 3-D Secure result
- Step 6: Process the transaction with Hosted Payment Fields token
Step 1: Prevent your shopper from submitting the form during 3-D Secure setup
If the shopper submits the payment form while BlueSnap is setting up 3DS, an error may occur. You must let BlueSnap deactivate the submit button while setting up 3DS. To do this, add the data-bluesnap
attribute to your submit button element and set the value to submitButton
, as shown here
<button data-bluesnap="submitButton" type="submit" id="submit-button">Pay Now</button>
Important!
You must define the data-bluesnap
value exactly as shown above; otherwise, BlueSnap cannot properly deactivate the button.
var bsObj = {
'3DS': true
};
Step 3: Account for 3-D Secure errors
BlueSnap passes 3DS error codes and descriptions (shown here) to your onError
callback function as the errorCode
and errorDescription
parameters. Update your onError
callback function to account for these errors.
Step 4: Create 3-D Secure object with transaction data
Create a 3DS object with at least the transaction amount and currency, as shown in the code below.
If you want to submit the credentials and activate 3DS, pass your object as an additional parameter to bluesnap.hostedPaymentFieldsSubmitData
(shown in Step 5). You can also decide not to activate 3DS and not pass the object.
When the shopper hits the submit button, the data you provide within your object is sent to the issuer during the lookup and they 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 3DS 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 (refer to Supported 3-D Secure object properties).
var threeDSecureObj = {
amount: 35.75,
currency: 'USD'
};
Step 5: Determine 3-D Secure result
BlueSnap passes the 3DS result to your purchase function callback as callBack.threeDSecure.authResult
, which has one of the values shown here. Configure your purchase function callback to determine the 3DS result and take appropriate action. (Refer to the code below for a simple bluesnap.hostedPaymentFieldsSubmitData
call with the changes from Steps 4 and 5.)
Note
callBack.threeDSecure
also includes threeDSecureReferenceId
, a reference to the 3DS authentication.
The code calls bluesnap.hostedPaymentFieldsSubmitData
with a simple purchase callback function. Here you can decide if you want to activate 3DS by either including the threeDSecureObj
in bluesnap.hostedPaymentFieldsSubmitData
or you can decide not to activate 3DS and not pass the object.
bluesnap.hostedPaymentFieldsSubmitData(function(callback) {
if (null != callback.cardData) {
console.log('Card type is ' + callback.cardData.ccType +
', Last 4 digits are ' + callback.cardData.last4Digits +
', Exp is ' + callback.cardData.exp +
', Issuing Country is ' + callback.cardData.issuingCountry +
', 3D Secure result is ' + (callback.threeDSecure != null ? callback.threeDSecure.authResult : null));
// submit form to server & process transaction
} else {
.
.
.
}
}, threeDSecureObj);
bluesnap.hostedPaymentFieldsSubmitData(function(callback) {
if (null != callback.cardData) {
console.log('Card type is ' + callback.cardData.ccType +
', Last 4 digits are ' + callback.cardData.last4Digits +
', Exp is ' + callback.cardData.exp +
', Issuing Country is ' + callback.cardData.issuingCountry +
', 3D Secure result is ' + (callback.threeDSecure != null ? callback.threeDSecure.authResult : null));
// submit form to server & process transaction
} else {
.
.
.
}
});
Step 6: Process the transaction with Hosted Payment Fields token
Process 3-D 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. Refer to the Hosted Payment Fields guide for Payment API code samples with pfToken
.
3-D Secure with Plain Text cards
If you're using plain text cards, implementing 3-D Secure consists of these steps:
- Step 1: Obtain the 3DS Payments token for the session
- Step 2: Add the BlueSnap JavaScript file to your checkout form
- Step 3: Initialize 3DS
- Step 4: Activate 3DS Payments Submit Data function
- Step 5: Process a transaction with the 3DS Reference ID
Step 1: Obtain the 3DS Payments token for the session
Get your 3DS Payments token by sending a server-to-server POST request.
For a card that is new on your website:
BLUESNAPDOMAINPATH/services/2/payment-fields-tokens
For a saved card:
BLUESNAPDOMAINPATH/services/2/payment-fields-tokens/prefill
{ "ccNumber":"4111 1111 1111 1111", "expDate" : "01/2022" }
Insert the domain for either Sandbox or Production
In all steps, replace the BLUESNAPDOMAINPATH with the relevant domain for either the BlueSnap Sandbox or Production environment, as follows:
- Sandbox:
https://sandbox.bluesnap.com
- Production:
https://ws.bluesnap.com
For example, the Hosted Fields token request (step 1) should be sent to https://sandbox.bluesnap.com/services/2/payment-fields-tokens
on Sandbox and https://ws.bluesnap.com/services/2/payment-fields-tokens
on Production.
The response provides the token in the location header. For example:BLUESNAPDOMAINPATH/services/2/payment-fields-tokens/PAYMENTFIELDTOKENID
Note: Secured Payments Token expires after 60 minutes.
Step 2: Add the BlueSnap JavaScript file to your checkout form
In your checkout page, call the BlueSnap JavaScript file by adding the following script:
<script type="text/javascript" src="BLUESNAPDOMAINPATH/web-sdk/4/bluesnap.js"></script>
<script>
//Run the following command after Document Object Model (DOM) is fully loaded
// and bluesnap script was loaded
bluesnap.threeDsPaymentsSetup("PAYMENTFIELDTOKENID", function(sdkResponse){
var code = sdkResponse.code;
if (code == 1){ // on Success
var cardData = sdkResponse.cardData;
var threeDSecure = sdkResponse.threeDSecure;
console.log('card type: ' + cardData.ccType
+ ', last4digits: '
+ cardData.last4Digits
+ ', issuing Country: '
+ cardData.issuingCountry
+ ', is Regulated Card: '
+ cardData.isRegulatedCard
+ ', card Sub Type: '
+ cardData.cardSubType
+ ', bin Category: '
+ cardData.binCategory
+ ', cc bin: '
+ cardData.ccBin
+ ', 3D Secure result: '
+ threeDSecure.authResult
+ ', 3D Secure ReferenceId: '
+ threeDSecure.threeDSecureReferenceId
+ ', after that I can call final submit');
// SUBMIT THE FORM HERE!
} else {
// in case some errors occurred
var errorsArray = sdkResponse.info.errors;
// in case some warnings occurred
var warningsArray = sdkResponse.info.warnings;
}
});
</script>
Replace PAYMENTFIELDTOKENID
with the token you obtained in Step 1.
The SdkResponse
object contains:
{
"status": STATUS,
"code": ERROR_CODE,
"info": { // if an error or warning occurred
"errors": ["Some errors"],
"warnings": ['Some warning']
},
"cardData": {
"binCategory": "CONSUMER",
"ccBin": "411111",
"cardSubType": "CREDIT",
"ccType": "VISA",
"last4Digits": "0002",
"isRegulatedCard": "Y",
"issuingCountry": "us"
},
"threeDSecure": {
"authResult": “AUTHENTICATION_SUCCEEDED”,
"threeDSecureReferenceId": "12345"
}
}
The "status"
can have the following values:
Success
Invalid Data
— Identifies issues with the jsonData provided from the merchant.Inner Error
— Identifies issues in the solution itself.Server Error
— Identifies issues with the BlueSnap server.
The "code"
field can have the following error codes:
1
— On a status ofSuccess
10
— On a status ofInvalid Data
when an error prevents the process from continuing. For example: Invalid provided currency.15
— On a status ofInvalid Data
when an error does not prevent the process from continuing. (The callback is called with a warning array. The process continues and callback is called again on completion or another error). For example: Invalid billingFirstName.- Other codes are the BlueSnap server HTTP errors or generic server errors (400, 500). For example:
22013
isCC_TYPE_IS_NOT_SUPPORTED_BY_THE_MERCHANT
14040
isTOKEN_IS_EXPIRED
14042
isTOKEN_IS_NOT_ASSOCIATED_WITH_A_PAYMENT_METHOD
14104
isSHOPPER_CC_NOT_FOUND
14102/10
isTHREE_D_SECURE_MISSING_REQUIRED_FIELDS
The "info"
field is present if an error or warning occurred and will contain the errors
and warnings
.
- The following are possible values for
errors
:Invalid amount: <given_amount>
— An invalid amount was givenAmount is mandatory and must be of type number
— An amount wasn’t provided or provided not as a numberCurrency <given_currency> is not supported
— The given currency is not supportedCurrency is mandatory
— An amount wasn’t providedInvalid ccNumber
Invalid cvv
Invalid expDate
Invalid ccType
Invalid last4Digits
- The following is a possible value for
warnings
:Parameter <given_key> with value of <given_value> is invalid
— Keys verified through this process are: email, all shipping details, and all of the billing details.
For example:Parameter shippingFirstName with value of 123 is invalid
Step 4: Activate 3DS Payments Submit Data function
To activate 3DS Payments Submit Data function when the user presses the submit button and then wait for response before activating the submit form, add the script below into your checkout form:
<script>
var newCard = {
"ccNumber":"CREDIT CARD NUMBER",
"cvv":"CVV", //Optional
"expDate":"MM/YYYY",
"amount": 10,
"currency": "USD"
}
bluesnap.threeDsPaymentsSubmitData(newCard);
</script>
<script>
var saveCardDirectly = {
"cvv":"CVV", //Optional
"amount": 10,
"currency": "USD"
}
bluesnap.threeDsPaymentsSubmitData(saveCardDirectly);
</script>
This function should be activated when the shopper clicks the Submit button. This submits the credit card data to BlueSnap, where it is associated with the 3DS Payments Token. After the data submission is completed, BlueSnap calls your function from step 3 with the submission results.
Step 5: Process a transaction with the 3DS Reference ID
Process 3-D Secure transactions (or save shopper payment details) from your server the same way you handle regular card payments—by including the threeDSecureReferenceId
within the threeDSecure
property in the request. Refer to the Auth-Capture section for Payment API code samples with 3-D Secure.
curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"cardTransactionType": "AUTH_CAPTURE",
"recurringTransaction": "ECOMMERCE",
"softDescriptor": "DescTest",
"amount": 10,
"currency": "USD",
"cardHolderInfo": {
"firstName": "Will",
"lastName": "Smith"
},
"creditCard": {
"cardNumber": "4012000033330026",
"securityCode": "123",
"expirationMonth": "07",
"expirationYear":"2019"
},
"threeDSecure": {
"threeDSecureReferenceId":"4759"
}
}'
3-D Secure with Returning Shoppers
If you're using 3-D Secure for returning shoppers, implementation consists of these steps:
Step 1: Obtain the 3DS Payments token for this session
Step 2: Add the BlueSnap JavaScript file to your checkout page
Step 3: Initialize 3DS
Step 4: Activate 3DS Payments Submit Data function
Step 5: Process the transaction with the 3DS Reference ID
Step 1: Obtain the 3DS Payments token for this session
Get your 3DS Payments token by sending a server-to-server POST request to:
BLUESNAPDOMAINPATH/services/2/payment-fields-tokens?shopperId=SHOPPERID
If you have saved the shopper using your sellerShopperId
, you can use that instead of shopperId
.
The response provides the token in the location header. For example:BLUESNAPDOMAINPATH/services/2/payment-fields-tokens/PAYMENTFIELDTOKENID
Insert the domain for either Sandbox or Production
In all steps, replace the BLUESNAPDOMAINPATH with the relevant domain for either the BlueSnap Sandbox or Production environment, as follows:
- Sandbox:
https://sandbox.bluesnap.com
- Production:
https://ws.bluesnap.com
For example, the Hosted Fields token request (step 1) should be sent to https://sandbox.bluesnap.com/services/2/payment-fields-tokens
on Sandbox and https://ws.bluesnap.com/services/2/payment-fields-tokens
on Production.
<script type="text/javascript" src="BLUESNAPDOMAINPATH/web-sdk/4/bluesnap.js"></script>
<script>
//Run the following command after Document Object Model (DOM) is fully loaded
// and bluesnap script was loaded
bluesnap.threeDsPaymentsSetup("PAYMENTFIELDTOKENID", function(sdkResponse){
var code = sdkResponse.code;
if (code == 1){ // on Success
var cardData = sdkResponse.cardData;
var threeDSecure = sdkResponse.threeDSecure;
console.log('card type: ' + cardData.ccType
+ ', last4digits: '
+ cardData.last4Digits
+ ', issuing Country: '
+ cardData.issuingCountry
+ ', is Regulated Card: '
+ cardData.isRegulatedCard
+ ', card Sub Type: '
+ cardData.cardSubType
+ ', bin Category: '
+ cardData.binCategory
+ ', cc bin: '
+ cardData.ccBin
+ ', 3D Secure result: '
+ threeDSecure.authResult
+ ', 3D Secure ReferenceId: '
+ threeDSecure.threeDSecureReferenceId
+ ', after that I can call final submit');
// SUBMIT THE FORM HERE!
} else {
// in case some errors occurred
var errorsArray = sdkResponse.info.errors;
// in case some warnings occurred
var warningsArray = sdkResponse.info.warnings;
}
});
</script>
Replace PAYMENTFIELDTOKENID
with the token you obtained in Step 1.
The SdkResponse
object contains:
{
"status": STATUS,
"code": ERROR_CODE,
"info": { // if an error or warning occurred
"errors": ["Some errors"],
"warnings": ['Some warning']
},
"cardData": {
"binCategory": "CONSUMER",
"ccBin": "411111",
"cardSubType": "CREDIT",
"ccType": "VISA",
"last4Digits": "0002",
"isRegulatedCard": "Y",
"issuingCountry": "us"
},
"threeDSecure": {
"authResult": “AUTHENTICATION_SUCCEEDED”,
"threeDSecureReferenceId": "12345"
}
}
The "status"
can have the following values:
Success
Invalid Data
— Identifies issues with the jsonData provided from the merchant.Inner Error
— Identifies issues in the solution itself.Server Error
— Identifies issues with the BlueSnap server.
The "code"
field can have the following error codes:
1
— On a status ofSuccess
10
— On a status ofInvalid Data
when an error prevents the process from continuing. For example: Invalid provided currency.15
— On a status ofInvalid Data
when an error does not prevent the process from continuing. (The callback is called with a warning array. The process continues and callback is called again on completion or another error). For example: Invalid billingFirstName.- Other codes are the BlueSnap server HTTP errors or generic server errors (400, 500). For example:
22013
isCC_TYPE_IS_NOT_SUPPORTED_BY_THE_MERCHANT
14040
isTOKEN_IS_EXPIRED
14042
isTOKEN_IS_NOT_ASSOCIATED_WITH_A_PAYMENT_METHOD
14104
isSHOPPER_CC_NOT_FOUND
14102/10
isTHREE_D_SECURE_MISSING_REQUIRED_FIELDS
The info
field is present if an error or warning occurred and will contain the errors
and warnings
.
Step 4: Activate the 3DS Payments Submit Data function
To activate 3DS Payments Submit Data function when the user presses the submit button and then wait for response before activating the submit form, add the script below into your checkout form:
<script>
var previouslyUsedCard = {
"last4Digits": "1111",
"ccType": "VISA",
"amount": 10,
"currency": "USD"
}
bluesnap.threeDsPaymentsSubmitData(previouslyUsedCard);
</script>
This function should be activated when the shopper clicks the Submit button. This submits the credit card data to BlueSnap, where it is associated with the 3DS Payments Token. After the data submission is completed, BlueSnap calls your function from step 3 with the submission results.
Step 5: Process the transaction with the 3DS Reference ID
Process 3-D Secure transactions (or save shopper payment details) from your server the same way you handle regular card payments—by including the threeDSecureReferenceId
within the threeDSecure
property in the request. Refer to the Auth-Capture section for Payment API code samples with 3-D Secure.
curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"cardTransactionType": "AUTH_CAPTURE",
"softDescriptor": "DescTest",
"amount": 10,
"currency": "USD",
"vaultedShopperId":"19574268",
"creditCard": {
"cardLastFourDigits": "1111",
"cardType": "VISA"
},
"threeDSecure": {
"threeDSecureReferenceId":"5303"
}
}'
3-D Secure in Payment Request API (W3C)
To add 3-D Secure to Payment Request API (W3C), add "threeDS": "true"
in the sdkRequest
object. For more information, refer here.
3-D Secure in Secured Payment Collector
To add 3-D Secure to the Secured Payment Collector, pass true
to bluesnap.securedPaymentCollectorSetup
(Step 4 of the implementation process).
To process the transaction with 3-D Secure, send the value from sdkResponse.threeDSecure.authResult
(Step 4 of the implementation process) to your server. Include this value and your token in your API request to BlueSnap. For example:
curl -v -X POST https://sandbox.bluesnap.com/services/2/transactions \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"cardTransactionType": "AUTH_CAPTURE",
"amount": 25.0,
"currency": "USD",
"pfToken": "PAYMENT_TOKEN",
"threeDSecure": {
"threeDSecureReferenceId": "1234"
}
}'
To process the transaction without 3-D Secure, omit the threeDSecure
object from the request. For details, see Completing Tokenized Payments.
Processing payments with data from external Merchant Plug-In (MPI)
If you're using an external Merchant Plug-In (MPI) for 3-D 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.
Note
If you’re using an external merchant plugin you don’t need to set the flag in BlueSnap.
Ask your implementation manager to provide the appropriate MIDs and BINs.
To process the payment, include the threeDSecure
object.
Sample Auth Capture request:
{
"amount": 11,
"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=",
"dsTransactionId" : "e08da266-b58d-45c9-a1f8-570b7fb80e30",
"threeDSecureVersion" : "2.1.0"
}
}
Supported 3-D Secure object properties
amount
number requiredcurrency
string requiredbillingFirstName
string optionalbillingLastName
string optionalbillingCountry
string optional Value must be a two-letter country code (ISO 3166-1 alpha-2). Find a complete list of country codes here.billingState
string
optional Value must be the state/province portion of the ISO 3166-2 code, in all uppercase characters. For example, for US-OH, send OH, or for GB-LND, send LND. If you are uncertain of the format, it is recommended to not pass a value.billingCity
string optionalbillingAddress
string optionalbillingZip
string optionalshippingFirstName
string optionalshippingLastName
string optionalshippingCountry
string optional
optional Value must be a two-letter country code (ISO 3166-1 alpha-2). Find a complete list of country codes here.shippingState
string optional
optional Value must be the state/province portion of the ISO 3166-2 code, in all uppercase characters. For example, for US-OH, send OH, or for GB-LND, send LND. If you are uncertain of the format, it is recommended to not pass a value.shippingCity
string optionalshippingAddress
string optionalshippingZip
string optionalemail
string optionalphone
string optional
Error codes
14100
Problem: 3-D Secure is not enabled
Resolution: Enable 3-D Secure
14101
Problem: 3-D Secure authentication failed
Resolution: Inform the shopper to try a different payment method
14102/10
Problem: 3-D Secure object is missing required fields { ... }
Resolution: Make sure 3-D Secure object has both transaction amount and currency
14103
Problem: 3-D Secure client error
Resolution: Continue without 3DS
Authentication results
AUTHENTICATION_BYPASSED
- Meaning: 3-D Secure authentication was bypassed due to the merchant's configuration or the shopper’s credit card issuing bank configuration.
- To Proceed: Process the transaction without 3-D Secure
AUTHENTICATION_SUCCEEDED
- Meaning: 3-D 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 3-D Secure chargeback liability shift.
- To Proceed:
- In Hosted Payment Fields: Process the 3-D Secure transaction
- In the Secured Payment Collector: Process the 3-D Secure transaction
- In Hosted Payment Fields: Process the 3-D Secure transaction
AUTHENTICATION_UNAVAILABLE
- Meaning: 3-D Secure is unavailable for this card or a technical error occurred.
- To Proceed: Process the transaction without 3-D Secure
AUTHENTICATION_FAILED
- Meaning: The card on the transaction could not be authenticated..
- To Proceed: If the option Process failed 3DS transactions is enabled in Settings > Fraud Settings in the Merchant Portal, then the transaction can be processed.
Note
The authentication result above is included in the Order Locator information for any order processed using 3-D Secure.
Testing 3-D Secure
For information about Sandbox testing of 3-D Secure, refer here.
Subscribing to Events
BlueSnap uses an event-based system that helps you get insight into what’s happening in real-time. It allows you to subscribe to different events that are triggered internally by BlueSnap. You only have to subscribe to an event once per page load. After that, you won't need to re-subscribe.
Keep in mind you should subscribe to events before you call the bluesnap.threeDsPaymentsSetup
function. The code snippets below are currently only applicable to 3DS with plain text cards and with returning shoppers.
bluesnap.on('setupComplete', () => {
// setupComplete
});
bluesnap.on('threeDsChallengeExecuted', () => {
// threeDsChallengeExecuted
});