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.

Before you Begin

If you are using the 3-D Secure in Hosted Payment Fields option, be sure you have implemented the latest version of Hosted Payment Fields.
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.
Merchant-initiated transactions are out-of-scope for 3-D Secure, provided they occur after a 3-D Secure customer-initiated transaction. Merchants who are using the BlueSnap Subscription Engine or our Merchant Managed Subscription feature are eligible for this out-of-scope exemption. To ensure your transaction is identified as merchant-initiated, use our Merchant Managed Subscription API. Refer to Create Merchant-Managed Subscription and Create Merchant-Managed Subscription Charge for details.
If you handle your own subscriptions (you are sending Auth Capture requests without the BlueSnap Subscription Engine or our merchant-managed subscription feature), be sure to follow the Rules for MITs.

🚧
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.

We strongly recommend you only download BlueSnap JavaScript once on page load, as re-downloading it can interfere with the 3DS flow.

Hosted Payment Fields

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.

Step 2: Enable 3-D Secure usage in the transaction

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

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 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 = {
  authenticationIndicator: '01',
  amount: 35.75, 
  currency: 'USD',
  billingAddress:'123 Main Street',
  billingCity:'Boston',
  billingCountry:'US',
  billingZip:'02453',
  billingState:'MA',
  email:'first.last@shopper.com',
  billingFirstName:'Jane',
  billingLastName:'Doe',
  phone:'+12222345678',
};

📘
If you're using surcharges, you must add the surcharge amount obtained from the Calculate Surcharge API to the total amount in this object.

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.

Plain Text Cards

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:
Production: https://ws.bluesnap.com/services/2/payment-fields-tokens
Sandbox: https://sandbox.bluesnap.com/services/2/payment-fields-tokens
For a saved card:
Production: https://ws.bluesnap.com/services/2/payment-fields-tokens/prefill
Sandbox: https://sandbox.bluesnap.com/services/2/payment-fields-tokens/prefill
{ "ccNumber":"4111 1111 1111 1111", "expDate" : "01/2022" }

The response provides the token in the location header. For example:
Production: https://ws.bluesnap.com/services/2/payment-fields-tokens/PAYMENTFIELDTOKENID
Sandbox: https://sandbox.bluesnap.com/services/2/payment-fields-tokens/PAYMENTFIELDTOKENID

Note: Secured Payments Token expires after 60 minutes.

📘
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://sandpay.bluesnap.com

Production: https://pay.bluesnap.com

For example, the Hosted Fields token request (step 1) should be sent to https://sandpay.bluesnap.com/services/2/payment-fields-tokens on Sandbox and https://pay.bluesnap.com/services/2/payment-fields-tokens on Production.

🚧
Important
Be sure to include the intended URL for the environment you are choosing to use. Including a URL that does not match the environment it is being used in will prevent the solution from working correctly.

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/5/bluesnap.js"></script>

Step 3: Initialize 3DS

To initialize 3-D Secure, call bluesnap.threeDsPaymentsSetup with the following parameters:

The token from step 1
A callback function to handle the data submission results (this occurs in step 4)

<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 by 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 of Success
10 — On a status of Invalid Data. This prevents the process from continuing. You should display the error to the shopper and prompt a fix. For example: Invalid provided currency.
15 — On a status of Invalid Data. This does not prevent the process from continuing. The callback is called with a warning array. The process continues and the callback is called again on completion or upon encountering another error. You should continue with the 3DS flow, as this error is for informational purposes only. For example: Invalid billingFirstName.
Other codes are the BlueSnap server HTTP errors or generic server errors (400, 500). For example:
- 22013 is CC_TYPE_IS_NOT_SUPPORTED_BY_THE_MERCHANT
- 14040 is TOKEN_IS_EXPIRED
- 14042 is TOKEN_IS_NOT_ASSOCIATED_WITH_A_PAYMENT_METHOD
- 14104 is SHOPPER_CC_NOT_FOUND
- 14102/10 is THREE_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 given
Amount is mandatory and must be of type number — An amount wasn’t provided or provided not as a number
Currency <given_currency> is not supported — The given currency is not supported
Currency is mandatory — An amount wasn’t provided
Invalid 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.

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).

📘
If you're using surcharges, you must add the surcharge amount obtained from the Calculate Surcharge API to the total amount in this script.

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. You can find examples of Auth Capture requests with 3DS on the Auth Capture page.

Returning Shoppers

Step 1: Obtain the 3DS Payments token for this session

Get your 3DS Payments token by sending a server-to-server POST request to:

Production: https://ws.bluesnap.com/services/2/payment-fields-tokens?shopperId=SHOPPERID
Sandbox: https://sandbox.bluesnap.com/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:

Production: https://ws.bluesnap.com/services/2/payment-fields-tokens/PAYMENTFIELDTOKENID
Sandbox: https://sandbox.bluesnap.com/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://sandpay.bluesnap.com/

Production: https://pay.bluesnap.com/

Note: Secured Payments Token expires after 60 minutes.

Step 2: Add the BlueSnap JavaScript file to your checkout page

