All Topics
BlueSnap.comDeveloper DocsShopper SupportStatusTalk to Sales

Hosted Payment Fields FAQs

How do I upgrade my Hosted Payment Fields version?

Upgrade from v1.0 to v2.0

Switching from v1.0 to v2.0 consists of a few steps outlined below. By upgrading, you'll stay up-to-date with the latest Hosted Payment Fields technology and take advantage of some new changes, including a streamlined expiration date input element, the option to use an expiration date drop-down list, and simplified event-handling.

Get started with these steps:

  1. Change the BlueSnap JavaScript file name according to the code below: 
<script type="text/javascript" src="BLUESNAPDOMAINPATH/services/hosted-payment-fields/v2.0/bluesnap.hpf.min.js"></script>

Replace BLUESNAPDOMAINPATH with:

  • https://sandbox.bluesnap.com for sandbox
  • https://ws.bluesnap.com for production
  1. In your HTML form, make sure the Hosted Payment Fields <div> elements have the following mandatory naming convention for the values of the data-bluesnap attributes. 
<div data-bluesnap="ccn"></div>
<div data-bluesnap="exp"></div>		
<div data-bluesnap="cvv"></div>
  1. In bsObj of your JavaScript code, make the following changes:
  • Remove the hostedPaymentFields object.
  • Remove the onEmpty event handler. onError is now called if an element is empty.

The code sample below shows bsObj after making these changes (condensed for brevity): 

var bsObj = {
  onFieldEventHandler: {
    onFocus: function(tagId) {}, 
    onBlur: function(tagId) {}, 
    onError: function(tagId, errorCode) {},  
    onType: function(tagId, cardType) {}, 
    onValid: function(tagId) {}
  }, 
  style: {
    // Optional
  },
  ccnPlaceHolder: "1234 5678 9012 3456", // Optional
  cvvPlaceHolder: "123", // Optional
  expPlaceHolder: "MM/YY" // Optional
};
  1. Update your code according to the following changes to the errorCode parameter values.
    • value 004 is now 400 and indicates that the session expired.
    • value 005 is now split into 403, 404, and 500 and indicates that a BlueSnap internal server error occurred.
  2. Optional: To use a dropdown selector for the expiration date element, add the property expDropDownSelector to bsObj and set its value to true. 
var bsObj = {
  ...
  expDropDownSelector: true //false by default
}
  1. Optional: Update the style property of bsObj. Note that the selector #exp has been replaced with #month and #year, allowing you to style the month and year portions separately of the expiration date element. For an updated list of the supported selectors, see Styling the Hosted Payment Fields.

Upgrade from v2.0 to v3.0

Switching from v2.0 to v3.0 (Web SDK) consists of a few steps outlined below. By upgrading, you'll stay up-to-date with the latest Hosted Payment Fields technology and take advantage of some new changes, including a streamlined expiration date input element, the option to use an expiration date dropdown, and simplified event-handling.

Get started with these steps:

  1. Change the BlueSnap JavaScript file name according to the code below:
<script type="text/javascript" src="BLUESNAPDOMAINPATH/source/web-sdk/bluesnap.js"></script>

Replace BLUESNAPDOMAINPATH with:

  • https://sandbox.bluesnap.com for sandbox
  • https://ws.bluesnap.com for production
  1. In the script that initiates the Hosted Payment Fields with your Hosted Fields token, change the errorCode returns to the following:
/*errorCode returns:
                "001" --> "Please enter a valid credit card number";
                "002" --> "Please enter the CVV/CVC of your card";
                "003" --> "Please enter your credit card's expiration date";
                "22013" --> "CC type is not supported by the merchant"; 
                "14040" --> " Token is expired";
                "14041" --> " Could not find token";
                "14042" --> " Token is not associated with a payment method, please verify your client integration or contact BlueSnap support";
                "400" --> "Session expired please refresh page to continue";
                "403", "404", "500" --> "Internal server error please try again later"; 
            */

And in the same script, change the selectors as follows: 

