Hosted Payment Fields and Tokenization
BlueSnap uses both one-time and multi-use tokens to securely process shopper data. When using Hosted Payment Fields with our Payment APIs, we leverage a one-time token (pfToken
). Hosted Payment Fields are iframes that replace sensitive credit card input fields on 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.
You can also create a multi-use token by including the one-time token within the pfToken
property in a Create Vaulted Shopper request. This will save the shopper's payment information, creating a new vaulted shopper.
Visit our Hosted Payment Fields Guide for full implementation details.
If you are using our Hosted Payment Page, we securely capture all shopper data automatically, so there are no additional steps you need to take during the sale. If you would then like to take advantage of our tokenization to simplify the checkout process for your returning shoppers, be sure to read our guide on how to implement this feature.
Credentials
You need a BlueSnap account and API credentials to take advantage of Hosted Payment Fields. 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.
Programming Languages
You can use our solution using plain JavaScript. Though our solution does not require jQuery, you may choose to use jQuery or JS frameworks like AngularJS and React.
Hosted Payment Fields Token (pfToken)
Creating a `pfToken'
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
Reusing a pfToken
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:
-
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. -
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.
Replacing a pfToken
Refer to the Updating the BlueSnap token section.
Creating/Updating Vaulted Shoppers with a pfToken
To create or update a vaulted shopper with the token, include pfToken
inside paymentSources
> creditCardInfo
.
For code samples, see our Developer Docs:
Visit our Hosted Payment Fields Guide for more information on bluesnap.hostedPaymentFieldsSubmitData
.
Upgrade 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:
- 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 sandboxhttps://ws.bluesnap.com
for production
- In your HTML form, make sure the Hosted Payment Fields
<div>
elements have the following mandatory naming convention for the values of thedata-bluesnap
attributes.
<div data-bluesnap="ccn"></div>
<div data-bluesnap="exp"></div>
<div data-bluesnap="cvv"></div>
- 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
};
- 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.
- Optional: To use a dropdown selector for the expiration date element, add the property
expDropDownSelector
tobsObj
and set its value to true.
var bsObj = {
...
expDropDownSelector: true //false by default
}
- Optional: Update the
style
property ofbsObj
. 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:
- 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 sandboxhttps://ws.bluesnap.com
for production
- 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)
- 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
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:
-
Change the URL:
fromsource/web-sdk/bluesnap.js
toweb-sdk/4/bluesnap.js
-
Change the following call:
frombluesnap.hostedPaymentFieldsCreation(token, bsObj);
tobsObj["token"] = token;
bluesnap.hostedPaymentFieldsCreate(bsObj);
-
Change call:
frombluesnap.submitCredentials
tobluesnap.hostedPaymentFieldsSubmitData
-
For
cardTypes
change:AmericanExpress
toAMEX
DinersClub
toDINERS
Discover
toDISCOVER
MasterCard
toMASTERCARD
Visa
toVISA
-
On the
onFieldEventHandler
>onError
:
- Errors
001
,002
,003
changed to10
- The description changed to
invalidCcNumber, invalidCvv, invalidExpDate
.
- Important
onFieldEventHandler > expDropDownSelector
currently is not supported.
For complete v4.0 implementation instructions and code samples, visit the Hosted Payment Fields guide.
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
- 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 3 months ago