{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","settings":"","results":{"codes":[]},"params":[]},"next":{"description":"","pages":[]},"title":"Secured Payment Collector","type":"basic","slug":"secured-payment-collector","excerpt":"","body":"BlueSnap's Secured Payment Collector allows you to securely collect the shopper's sensitive details for ACH/ECP and card payments. Secured Payment Collector consists of discrete `input` fields that give you complete control over the look and feel of your checkout form while giving customers the seamless experience of staying on your website. When the shopper submits the checkout form, BlueSnap securely captures and tokenizes their sensitive information. You can then include the token in the API request to finish the transaction or save their information for future use. \n \n\n# Implementing Secured Payment Collector\nImplementing Secured Payment Collector consists of these steps: \n[1. Obtain the token for the session](#section-1-obtain-the-token-for-the-session)\n[2. Add the BlueSnap JavaScript file to your form](#section-2-add-the-bluesnap-javascript-file-to-your-form)\n[3. Add input fields to your form](#section-3-add-the-input-fields-to-your-form)\n[4. Initialize the Secured Payment Collector](#section-4-initialize-the-secured-payment-collector)\n[5. Submit the shopper's data to BlueSnap](#section-5-submit-the-shopper-s-data-to-bluesnap)\n[Updating an expired token](#section-updating-an-expired-token)\n[Using the token to process payments](#section-using-the-token-to-process-payments)\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"In all steps below, replace the `BLUESNAPDOMAINPATH` with the relevant BlueSnap domain:\\n\\n* Sandbox: `https://sandbox.bluesnap.com`\\n* Production: `https://ws.bluesnap.com`\",\n  \"title\": \"Insert the domain for either Sandbox or Production\"\n}\n[/block]\n## 1. Obtain the token for the session\nObtain the token by sending a server-to-server POST request to: \n\n`BLUESNAPDOMAINPATH/services/2/payment-fields-tokens` \n\nThe response provides the token in the location header. For example: \n`BLUESNAPDOMAINPATH/services/2/payment-fields-tokens/12345abcde` \n\n**Note:** The token expires after 60 minutes. \n\n## 2: Add the BlueSnap JavaScript file to your form \nIn your form, call the BlueSnap JavaScript file by adding the following script. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<script type=\\\"text/javascript\\\" src=\\\"BLUESNAPDOMAINPATH/web-sdk/4/bluesnap.js\\\"></script> \",\n      \"language\": \"html\"\n    }\n  ]\n}\n[/block]\n ## 3: Add the input fields to your form \nAdd `input` elements to your form with a `data-bluesnap` attribute so BlueSnap knows where to capture the sensitive data from. See the code samples below for the specific inputs to add to your form. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"<form action=\\\"#\\\">\\n  <label for=\\\"ecpRoutingNumber\\\">Routing Number:</label>\\n  <input id=\\\"ecpRoutingNumber\\\" name=\\\"ecpRoutingNumber\\\" data-bluesnap=\\\"ecpRoutingNumber\\\" placeholder=\\\"ACH/ECP Routing Number\\\" />\\n\\n  <label for=\\\"ecpAccountNumber\\\">Account Number:</label>\\n  <input id=\\\"ecpAccountNumber\\\" name=\\\"ecpAccountNumber\\\" data-bluesnap=\\\"ecpAccountNumber\\\" placeholder=\\\"ACH/ECP Account Number\\\" />\\n\\n  <label for=\\\"ecpAccountType\\\">Account Type:</label>\\n  <input id=\\\"ecpAccountType\\\" name=\\\"ecpAccountType\\\" data-bluesnap=\\\"ecpAccountType\\\" placeholder=\\\"ACH/ECP Account Type\\\" />\\n</form>\",\n      \"language\": \"html\",\n      \"name\": \"ACH/ECP\"\n    },\n    {\n      \"code\": \"<form action=\\\"#\\\">\\n  <label for=\\\"ccn\\\">credit card number:</label>\\n  <input id=\\\"ccn\\\" name=\\\"ccn\\\" data-bluesnap=\\\"ccn\\\" pattern=\\\"^[0-9]{10,26}$\\\" placeholder=\\\"1234567890123456\\\" />\\n\\n  <label for=\\\"cvv\\\">cvv:</label>\\n  <input id=\\\"cvv\\\" name=\\\"cvv\\\" data-bluesnap=\\\"cvv\\\" pattern=\\\"^[0-9]{3,4}$\\\" placeholder=\\\"123\\\" />\\n\\n  <label for=\\\"exp\\\">expiration date:</label>\\n  <input id=\\\"exp\\\" name=\\\"exp\\\" data-bluesnap=\\\"exp\\\" pattern=\\\"^[0-9]{2}\\\\/[0-9]{4}$\\\" placeholder=\\\"MM/YYYY\\\" />\\n</form>\",\n      \"language\": \"html\",\n      \"name\": \"New card\"\n    },\n    {\n      \"code\": \"<form action=\\\"#\\\">\\n  <label for=\\\"last4digits\\\">Credit card (last 4 digits)</label>\\n  <input id=\\\"last4digits\\\" name=\\\"last4digits\\\" data-bluesnap=\\\"last4digits\\\" pattern=\\\"^[0-9]{4}$\\\" placeholder=\\\"1234\\\" />\\n\\n  <label for=\\\"type\\\">Card type</label>\\n  <input id=\\\"type\\\" name=\\\"type\\\" data-bluesnap=\\\"type\\\" pattern=\\\"^[A-Z]{3,}([_][A-Z]{3,}){0,}$\\\" placeholder=\\\"VISA\\\" />\\n</form>\",\n      \"language\": \"html\",\n      \"name\": \"Saved card\"\n    }\n  ]\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"warning\",\n  \"body\": \"The `data-bluesnap` values must be entered exactly as they appear in the above code samples in order for your implementation to work.\",\n  \"title\": \"data-bluesnap values\"\n}\n[/block]\n## 4. Initialize the Secured Payment Collector\nAfter the DOM and the BlueSnap JavaScript file are fully loaded, initialize the Secured Payment Collector by calling `bluesnap.securedPaymentCollectorSetup` with the following parameters: \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Parameter\",\n    \"h-1\": \"Required\",\n    \"0-0\": \"PAYMENT_TOKEN\",\n    \"0-1\": \"**Required**\",\n    \"h-2\": \"Description\",\n    \"0-2\": \"The token you obtained in Step 1.\",\n    \"1-0\": \"Callback function\",\n    \"1-1\": \"**Required**\",\n    \"1-2\": \"Callback function for when the data submission attempt is completed. It will receive a [`sdkResponse` object](/v8976-Tools/docs/sdkresponse-object) containing the submission result. Your function should detect the result and respond accordingly. \\n\\nFor example, if the data submission was successful (when `sdkResponse.code` is `1`), you should continue the form submission to your server and [process the payment](#section-using-the-token-to-process-payments).\",\n    \"2-0\": \"3-D Secure boolean\",\n    \"2-1\": \"Optional; Only applicable for card payments.\",\n    \"2-2\": \"Whether the card transaction should use [3-D Secure](/docs/3-d-secure-for-api). Default value is `false`.\"\n  },\n  \"cols\": 3,\n  \"rows\": 3\n}\n[/block]\nDepending on the shopper's payment method, your code will look similar to the following code samples. The primary difference between the code samples is whether `sdkResponse` contains the `cardData` property.     \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Run after DOM and BlueSnap JS are fully loaded\\ndocument.addEventListener('DOMContentLoaded', function () {\\n  bluesnap.securedPaymentCollectorSetup(\\n    'PAYMENT_TOKEN',\\n    function (sdkResponse) {\\n      if (sdkResponse.code === 1) {\\n        // Data submission was a success\\n        // Continue form submission to your server & complete the transaction\\n      } else {\\n        // Data submission resulted in error or warning\\n        const { errors, warnings } = sdkResponse.info;\\n        console.log('Errors: ', errors);\\n        console.log('Warnings: ', warnings);\\n      }\\n    },\\n    false\\n  );\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"ACH/ECP\"\n    },\n    {\n      \"code\": \"// Run after DOM and BlueSnap JS are fully loaded\\ndocument.addEventListener('DOMContentLoaded', function () {\\n  bluesnap.securedPaymentCollectorSetup(\\n    'PAYMENT_TOKEN',\\n    function (sdkResponse) {\\n      if (sdkResponse.code === 1) {\\n        // Submission was successful\\n        const { cardData /*, threeDSecure */ } = sdkResponse;\\n        console.log('Card Data:', cardData);\\n        // Continue form submission to your server & complete the transaction\\n      } else {\\n        // Submission resulted in an error or warning\\n        const { errors, warnings } = sdkResponse.info;\\n        console.log('Errors: ', errors);\\n        console.log('Warnings: ', warnings);\\n      }\\n    },\\n    false // set to true for 3-D Secure\\n  );\\n});\",\n      \"language\": \"javascript\",\n      \"name\": \"Cards\"\n    }\n  ]\n}\n[/block]\n## 5. Submit the shopper's data to BlueSnap\nWhen the shopper clicks the submit button on your form, you will submit their data directly to BlueSnap, where it will be securely stored and associated with your token. Call `bluesnap.securedPaymentCollectorSubmitData` with an object containing details about the transaction. At a minimum, include the transaction amount and currency (see [Supported data object properties](#section-supported-data-object-properties)). The transaction details contained in the object will be tokenized along with the shopper's sensitive payment details\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"document\\n  .getElementById('submitButton')\\n  .addEventListener('click', function () {\\n    const data = {\\n      amount: 10,\\n      currency: 'USD'\\n    };\\n    bluesnap.securedPaymentCollectorSubmitData(data);\\n  });\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\nWhen the data submission attempt is completed, the callback you provided to BlueSnap in Step 4 will be called with the results. If the submission was successful (when `sdkResponse.code` is `1`), your callback will continue the form submission to your server, where you can [process the transaction](#section-using-the-token-to-process-payments) using the token.\n\n**Note:** After a successful data submission to BlueSnap, all data within the `input` fields containing a `data-bluesnap` attribute will be deleted to maintain the shopper's confidentiality.\n\n### Supported data object properties\nThe following table outlines the properties that can be included in your `data` object that you pass to `bluesnap.securedPaymentCollectorSubmitData`. \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Property\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Required\",\n    \"0-0\": \"`amount`\",\n    \"0-1\": \"Number\",\n    \"0-2\": \"**Required**\",\n    \"1-0\": \"`currency`\",\n    \"1-1\": \"String \\n\\nSee [Currency Codes](https://support.bluesnap.com/docs/currencies).\",\n    \"1-2\": \"**Required**\",\n    \"2-0\": \"`email`\",\n    \"2-1\": \"String\",\n    \"2-2\": \"Optional\",\n    \"4-0\": \"`billingFirstName`\",\n    \"4-1\": \"String\",\n    \"4-2\": \"Optional\",\n    \"5-0\": \"`billingLastName`\",\n    \"5-1\": \"String\",\n    \"5-2\": \"Optional\",\n    \"6-0\": \"`billingCountry`\",\n    \"6-1\": \"String \\n\\nSee [Country Codes](/docs/country-codes)\",\n    \"6-2\": \"Optional\",\n    \"7-0\": \"`billingState`\",\n    \"7-1\": \"String \\n\\nSee [State and Province Codes](/docs/state-and-province-codes)\",\n    \"7-2\": \"Optional\",\n    \"8-0\": \"`billingCity`\",\n    \"8-1\": \"String\",\n    \"8-2\": \"Optional\",\n    \"9-0\": \"`billingAddress`\",\n    \"9-1\": \"String\",\n    \"9-2\": \"Optional\",\n    \"10-0\": \"`billingZip`\",\n    \"10-1\": \"String\",\n    \"10-2\": \"Optional\",\n    \"11-0\": \"`shippingFirstName`\",\n    \"11-1\": \"String\",\n    \"11-2\": \"Optional\",\n    \"12-0\": \"`shippingLastName`\",\n    \"12-1\": \"String\",\n    \"12-2\": \"Optional\",\n    \"13-0\": \"`shippingCountry`\",\n    \"13-1\": \"String \\n\\nSee [Country Codes](/docs/country-codes)\",\n    \"13-2\": \"Optional\",\n    \"14-0\": \"`shippingState`\",\n    \"14-1\": \"String \\n\\nSee [State and Province Codes](/docs/state-and-province-codes)\",\n    \"14-2\": \"Optional\",\n    \"15-0\": \"`shippingCity`\",\n    \"15-1\": \"String\",\n    \"15-2\": \"Optional\",\n    \"16-0\": \"`shippingAddress`\",\n    \"16-1\": \"String\",\n    \"16-2\": \"Optional\",\n    \"17-0\": \"`shippingZip`\",\n    \"17-1\": \"String\",\n    \"17-2\": \"Optional\",\n    \"3-0\": \"`phone`\",\n    \"3-1\": \"String\",\n    \"3-2\": \"Optional\"\n  },\n  \"cols\": 3,\n  \"rows\": 18\n}\n[/block]\n## Updating an expired token\nTo allow BlueSnap to handle token expiration, provide a function that obtains a new token from your server. BlueSnap will automatically call your function when an expired token is detected, preventing an error from occurring. Prior to calling `bluesnap.securedPaymentCollectorSetup`, call `bluesnap.setTokenProvider` with your function. Your function should contact your server to get the token, and then your function should call the provided callback with it.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Run before calling bluesnap.securedPaymentCollectorSetup\\nbluesnap.setTokenProvider((callback) => {\\n  // 1. Get a new token from your server\\n  fetch('/token')\\n    .then((response) => response.json())\\n    .then((data) => {\\n      // 2. Pass token to BlueSnap\\n      callback(data.token);\\n    })\\n    .catch((error) => {\\n      console.log(error);\\n      callback();\\n    });\\n});\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n## Using the token to process payments\nAfter submitting the shopper's data to BlueSnap, your callback from Step 4 will be triggered. If the data submission was successful, you can process the transaction by including the token in your API request. This must be done from your server and requires using your [API Credentials](/docs/api-credentials).\n\nTo process an ACH/ECP payment, send a [Create ECP Transaction](/v8976-JSON/docs/create-ecp-transaction) request. As part of the required properties, include `pfToken` in the request, with its value set to your token from Step 1.  \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/alt-transactions/ \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Accept: application/json' \\\\ \\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n{\\n  \\\"pfToken\\\": \\\"eba795a8ec2a8e7754afe7a69b0a0869fba0e6daec01e2d81e1ccbb6771c24ab_\\\",\\n  \\\"amount\\\": 100,\\n  \\\"currency\\\": \\\"USD\\\",\\n  \\\"payerInfo\\\": {\\n    \\\"zip\\\": \\\"12345\\\",\\n    \\\"firstName\\\": \\\"John\\\",\\n    \\\"lastName\\\": \\\"Doe\\\",\\n    \\\"phone\\\": \\\"1234567890\\\"\\n  },\\n  \\\"softDescriptor\\\": \\\"ABC COMPANY\\\",\\n  \\\"authorizedByShopper\\\": true\\n}'\",\n      \"language\": \"curl\",\n      \"name\": \"Create ACH/ECP Transaction - Request\"\n    }\n  ]\n}\n[/block]\nFor details on how to process card payments, refer to [Completing Tokenized Payments](/docs/completing-tokenized-payments).","updates":[],"order":0,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"60957f4cce403c0045a03237","createdAt":"2020-07-27T16:40:50.364Z","user":"5ea72d649148ff00653f6bbc","category":{"sync":{"isSync":false,"url":""},"pages":[],"title":"Secured Payment Collector","slug":"secured-payment-collector","order":14,"from_sync":false,"reference":false,"_id":"60957f4cce403c0045a031f2","createdAt":"2020-07-27T16:40:40.187Z","version":"60957f4cce403c0045a03255","project":"57336fd5a6a9c40e00e13a0b","__v":0},"version":{"version":"8976-Tools","version_clean":"8976.0.0-Tools","codename":"3.38 Release","is_stable":false,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["60957f4cce403c0045a031e3","60957f4cce403c0045a031e4","60957f4cce403c0045a031e5","60957f4cce403c0045a031e6","60957f4cce403c0045a031e7","60957f4cce403c0045a031e8","60957f4cce403c0045a031e9","60957f4cce403c0045a031ea","60957f4cce403c0045a031eb","60957f4cce403c0045a031ec","60957f4cce403c0045a031ed","60957f4cce403c0045a031ee","5b34c737e0dca2000311de6a","60957f4cce403c0045a031ef","60957f4cce403c0045a031f0","60957f4cce403c0045a031f1","60957f4cce403c0045a031f2","60957f4cce403c0045a031f3","60957f4cce403c0045a031f4","60957f4cce403c0045a031f5"],"_id":"60957f4cce403c0045a03255","project":"57336fd5a6a9c40e00e13a0b","__v":0,"forked_from":"603fec227146110018e1daaf","createdAt":"2018-04-23T15:17:35.680Z","releaseDate":"2018-04-23T15:17:35.680Z"},"project":"57336fd5a6a9c40e00e13a0b","__v":0,"parentDoc":null}