(Selectors: "#ccn", "#cvv", "#year", "#month", "input", "::placeholder", ":focus", ".valid", ".invalid", "span", "select", "option")
(Properties: "color", "font", "font-family", "font-size", "font-style", "font-weight", "line-height", "opacity", "outline", "text-shadow", "transition",
"left", "margin-right", "width", "height", "background-color)
  1. In the script where you submit credit card, expiration date, and CVV data, change the do_when_clicking_submit_button() function to the following:
<script>
    function do_when_clicking_submit_button(){                                             
		    bluesnap.hostedPaymentFieldsSubmitData( function(callback){
            if (null != callBack.cardData) {
                console.log('the card type is ' + callBack.cardData.ccType                            
                + ', last 4 digits are ' + callBack.cardData.last4Digits      
                + ', exp is ' + callBack.cardData.exp 
                + ' and issuing Country is ' 
                + callBack.cardData.issuingCountry + ', after that I can call final submit');               
				        // submit the form  
                } else {  
                var errorArray = callBack.error;
            	  for (i in errorArray) {
                    console.log("Received error: tagId= " + errorArray[i].tagId 
                    + ", errorCode= " + errorArray[i].errorCode 
                    + ", errorDescription= " + errorArray[i].errorDescription);
            		}
            }             
		    });
	  }                                                            
</script>

Upgrade from v3.0 to v4.0

🚧

Important

BlueSnap recommends that you upgrade from v3.0 directly to v5.0. In addition to the latest features, v5.0 is in compliance with the most recent 3D Secure regulations implemented by the EU.

For instructions, see Upgrade from v3.0 to v5.0.

Switching from v3.0 to v4 (Web SDK) consists of a few steps outlined below. By upgrading, you'll stay up-to-date with the latest Hosted Payment Fields technology and take advantage of some new changes.
Get started with these steps:

  1. Change the URL:
    from source/web-sdk/bluesnap.js
    to web-sdk/4/bluesnap.js

  2. Change the following call:
    from bluesnap.hostedPaymentFieldsCreation(token, bsObj);
    to bsObj["token"] = token;
    bluesnap.hostedPaymentFieldsCreate(bsObj);

  3. Change call:
    from bluesnap.submitCredentials
    to bluesnap.hostedPaymentFieldsSubmitData

  4. For cardTypes change:

    • AmericanExpress to AMEX
    • DinersClub to DINERS
    • Discover to DISCOVER
    • MasterCard to MASTERCARD
    • Visa to VISA

  5. On the onFieldEventHandler > onError:

  • Errors 001, 002, 003 changed to 10
  • The description changed to invalidCcNumber, invalidCvv, invalidExpDate.

Notes:

  • onFieldEventHandler > expDropDownSelectoris not currently supported.
  • When a field fails client-side validation, we only activate the onError function. We do not call the merchant’s callback.

👍

For complete v4.0 implementation instructions and code samples, visit the Hosted Payment Fields guide.

Upgrade from v3.0 to v5.0

BlueSnap lets you upgrade the Web SDK from v3.0 directly to v5.0. Upgrading to v5.0 gives you the latest Hosted Payment Fields technology and keeps you in compliance with the most recent 3D Secure regulations implemented by the EU.

The following changes reference code samples provided in Hosted Payment Fields:

  • In the HTML script element that adds the BlueSnap Javascript file to your checkout form, change the src attribute to use the Web SDK v5.0 domain path:
    Sandbox script element 
    <script type="text/javascript" src="sandpay.bluesnap.com/web-sdk/5/bluesnap.js"></script>
    Production script element 
    <script type="text/javascript" src="pay.bluesnap.com/web-sdk/5/bluesnap.js"></script>
  • The following changes were made to the onError method in bsObj.onFieldEventHandler:
    • Errors 001, 002, and 003 to were replaced with error 10.
    • The errorDescription callback parameter is optional. It returns invalid or empty to describe why the field threw the error.
      To determine which input threw the error, you can use the tagId parameter.
    • The eventOrigin callback parameter is optional. It returns onBlur or onSubmit depending on the scenario.
    • You can include the optional updateAccessibilityError callback parameter. For implementation details, see Customizing the Hosted Payment Fields.
  • ThebsObj.expDropDownSelector property is no longer supported.
  • Replace bluesnap.hostedPaymentFieldsCreation(token, bsObj); with the following code: 
    bsObj["token"] = token;
bluesnap.hostedPaymentFieldsCreate(bsObj);
  • In the function that submits payment data to BlueSnap, change bluesnap.submitCredentials to bluesnap.hostedPaymentFieldsSubmitData. For example: 
    function do_when_clicking_submit_button(){
    bluesnap.hostedPaymentFieldsSubmitData(function(callback){
        ...
  • For cardTypes, credit card names where changed to the following:
    • AmericanExpress is now AMEX
    • DinersClub is now DINERS
    • Discover is now DISCOVER
    • MasterCard is now MASTERCARD
    • Visa is now VISA
  • When a field fails client-side validation, BlueSnap activates only the onError function. BlueSnap does not call your merchant callback.

Upgrade from v4.0 to v5.0

Switching from v4 to v5 (Web SDK) consists of a few steps outlined below. By upgrading, you'll stay up-to-date with the latest Hosted Payment Fields technology and take advantage of some new changes.
Get started with these steps:
BlueSnap domain path have been changed to:

  • Sandbox: https://sandpay.bluesnap.com
  • Production: https://pay.bluesnap.com

In onFieldEventHandler:

  • onError function parameters are now tagId, errorCode, errorDescription, eventOrigin and updateAccessibilityError.
  • eventOrigin will return onBlur | onSubmit depending on the scenario.
  • updateAccessibilityError is part of the accessibility feature customization capabilities. See Customizing Accessibility Features for more information.
  • In scenario errorCode: “10” description can be either “invalid” or “empty” depending on the scenario, for example:
    • (errorCode: "10", errorDescription: "empty", eventOrigin: "onBlur", tagId: "ccn", updateAccessibilityError: Function)
    • (errorCode: "10", errorDescription: "invalid", eventOrigin: "onSubmit", tagId: "ccn", updateAccessibilityError: Function)
  • errorDescription, eventOrigin and updateAccessibilityError are all optional.

For complete v5.0 implementation instructions and code samples, visit the Hosted Payment Fields guide.

Back to Top

Updated 9 months ago