In today's world, security and PCI compliance play important roles in protecting cardholders and delivering cash flow for businesses.

Protect.js uses an iframe to create PayTrace hosted fields when collecting sensitive-payment information. This allows you to control the UI and UX of your checkout process so that cardholder data never touches your servers.

You can quickly start accepting secure payments and storing cardholders' payment information by embedding a few lines of code within your existing checkout flow. While achieving the highest level of PCI-Compliance, SAQ-A.

The benefits of using PayTrace Protect.js

• It will allow your customers to process transactions on your website.
• It will allow your customers to safely and securely store their credit card information for future use.
• Your customers are not required to be redirected to another payment page.
• It provides your customers the comfort and security of processing payments on your website.
• Using Protect.js reduces your PCI scope and can help you qualify for PCI SAQ-A.

The PayTrace Protect.js Workflow

Protect.js Details

Protect.js places PayTrace Hosted Payment fields, within an iframe, on your webform. This will allow your customers to enter their sensitive credit card information directly into PayTrace while ensuring your server does not handle any sensitive data. Once this information has been captured, Protect.js will then return a one time use hpf_token (nonce) and enc_key. The nonce and enc_key can then be submitted via an API request in order to process transactions or create customer profiles.

How to incorporate Protect.js in a web form

The following steps are required to utilize The PayTrace Protect.js Library in a web form.

Our examples make use of Promises and Arrow Functions which are not
supported by IE11. For integrators wishing to support IE11, you will
need to use Callback Functions and methods. For assistance, please
contact DeveloperSupport@PayTrace.com

1. Setup: Include JS library and div container tag for iframe on your website.

<!-- This is the PayTrace Protect.js library: -->
<script src='https://protect.paytrace.com/js/protect.min.js'></script>

<!-- This is the PayTrace Sandbox Protect.js library: -->
<script src='https://protect.sandbox.paytrace.com/js/protect.min.js'></script>

<!-- The JS Library then adds the iframe using this div container tag during setup -->
<div id='pt_hpf_form'><!--iframe sensitive data payment fields inserted here--></div>

This step allows the PTPayment object to become available when the Protect library script is sourced in the web application. See available PTPayment methods below:

2. Get authorization for application to use JSON API

Make OAuth authorization call to the JSON API to get an API AUTH TOKEN. This token will be used as the authorization bearer access token to authorize the application to use PayTrace's API. The token should be kept secret and should never be added to client side code. This token is valid for 2 hours.

grant_type=client_credentials&client_id=YourUserName&client_secret=YourPassword

3. Use the JSON API Authorization token to get authorization to use Protect

Using the API AUTH TOKEN from step two as the authorization header, make a JSON API POST request to: https://api.paytrace.com/v3/payment-fields/token to get a PROTECT AUTH TOKEN (clientKey).

POST
URL='https://api.paytrace.com/v3/payment-fields/token'
Content-Type: application/json
Authorization: Bearer "Auth Token in Step 2"

The clientkey will be used to authorize the application to use Protect.js. This key is valid for 20 minutes.

4. Use the Protect authorization token to setup the payment form.

Ensure you have the following setup code:

<script>
// Minimal Protect.js setup call
PTPayment.setup({
  authorization: { clientKey: <clientKey> }
}).then(function(instance){
//use instance object to process and tokenize sensitive data payment fields.
});
</script>

By this point, you should be able to see the Protect.js iframe rendered on your webpage. See example below:

To improve the look and feel of Protect.js, styling options can be statically applied during the setup call. For more information regarding our Styling option, see Protect.js Styling.

5. Bind submit event to event handler for tokenization of sensitive data

The process method will tokenize the sensitive data in the payment fields. The method returns a http promise that will either be fulfilled (resolved) or rejected. If it is rejected, the possible reasons are: network error, internal error, or the fields did not pass validation.

5.1 Validate fields before tokenizing sensitive data.

Step 5.1: Bind Submit event and validate fields before tokenizing sensitive data.

// this can be any event we chose. We will use the submit event and stop
// any default event handling and prevent event handling bubbling.
document.getElementById("ProtectForm").addEventListener("submit",function(e){
 e.preventDefault();
 e.stopPropagation();

// To trigger the validation of sensitive data payment fields within
// the iframe before calling the tokenization process:
PTPayment.validate(function(validationErrors) {
 if (validationErrors.length >= 1) {
  if (validationErrors[0]['responseCode'] == '35') {
   // Handle validation Errors here
   // This is an example of using dynamic styling to show the Credit card
   // number entered is invalid
   PTPayment.style({'cc': {'border_color': 'red'}});
  }
 } else {
   // no error so tokenize
   instance.process()
   .then( (r) => submitPayment(r) )
   .catch( (err) => handleError(err) );
 }
});// end of PTPayment.validate
});// end of add event listener submit

PTPayment.validate will validate the payment fields and allow you to re-prompt your customers to enter valid information.

Dynamic styling can then be used to better control your customer experience when invalid input is entered. For more information regarding our Styling options, see Styling Options.

For a list of potential validation errors, see Validation Error Responses below.

OR

5.2 Directly Tokenize sensitive data

OR

Step 5.2: Bind Submit event and directly tokenize sensitive data.

// this can be any event we chose. We will use the submit event and
// stop any default event handling and prevent event handling bubbling.
document.getElementById("ProtectForm").addEventListener("submit",function(e){
 e.preventDefault();
 e.stopPropagation();

// The tokenization process also validates the sensitive data payment fields
  PTPayment.process() //call tokenization
  .then( (r) => submitPayment(r) )
   // submit nonce and cipher key to PayTrace Protect Servers to tokenize
   // sensitive data payment fields
  .catch( (err) => handleError(err) );
   // handle unsuccessful tokenization failures


});// end of add event listener submit

The tokenization process also validates the sensitive data payment fields.

Dynamic styling can then be used within the error handling to better control your customer experience when invalid input is entered. For more information regarding our Styling options, see Styling Options.

For a list of potential validation errors, see Validation Error Responses below.

Validation Error Responses

If for any reason the users input fails the Protect.js validation, the appropriate Response code will be returned in the error response.

How to submit Protect.js Tokens through the API

Once you have received the hpf_token (nonce) and enc_key, you will then submit these values using an API Request and the Oauth token from Step 2. API methods that are meant to be used with the Protect.js UI are listed within their appropriate request categories and begin with the keyword Protect.

Successful Protect.js tokenization response

{
  "success": true,
  "message": {
    "hpf_token": "f519084b-db08-4e82-8670-9e690d9897cc",
    "enc_key": "84jkunZs5Ae4_tNaW3QtIIjaE08wyg70oJfA-gtm6aY="
  }
}

Protect.js validation error response

{
	"message": "Field Validation Error(s)",
	"reason": [
      { "description": "Please provide a valid Credit Card Number.", "responseCode": "35" },
      { "description": "Please provide a valid Expiration Month.", "responseCode": "43" }
  ]
}