{"_id":"593fe2282418a7003933a387","category":{"_id":"593fe2262418a7003933a35f","version":"593fe2262418a7003933a35e","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-01T16:04:11.135Z","from_sync":false,"order":0,"slug":"welcome","title":"Quickstart"},"user":"560d5913af97231900938124","parentDoc":null,"project":"57336fd5a6a9c40e00e13a0b","version":{"_id":"593fe2262418a7003933a35e","project":"57336fd5a6a9c40e00e13a0b","__v":1,"createdAt":"2017-06-13T13:01:26.536Z","releaseDate":"2017-06-13T13:01:26.536Z","categories":["593fe2262418a7003933a35f","593fe2262418a7003933a360","593fe2262418a7003933a361","593fe2262418a7003933a362","593fe2262418a7003933a363","593fe2262418a7003933a364","593fe2262418a7003933a365"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"3.21.2","version_clean":"8976.0.0-Basics","version":"8976-Basics"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-10-15T15:08:55.765Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"In this tutorial, we're going to create a basic payment form and set it up to use BlueSnap's Hosted Payment Fields. This will limit your PCI compliance burden to the simplest SAQ A level, because sensitive payment data will never hit your server.\n\nWhen you're using Hosted Payment Fields, the credit card number, CVV and expiration date are all saved directly to BlueSnap servers and associated with a token. Then you can use that token to process payments or save shopper details.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"If you already have a checkout page or app where shoppers can enter their payment information, you can jump ahead to [charging a card](doc:make-a-payment-payment-api).\"\n}\n[/block]\n##Basic checkout form\nTo begin, let's look at a typical checkout form: \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<!DOCTYPE html>\\n<html>\\n\\n<head>\\n  <meta charset=\\\"UTF-8\\\">\\n</head>\\n\\n<body>\\n\\n<form action=\\\"\\\" method=\\\"POST\\\" id=\\\"checkout-form\\\">\\n  \\n  <div>\\n\\t  <label for=\\\"creditCard\\\">Card Number</label>\\n\\t  <input type=\\\"text\\\" name=\\\"creditCard\\\" id=\\\"creditCard\\\" data-bluesnap=\\\"encryptedCreditCard\\\">\\n  </div>\\n \\n  <div>\\n\\t  <label for=\\\"cvv\\\">Security Code</label>\\n\\t  <input type=\\\"text\\\" name=\\\"cvv\\\" id=\\\"cvv\\\">\\n  </div>\\n  \\n  <div>\\n    <label for=\\\"Expiration\\\">Exp. (MM/YYYY)</label>\\n      <input type=\\\"text\\\" name=\\\"exp-month\\\" id=\\\"exp-month\\\" size=\\\"2\\\">\\n      <span> / </span>\\n      <input type=\\\"text\\\" name=\\\"exp-year\\\" id=\\\"exp-year\\\" size=\\\"4\\\">\\n  </div>\\n\\n  <button type=\\\"submit\\\" id=\\\"submit-button\\\">Buy Now</button>\\n  \\n</form>\\n</body>\\n\\n</html>\",\n      \"language\": \"html\",\n      \"name\": \"Sample checkout form\"\n    }\n  ]\n}\n[/block]\nThe input fields in this sample include the basic required information that you typically have to provide to BlueSnap's API in order to process a credit card payment.\n\nHowever, if you have the shopper's sensitive credit card data sent directly to your server, you will be responsible for a high PCI compliance level, which most merchants prefer to avoid.\n\nTherefore you likely want to use [Hosted Payment Fields](/v4.0/docs/hosted-payment-fields), as we will describe in this tutorial. Alternatively, you can implement [Client-side encryption](doc:client-side-encryption). \n\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Implementing Hosted Payment Fields\nFollow the steps below in order to implement Hosted Payment Fields in your checkout form.\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Insert the domain for either Sandbox or Production\",\n  \"body\": \"In all steps below, 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]\n###1. Obtain the Hosted Payment Field token for the session\nObtain the Hosted Payment Field token by sending a server-to-server POST request to:\n\n`BLUESNAPDOMAINPATH/services/2/payment-fields-tokens`\n\nThe response will provide the token in the location header. For example: \n`BLUESNAPDOMAINPATH/services/2/payment-fields-tokens/HOSTEDFIELDTOKENID`\n\n**Note:** You will need a BlueSnap account in order to generate a Hosted Payment Field token. If you don't have an account yet, you can [sign up for one here](http://home.bluesnap.com/get-started/).\n\n###2. Add the BlueSnap JavaScript file to your checkout form\nIn your checkout page, call the BlueSnap Hosted Payment Fields JavaScript file by adding the following script:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script type=\\\"text/javascript\\\" src=\\\"BLUESNAPDOMAINPATH/services/hosted-payment-fields/v1.0/bluesnap.hpf.mini.js\\\"></script>\",\n      \"language\": \"coffeescript\",\n      \"name\": \"Adding Hosted Payment Fields JavaScript file\"\n    }\n  ]\n}\n[/block]\n###3. Add the Hosted Payment Fields to your checkout form\nReplace the credit card number, expiration date and CVV input fields in your checkout form with the following `<div>` elements:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<div data-bluesnap=\\\"ccn\\\"></div>\\n\\t\\t\\t\\n<div data-bluesnap=\\\"exp\\\"></div>\\n\\t\\t\\t\\n<div data-bluesnap=\\\"cvv\\\"></div>\",\n      \"language\": \"html\",\n      \"name\": \"Hosted Payment Fields <div> elements\"\n    }\n  ]\n}\n[/block]\n**Note:** The values you define for the `data-bluesnap` attributes cannot contain spaces or special characters.\n\n###4. Add a script to initiate the Hosted Payment Fields with your Hosted Fields token\nIn order to call the Hosted Payment Fields script, add the following script to your checkout page below the `<div>` elements.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script>\\n\\tvar bsObj = {\\n\\t\\thostedPaymentFields: {\\n\\t\\t\\tccn: \\\"ccn\\\", // NAME OF CCN DATA BLUESNAP, \\n\\t\\t\\tcvv: \\\"cvv\\\", //NAME OF CVV DATA BLUESNAP, \\n\\t\\t\\texp: \\\"exp\\\" //NAME OF EXP DATA BLUESNAP  \\n\\t\\t},\\n\\t\\tonFieldEventHandler: {\\n\\t\\t\\t/* tagId returns: \\\"ccn\\\", \\\"cvv\\\", \\\"exp\\\"\\n\\t\\t\\tonFocus: function(tagId) {}, // Handle focus\\n\\t\\t\\tonBlur: function(tagId) {}, // Handle blur \\n\\t\\t\\tonError: function(tagId, errorCode) {}, // Handle a change in validation\\n\\t\\t\\tonEmpty: function(tagId, errorCode) {}, // Handle a change in validation\\n\\t\\t\\tonType: function(tagId, cardType) {}, // cardType will give card type, and only applies to ccn: CarteBleue, Visa, MasterCard, AmericanExpress, Discover, DinersClub, JCB, Solo, MaestroUK\\n\\t\\t\\tonValid: function(tagId) {}, // Handle a change in validation\\n\\t\\t}, \\n\\t\\tstyle: {\\n\\t\\t\\t/* Style elements (Selectors: \\\"#ccn\\\", \\\"#cvv\\\", \\\"#exp\\\", \\\"input\\\", \\\":focus\\\", \\\".valid\\\", \\\".invalid\\\") can receive properties: \\\"color\\\", \\\"font\\\", \\\"font-family\\\", \\\"font-size\\\", \\\"font-style\\\", \\\"font-weight\\\", \\\"line-height\\\", \\\"opacity\\\", \\\"outline\\\", \\\"text-shadow\\\", \\\"transition\\\" */\\n\\t\\t\\t\\\"Selector\\\": {\\n\\t\\t\\t\\t\\\"Property\\\": \\\"Value\\\",\\n\\t\\t\\t\\t\\\"Property2\\\": \\\"Value2\\\"\\n\\t\\t\\t},\\t\\t\\t\\t\\t\\t\\t\\t\\t\\t\\n\\t\\t\\t\\\"Selector2\\\": {\\n\\t\\t\\t\\t\\\"Property\\\": \\\"Value\\\"\\n\\t\\t\\t}\\n\\t\\t}\\n\\t};\\n  //Run the following command after Document Object Model (DOM) is fully loaded \\n\\tbluesnap.hostedPaymentFieldsCreation (\\\"HOSTEDFIELDTOKENID\\\", bsObj);\\n</script>\",\n      \"language\": \"html\",\n      \"name\": \"Initiating Hosted Payment Fields with token\"\n    }\n  ]\n}\n[/block]\nReplace `HOSTEDFIELDTOKENID` with the token you obtained in step 1.\n\nIn `bsObj`, the `ccn`, `cvv` and `exp` names must match the values of the `data-bluesnap` attributes in the Hosted Payment Field `<div>` elements.\n\nUse `onFieldEventHandler` to handle focus, blur, validation events, and to get the card type. For example, you can use this to identify when the user has entered a Visa card and then show the relevant icon for Visa.\n\n*Note*: If you wish to use BlueSnap icons per card type, they are available here:\n  * **AmericanExpress**: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/amex.png\n  * **DinersClub**: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/diners.png\n  * **Discover**: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/discover.png\n  * **JCB**: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/jcb.png\n  * **MaestroUK**: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/maestro.png\n  * **MasterCard**: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/mastercard.png\n  * **Visa**: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/visa.png\n  * **Solo**: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/solo.png\n  * **CarteBleue**: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/cb.png\t\n\nStyling is optional. For more details on the `style` capabilities, see [Styling the Hosted Payment Fields](/v4.0/docs/hosted-payment-fields#section-styling-the-hosted-payment-fields).\n\n###5. Add a script to submit credit card, expiration date and CVV data\nAdd the script below into your checkout form:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script>\\nbluesnap.submitCredentials(function(cardData){console.log('the card type is ' + cardData.ccType + ' and last 4 digits are ' + cardData.last4Digits + ' after that I can call final submit')})\\n</script>\",\n      \"language\": \"text\",\n      \"name\": \"Submit payment data to BlueSnap\"\n    }\n  ]\n}\n[/block]\nThis submits the credit card, expiration date and CVV data to BlueSnap, where it will be associated with the Hosted Payment Fields token.\n\nOn success, a card data object containing the card type and last four digits will be be passed to the `function (cardData)`. You can add a function to do the final submit of the form after the card type and last four digits are received.\n\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Example forms\nBelow are two examples of checkout forms that use BlueSnap's Hosted Payment Fields (click the HTML/CSS/JS tabs to view the code):\n\n###Version 1: with Bootstrap styling\n[block:html]\n{\n  \"html\": \"<iframe height='537' scrolling='no' src='//codepen.io/JaneBenson/embed/LxqPMx/?height=537&theme-id=0&default-tab=js,result&embed-version=2' frameborder='no' allowtransparency='true' allowfullscreen='true' style='width: 100%;'>\\n</iframe>\"\n}\n[/block]\n###Version 2: with Material styling\n[block:html]\n{\n  \"html\": \"<iframe height='537' scrolling='no' src='//codepen.io/JaneBenson/embed/OWdywe/?height=537&theme-id=0&default-tab=js,result&embed-version=2' frameborder='no' allowtransparency='true' allowfullscreen='true' style='width: 100%;'>\\n</iframe>\"\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n##Next: Start processing payments\nNow that you have a way to collect shopper payment information and get it to your server, you can jump right into processing your first payments. See [Charge a card (Payment API)](doc:make-a-payment-payment-api) or [Charge a card (Extended Payment API)](doc:make-a-payment-extended-api).","excerpt":"Follow this tutorial to build your first checkout form, where you can collect payment information from your shoppers.","slug":"build-a-form","type":"basic","title":"Build a Checkout Form"}

Build a Checkout Form

Follow this tutorial to build your first checkout form, where you can collect payment information from your shoppers.

In this tutorial, we're going to create a basic payment form and set it up to use BlueSnap's Hosted Payment Fields. This will limit your PCI compliance burden to the simplest SAQ A level, because sensitive payment data will never hit your server.

When you're using Hosted Payment Fields, the credit card number, CVV and expiration date are all saved directly to BlueSnap servers and associated with a token. Then you can use that token to process payments or save shopper details.

If you already have a checkout page or app where shoppers can enter their payment information, you can jump ahead to charging a card.

Basic checkout form

To begin, let's look at a typical checkout form:

<!DOCTYPE html>
<html>

<head>
  <meta charset="UTF-8">
</head>

<body>

<form action="" method="POST" id="checkout-form">
  
  <div>
	  <label for="creditCard">Card Number</label>
	  <input type="text" name="creditCard" id="creditCard" data-bluesnap="encryptedCreditCard">
  </div>
 
  <div>
	  <label for="cvv">Security Code</label>
	  <input type="text" name="cvv" id="cvv">
  </div>
  
  <div>
    <label for="Expiration">Exp. (MM/YYYY)</label>
      <input type="text" name="exp-month" id="exp-month" size="2">
      <span> / </span>
      <input type="text" name="exp-year" id="exp-year" size="4">
  </div>

  <button type="submit" id="submit-button">Buy Now</button>
  
</form>
</body>

</html>

The input fields in this sample include the basic required information that you typically have to provide to BlueSnap's API in order to process a credit card payment.

However, if you have the shopper's sensitive credit card data sent directly to your server, you will be responsible for a high PCI compliance level, which most merchants prefer to avoid.

Therefore you likely want to use Hosted Payment Fields, as we will describe in this tutorial. Alternatively, you can implement Client-side encryption.

Back to Top

Implementing Hosted Payment Fields

Follow the steps below in order to implement Hosted Payment Fields in your checkout form.

Insert the domain for either Sandbox or Production

In all steps below, 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.

1. Obtain the Hosted Payment Field token for the session

Obtain the Hosted Payment Field token by sending a server-to-server POST request to:

BLUESNAPDOMAINPATH/services/2/payment-fields-tokens

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

Note: You will need a BlueSnap account in order to generate a Hosted Payment Field token. If you don't have an account yet, you can sign up for one here.

2. Add the BlueSnap JavaScript file to your checkout form

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

<script type="text/javascript" src="BLUESNAPDOMAINPATH/services/hosted-payment-fields/v1.0/bluesnap.hpf.mini.js"></script>

3. Add the Hosted Payment Fields to your checkout form

Replace the credit card number, expiration date and CVV input fields in your checkout form with the following <div> elements:

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

Note: The values you define for the data-bluesnap attributes cannot contain spaces or special characters.

4. Add a script to initiate the Hosted Payment Fields with your Hosted Fields token

In order to call the Hosted Payment Fields script, add the following script to your checkout page below the <div> elements.

<script>
	var bsObj = {
		hostedPaymentFields: {
			ccn: "ccn", // NAME OF CCN DATA BLUESNAP, 
			cvv: "cvv", //NAME OF CVV DATA BLUESNAP, 
			exp: "exp" //NAME OF EXP DATA BLUESNAP  
		},
		onFieldEventHandler: {
			/* tagId returns: "ccn", "cvv", "exp"
			onFocus: function(tagId) {}, // Handle focus
			onBlur: function(tagId) {}, // Handle blur 
			onError: function(tagId, errorCode) {}, // Handle a change in validation
			onEmpty: function(tagId, errorCode) {}, // Handle a change in validation
			onType: function(tagId, cardType) {}, // cardType will give card type, and only applies to ccn: CarteBleue, Visa, MasterCard, AmericanExpress, Discover, DinersClub, JCB, Solo, MaestroUK
			onValid: function(tagId) {}, // Handle a change in validation
		}, 
		style: {
			/* Style elements (Selectors: "#ccn", "#cvv", "#exp", "input", ":focus", ".valid", ".invalid") can receive properties: "color", "font", "font-family", "font-size", "font-style", "font-weight", "line-height", "opacity", "outline", "text-shadow", "transition" */
			"Selector": {
				"Property": "Value",
				"Property2": "Value2"
			},										
			"Selector2": {
				"Property": "Value"
			}
		}
	};
  //Run the following command after Document Object Model (DOM) is fully loaded 
	bluesnap.hostedPaymentFieldsCreation ("HOSTEDFIELDTOKENID", bsObj);
</script>

Replace HOSTEDFIELDTOKENID with the token you obtained in step 1.

In bsObj, the ccn, cvv and exp names must match the values of the data-bluesnap attributes in the Hosted Payment Field <div> elements.

Use onFieldEventHandler to handle focus, blur, validation events, and to get the card type. For example, you can use this to identify when the user has entered a Visa card and then show the relevant icon for Visa.

Note: If you wish to use BlueSnap icons per card type, they are available here:

  • AmericanExpress: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/amex.png
  • DinersClub: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/diners.png
  • Discover: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/discover.png
  • JCB: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/jcb.png
  • MaestroUK: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/maestro.png
  • MasterCard: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/mastercard.png
  • Visa: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/visa.png
  • Solo: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/solo.png
  • CarteBleue: BLUESNAPDOMAINPATH/services/hosted-payment-fields/cc-types/cb.png

Styling is optional. For more details on the style capabilities, see Styling the Hosted Payment Fields.

5. Add a script to submit credit card, expiration date and CVV data

Add the script below into your checkout form:

<script>
bluesnap.submitCredentials(function(cardData){console.log('the card type is ' + cardData.ccType + ' and last 4 digits are ' + cardData.last4Digits + ' after that I can call final submit')})
</script>

This submits the credit card, expiration date and CVV data to BlueSnap, where it will be associated with the Hosted Payment Fields token.

On success, a card data object containing the card type and last four digits will be be passed to the function (cardData). You can add a function to do the final submit of the form after the card type and last four digits are received.

Back to Top

Example forms

Below are two examples of checkout forms that use BlueSnap's Hosted Payment Fields (click the HTML/CSS/JS tabs to view the code):

Version 1: with Bootstrap styling

Version 2: with Material styling

Back to Top

Next: Start processing payments

Now that you have a way to collect shopper payment information and get it to your server, you can jump right into processing your first payments. See Charge a card (Payment API) or Charge a card (Extended Payment API).