Stax.js is Stax’s browser-side JavaScript library. It tokenizes and sends sensitive bank and card information directly from a user’s browser to Stax’s servers, keeping your software fully PCI compliant. When you tokenize a card, you securely store that card on file for future use.

Accepting a payment using a card is identical to tokenizing a card, but it will also take payment from the tokenized card. You can also include additional details within the call to take advantage of Level 2 processing.

Add Stax.js to your site

Add the following script tag to the head of your HTML file.

<script src="https://staxjs.staxpayments.com/staxjs-captcha.js"></script>

Initialize Stax.js

First, you must know your Web Payments Token (public key) within Stax Pay by navigating to Apps > API Keys.
Initialize your Stax.js instance with the StaxJs class using your website payments token, like in the examples below.

Note: Passing the number and CVV into the instance of staxjs generates the secure iframe around these two fields, keeping sensitive card information from touching your servers.

var staxjs = new StaxJs( "your_website_payments_token" , {
  number: {
    id: 'card-number',     // the html id of the div you want to contain the credit card number field
    placeholder: '0000 0000 0000 0000',    // the placeholder the field should contain
    style: 'height: 30px; width: 100%; font-size: 15px;',    // the style to apply to the field
    type: 'text'    // the input type (optional)
    format: 'prettyFormat'    // the formatting of the CC number (prettyFormat || plainFormat || maskedFormat)
  },
  cvv: {
    id: 'card-cvv',    // the html id of the div you want to contain the cvv field
    placeholder: 'CVV',    // the placeholder the field should contain
    style: 'height: 30px; width: 100%; font-size: 15px;',    // the style to apply to the field
    type: 'text'    // the input type (optional)
  }
});

Create a form to enter card information

Create a payment form to capture the card and CVV numbers and create a Tokenize button.

<form onsubmit="return false;">
  <div id="card-number" style="width:200px; height:30px;"></div>
  <div id="card-cvv" style="width:50px; height:30px;"></div>

  <button id="tokenizebutton">
    Pay
  </button>
</form>

Load the Data fields

Now that we’ve initialized our instance of StaxJs and made the elements that will contain the credit card fields, we can tell StaxJs to load in those credit card fields. The showCardForm function returns a Promise, which lets us handle the completion of the credit card fields loading in.

staxJs
.showCardForm()
.then((handler) => {
  console.log("form was loaded");
  // for quick testing, you can set a test number and test cvv here
  // handler.setTestPan("4111111111111111");
  // handler.setTestCvv("123");
})
.catch((err) => {
  console.log("there was an error loading the form: ", err);
});

Handling Form Completion

Stax.js has handlers available to check for field input validity. First, we will handle the card_form_uncomplete event, which means that the input within the fields is invalid.

merchant.on("card_form_uncomplete", (message) => {
  // the customer hasn't quite finished filling in the fields
  // or the input in the fields are invalid
  console.log(message);
  // activate pay button
  var tokenizeButton = document.querySelector("#tokenizebutton");
  tokenizeButton.disabled = true;
});

Next, we’ll handle the card_form_complete event, which means that the input within the fields is complete and valid.

merchant.on("card_form_complete", (message) => {
  // the customer has finished filling in the fields, and they're valid!
  // Nice!
  console.log(message);
  // activate pay button
  var tokenizeButton = document.querySelector("#tokenizebutton");
  tokenizeButton.disabled = false;
});

Form details

We have implemented the credit card fields and are getting ready to send in the payment, but we require some additional fields to send to the request to tokenize. An object called extraDetails includes, at a minimum, the required fields for creating a tokenized credit card with Stax.js