In your checkout page, call the BlueSnap JavaScript file by adding the following script:

<script type="text/javascript" src="BLUESNAPDOMAINPATH/web-sdk/5/bluesnap.js"></script>

Step 3: Initialize 3DS

To initialize 3-D Secure, call bluesnap.threeDsPaymentsSetup with the following parameters:

The token from step 1
A callback function to handle the data submission results (this occurs in step 4)

<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 by 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 of Success
10 — On a status of Invalid Data. This prevents the process from continuing. You should display the error to the shopper and prompt a fix. For example: Invalid provided currency.
15 — On a status of Invalid Data. This does not prevent the process from continuing. The callback is called with a warning array. The process continues and the callback is called again on completion or upon encountering another error. You should continue with the 3DS flow, as this error is for informational purposes only. For example: Invalid billingFirstName.
Other codes are the BlueSnap server HTTP errors or generic server errors (400, 500). For example:
- 22013 is CC_TYPE_IS_NOT_SUPPORTED_BY_THE_MERCHANT
- 14040 is TOKEN_IS_EXPIRED
- 14042 is TOKEN_IS_NOT_ASSOCIATED_WITH_A_PAYMENT_METHOD
- 14104 is SHOPPER_CC_NOT_FOUND
- 14102/10 is THREE_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 a response before activating the submit form, add the script below to 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.

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).

📘
If you're using surcharges, you must add the surcharge amount obtained from the Calculate Surcharge API to the total amount in this script.

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. You can find examples of Auth Capture requests with 3DS on the Auth Capture page.

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.

Google Pay 3-D Secure

When using the Payment Request Button for a Google Pay flow, you can request 3-D Secure activation by passing '3DS': true to the sdkRequest object. You must pass this object as an argument to the bluesnap.walletButtonSetup function in Step 4, as shown below:

SdkRequest = {
  ... // Add all other properties,
  '3DS': true
};

When you activate 3-D secure, consider the following scenarios:

Not all Google Pay payments require additional 3-D Secure — Google Pay automatically determines if a payment method requires additional 3-D Secure authentication. Some payment methods are pre-authenticated or verified by Google Pay. In these cases, no further 3-D Secure authentication is requested, even if '3DS': true is specified.
Optional 3-D Secure activation after Soft Decline — You might want to activate 3-D Secure only after a transaction results in a Soft Decline, rather than immediately defaulting to 3-D Secure for all transactions.

To support these scenarios, a third parameter threeDSecure is returned to your payment authorized callback function.

threeDSecure Object

This parameter is an object that contains key 3-D Secure-related properties and methods:

Property	Type	Description
`canActivate3DS`	boolean	Indicates whether 3-D Secure can be activated.
`activate3DS`	function	Function to activate 3-D Secure authentication, which is only usable if canActivate3DS is `true` and threeDSActivated is `false`. If activated, after the flow concludes, the `paymentAuthorized` callback will be retriggered with 3-D Secure data (contained inside the threeDSData object).
`threeDSActivated`	boolean	Indicates if 3-D Secure was activated. If `true`, do not use the success or error callbacks for `paymentAuthorized` since the Google Pay UI has been closed as part of the 3-D Secure flow.
`threeDSData`	object	Optional. `threeDSData` object. Object that is only returned when 3DS has been activated. Contains 3DS data. See threeDSData Object.

threeDSData Object

Property	Type	Description
`authResult`	string	See Authentication Results.
`threeDSecureReferenceId`	string	Reference ID of the 3-D Secure flow, to be included in the transaction request sent to our Payment API as part of the `threeDSecure` object.

📘
Note
When threeDSActivated is true, there is no need to use the success or error callbacks that are passed as parameters to your paymentAuthorized function. This is because the Google Pay user interface has already been closed as part of the 3-D Secure flow.

Using your own Google Pay Token

If you have your own Google Pay implementation and you want to activate our 3-D Secure flow, make sure to create a Google Pay wallet token as explained in Wallet Token Creation. You can then use our 3-D Secure Plain Text Card flow with the exception of passing gpToken instead of card details in the submission step, to activate 3-D Secure for the payment method.

The submission step would need to be executed as follows:

const obj = {
    gpToken: "Your Google Pay token",
    amount: 10,
    currency: "USD"
};
 
bluesnap.threeDsPaymentsSubmitData(obj);

Initiating 3-D Secure after a 3DS Soft Decline

A 3DS soft decline occurs after a transaction results in an error (soft decline), prompting stricter authentication with 3DS. This error occurs either because the 3DS flow was not completed/activated, because of a merchant bypass, or because the transaction requires a shopper challenge that was not activated. If you receive a soft decline, you can use BlueSnap JavaScript to perform 3DS and re-initiate the transaction. To do so while ensuring 3DS will not be bypassed due to the shopper country, choose one of the following options depending on the scenario:

Scenario 1: You already have a token and used it for your first transaction attempt.

Send a server-to-server PUT request to the following URL: https://sandbox.bluesnap.com/services/2/ payment-fields-tokens/authentication-required-3ds

