Support Guides

Hosted Payment Fields FAQs

What are Hosted Payment Fields?

Hosted Payment Fields are iframes that replace sensitive credit card input fields in your checkout page. When the shopper submits the checkout form, BlueSnap binds the sensitive card data to a token. Then, you can easily process payments or save shopper details by including the token in your BlueSnap API requests.

Visit our Hosted Payment Fields Guide for full implementation details.

What credentials do I need to use Hosted Payment Fields?

You need a BlueSnap account and API credentials. Every API request must be authenticated using a HTTP Basic Authentication header, as follows:
Authorization: Basic {Base64 encoding of 'username:password'}

Refer to Authentication & Headers for more information.

Does the Hosted Payment Fields script require jQuery?

No. Our solution does not require jQuery. You can use our solution using plain JavaScript. However, you can use jQuery, or JS frameworks like AngularJS and React if you want to.

How can I create a Hosted Payment Fields token?

Send a server-to-server POST request to:
BLUESNAPDOMAINPATH/services/2/payment-fields-tokens, where BLUESNAPDOMAINPATH is either:

  • Sandbox: https://sandbox.bluesnap.com
  • Production: https://ws.bluesnap.com

The response provides the token in the location header.
For example:
BLUESNAPDOMAINPATH/services/2/payment-fields-tokens/HOSTEDFIELDTOKENID

Can I reuse the Hosted Payment Fields token?

For each session, you need to create a new token via Create Token request. The token expires 60 minutes after its creation. Within these 60 minutes, you may do the following:

  1. Client-side — Call bluesnap.hostedPaymentFieldsSubmitData to submit the shopper's payment details to BlueSnap and bind them to the token. This function can be called as many times as needed before the 60 minutes are up, and before sending the token in a request from your server to BlueSnap.

  2. Server-side — After the shopper's card details are associated with the token (assuming the token has not yet expired), you may send the token in a request to BlueSnap to either submit the payment for processing or save the payment information to a shopper. After the token is successfully submitted in a request to BlueSnap, it expires and cannot be used again in another request.

How can I replace the Hosted Payment Fields token?

Refer to the Updating the BlueSnap token section.

How do I create or update a vaulted shopper with the Hosted Payment Fields token?

To create or update a vaulted shopper with the token, include pfToken inside paymentSources > creditCardInfo.

For code samples, see our Developer Docs:

Can I change the placeholder text inside the Hosted Payment Fields?

Yes. Inside the BlueSnap object, you can change the placeholder text.

For example: 

var bsObj = {
  ... 
  ccnPlaceHolder: "4111 1111 1111 1111",
  cvvPlaceHolder: "123", 
  expPlaceHolder: "MM/YY"
};

How can I style the credit card, CVV, and expiration date inputs?

The iframes inside the div elements are transparent. If you want to style the actual div element, you can do it as you normally would. If you want to style the text within the input field of the iframe, you can do it by defining the style property of the BlueSnap object (bsObj). Visit our Hosted Payment Fields Guide for a code sample.

Can I call bluesnap.hostedPaymentFieldsCreation before the DOM is fully loaded?

No. bluesnap.hostedPaymentFieldsCreation can only be called after the DOM is fully loaded. Since the function dynamically creates iframes , the DOM must be fully loaded to ensure the elements are created successfully.

One way to run the script after the DOM is fully loaded is to place the script element after the body element: 

<html>
  ...
  </body>
  <script>
    ... 
    bluesnap.hostedPaymentFieldsCreate (bsObj);
  </script>
</html>

You can also achieve this using the jQuery ready() method: 

... 
$(document).ready(function () {
	bluesnap.hostedPaymentFieldsCreate (bsObj);

How does the bluesnap.hostedPaymentFieldsSubmitData function work?

When bluesnap.hostedPaymentFieldsSubmitData is called, the shopper's credit card data stored in the data-bluensnap fields are submitted to BlueSnap and associated with the token. If all data-bluesnap inputs are successfully submitted to BlueSnap (meaning no client-side validation error, server error, or empty input fields), the callback function passed inside bluesnap.hostedPaymentFieldsSubmitData is called with a cardData object containing the card type, last four digits, expiration date, and issuing country (if applicable).

For example, if you are using Hosted Payment Fields to collect credit card number, expiration date, and CVV: 

bluesnap.hostedPaymentFieldsSubmitData( function(cardData) {
  // Credit card number, expiration date, & CVV were successfully submitted to BlueSnap
  console.log(cardData.ccType) // card type
  console.log(cardData.last4Digits) // last 4 digits of ccn
  console.log(cardData.issuingCountry) // issuing country
  // Here is where you perform final submission to your server... 
});

Visit our Hosted Payment Fields Guide for more information on bluesnap.hostedPaymentFieldsSubmitData.

Can I verify CVV when a shopper uses a saved card?

Yes. Follow the steps in the Hosted Payment Fields Guide with these changes:

In Step 3, include one <div> element for CVV, as shown in the below code. Note that the value for the data-bluesnap attribute must be typed exactly as shown below, or else the implementation won't work. 

<div data-bluesnap="cvv"></div>

Note that in Step 5, cardData will be empty.

When you send the payment for processing, you'll pass the securityCodePfToken property with its value set to your token, as shown in the Auth Capture request below. 

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": 11,
    "currency": "USD",
    "vaultedShopperId": 19557598,
    "softDescriptor": "Merchant ABC",
    "creditCard": {
        "cardLastFourDigits": "1111",
        "cardType": "VISA", 
      	"securityCodePfToken": "b1c3039eaae550483c07cb0dfd1e978dce91de560cc5c87993f161741e26d153_"   	
    }
}'

How can I upgrade from v1.0 to v2.0 of the Hosted Payment Fields?

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.

How can I upgrade from v2.0 to v3.0 of the Hosted Payment Fields?

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>

How can I upgrade from v3.0 to v4.0 of the Hosted Payment Fields?

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.

  6. Important
    onFieldEventHandler > expDropDownSelector currently is not supported.

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

Back to Top

Updated 5 months ago

Hosted Payment Fields FAQs

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.