Field Name	Description	Required
customer_id	It must be a string matching a valid customer_id in your merchant account. If supplied, a new customer will not be created or matched based on values. Instead, the supplied ID will be assigned this new payment method and transaction. If a customer_id is supplied, certain customer fields, such as firstname, lastname, phone, all address fields, etc., will be ignored.	No
firstname	max of 50 characters	Yes
lastname	max of 50 characters	Yes
phone	must be at least ten characters	No
email	must be a valid email. Receipts will be sent here automatically if the `send_receipt` flag is set to `true`.	No
adddress_1	max of 255 characters. This field is required for AVS if the account is configured to perform an AVS check on the street address. Required if customer_id is not passed into details	No*
address_2	max of 255 characters	No
address_city	Required if customer_id is not passed into details, max of 255 characters	No*
address_state	Required if customer_id is not passed into details, max of 2 characters (e.g. FL)	No*
address_country	- character country code (e.g. USA)	No
address_zip	It is not required unless AVS is configured to perform an AVS check on the zip code.	No*
company	String	No
method	“card” or “bank”	Yes
month	A string representing the 2-digit month when the card expires(“05”)	Yes*
year	A string representing the 4-digit year when the card expires (“2020”)	Yes*
match_customer	Boolean. This determines whether or not Stax.js matches the customer to an existing customer based on some combination of the same data sent into the JS request. See the Best Practices: Customer matching section for more details.	No
validate	Determines whether or not Stax.js does client-side validation.	No

example of extraDetails

const extraDetails = {
  firstname: "John",
  lastname: "Doe",
  method: "card",
  month: "10",
  year: "2020",
  phone: "5555555555",
  address_1: "100 S Orange Ave",
  address_2: "Suite 400",
  address_city: "Orlando",
  address_state: "FL",
  address_zip: "32811",
  address_country: "USA",
  validate: false,
  match_customer: false
};

Call the tokenize() method with extraDetails

document.querySelector("#tokenizebutton").onclick = () => {
  staxjs
    .tokenize(extraDetails)
    .then((response) => {
      console.log("payment method object:", response);
      console.log("customer object:", response.customer);
    })
    .catch((err) => {
      console.log("unsuccessful tokenization:", err);
    });
};

Response

A successful call to the Stax.js tokenize() method will create a tokenized payment method tied to a new or existing customer. If you already had a customer_id and passed it into the request, you already understand that customer. Still, if you are letting Stax.js create a new customer for you when calling tokenize(), you can retrieve the customer_id from the response and, if applicable, correlate it with the customer in your application.

Example Response(payment method object):

{
  address_1: "100 S Orange Ave";
  address_2: null;
  address_city: "Orlando";
  address_country: "USA";
  address_state: "FL";
  address_zip: "32811";
  bank_holder_type: null;
  bank_name: null;
  bank_type: null;
  card_exp: "112020";
  card_exp_datetime: "2020-11-30 23:59:59";
  card_last_four: "1111";
  card_type: "visa";
  created_at: "2020-07-06 16:22:16";
  customer: {
    address_1: "100 S Orange Ave";
    address_2: "";
    address_city: "Orlando";
    address_country: "USA";
    address_state: "FL";
    address_zip: "32811";
    allow_invoice_credit_card_payments: true;
    cc_emails: null;
    cc_sms: null;
    company: "";
    created_at: "2020-07-06 16:22:16";
    deleted_at: null;
    email: "";
    firstname: "Jon";
    gravatar: false;
    id: "cd10fbd4-199c-4753-8db8-66c4e2c2b4e8";
    lastname: "Doe";
    notes: null;
    options: null;
    phone: "111111111111111";
    reference: "";
    updated_at: "2020-07-06 16:22:16";
  }
  customer_id: "cd10fbd4-199c-4753-8db8-66c4e2c2b4e8";
  has_cvv: true;
  id: "2e34394f-5f1d-4ec0-a56d-f669509a5b13"; // payment_method_id
  is_default: 0;
  is_usable_in_vt: true;
  method: "card";
  nickname: "VISA: Jon Doe (ending in: 1111)";
  person_name: "Jon Doe";
  updated_at: "2020-07-06 16:22:16";
}