curl -v -X PUT https://sandbox.bluesnap.com/services/2/payment-fields-tokens/authentication-required-3ds \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json' \ 
   -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
   -d '
{
          "token": "your token"
    }'

curl -v -X PUT https://sandbox.bluesnap.com/services/2/payment-fields-tokens/authentication-required-3ds \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json' \ 
   -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
   -d '
{
          "token": "your token",
          "challengerequested3ds": true
    }'

Follow the steps to complete the 3-D Secure with Plain Text Cards flow with the following exceptions:

Skip Step 1 and use the token you already have instead of creating a new token.
On Step 4, include only the amount and currency fields in the object that you pass to the bluesnap.threeDsPaymentsSubmitData function. For example:
var bsObject = { "amount": 10, "currency": "USD" } bluesnap.threeDsPaymentsSubmitData(bsObject);

Scenario 2: No token was used for your first transaction attempt

Follow the steps to complete the 3-D Secure with Plain Text Cards flow with the following exception:

Step 1: When creating a token, add the following query parameters to the URL:
authenticationrequired3ds=true, challengerequested3ds=true (the latter is optional but recommended, and forces a 3DS shopper challenge).
For example: https://sandbox.bluesnap.com/services/2/payment-fields-tokens?authenticationrequired3ds=true&challengerequested3ds=true

curl -v -X POST https://sandbox.bluesnap.com/services/2/payment-fields-tokens?authenticationrequired3ds=true \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json' \ 
   -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
   -d '

curl -v -X POST https://sandbox.bluesnap.com/services/2/payment-fields-tokens?authenticationrequired3ds=true&challengerequested3ds=true \
   -H 'Content-Type: application/json' \
   -H 'Accept: application/json' \ 
   -H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
   -d '

Soft Decline Errors

THREE_D_SECURITY_AUTHENTICATION_REQUIRED
STRONG_CUSTOMER_AUTHENTICATION_REQUIRED

Find more information about these errors on the Card Transaction Errors page.

Processing payments with data from external merchant plugin (MPI)

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

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.

Example Auth Capture Request Body:

{
  "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

This section is relevant to all 3DS solutions detailed above.

Property	Type	Required
`authenticationIndicator`	string	Required Type of action for which you are using 3-D Secure authentication. Examples: `01`: Payment `02`: Recurring `03`: Payment + Store Card (where the cardholder chooses to store/save their card during the payment flow) `04`: Add Card `05`: Maintain / Update Card `06`: RFU PSD2 Requirement: You must pass 02 (Recurring) on the first 3DS Authentication of a recurring/subscription transaction. Subsequent merchant-initiated (MIT) transactions of the subscription are out of scope for 3DS.
`amount`	number	Required
`currency`	string	Required
`email`	string	Required Note: Either `email` or `phone` must meet the minimum requirements defined by the card network.
`phone`	string	Required As part of EMVCo specifications, at least one phone number (work, home or mobile) must be provided. The phone number should be unformatted and contain no hyphens. Examples: US: `+ 1-222-234-5678` = `+12222345678` UK: `+ 44-1234-123456` = `+441234123456` Note: Either `email` or `phone` must meet the minimum requirements defined by the card network.
`billingFirstName`	string	Required
`billingLastName`	string	Required
`billingCountry`	string	Recommended. Value must be a two-letter country code (ISO 3166-1 alpha-2). Find a complete list of country codes here.
`billingState`	string	Recommended. 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	Recommended
`billingAddress`	string	Recommended
`billingZip`	string	Recommended
`shippingFirstName`	string	Optional
`shippingLastName`	string	Optional
`shippingCountry`	string	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 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	Optional
`shippingAddress`	string	Optional
`shippingZip`	string	Optional

Note: The minimum data requirements do not apply if there are local data privacy regulations that prohibit the data field from being shared.

Error Codes

This section is relevant to all 3DS solutions detailed above.

Error Code	Description
`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

This section is relevant to all 3DS solutions detailed above.

`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*
in Hosted Payment Fields
in the Secured Payment Collector

`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

`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*
in Hosted Payment Fields
in the Secured Payment Collector

`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.*

`AUTHENTICATION_INCOMPLETE`

Meaning: 3-D Secure authentication was incomplete because the shopper failed to complete the challenge request from their issuing bank. This challenge request could be a challenge via their banking app on their phone, a pin number sent via SMS, or some other multi-factor challenge technique.
To Proceed: You could proceed to process the transaction without 3-D Secure*, if you are satisfied that the transaction is legitimate. If you choose to proceed, keep in mind you will be liable if the transaction is fraudulent.
with Hosted Payment Fields
with Secured Payment Collector

*This option is not available for Europe and the UK.

📘
Note
The authentication result above is included in the Order Locator information for any order processed using 3-D Secure.

Testing 3-D Secure

This section is relevant to all 3DS solutions detailed above.

For information about Sandbox testing of 3-D Secure, refer here.

Subscribing to Events

This section is only relevant to the following 3DS solutions: 3-D Secure with Plain Text Cards and 3-D Secure with Returning Shoppers.

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

});