BLOX - Card tokenization SDK

BLOX offers a robust and secure way to handle online payments by generating payment card tokens via secure iframes. Designed to simplify the often complicated task of payment processing, the SDK embeds secure iframes into your checkout pages, allowing for PCI-compliant collection of payment card details.

Key Features:

Secure Iframes: Creates isolated environments to safely collect payment card details, ensuring data security.
Payment Card Tokenization: Generates a secure token and an encrypted CVV based on the user's card details. This token and the encrypted CVV can then be used to make actual payments, eliminating the need to store sensitive information.
PCI Compliance: Meet PCI DSS requirements by using secure iframes, reducing your scope of compliance.

By using BLOX, developers can enhance security and user experience, while also expediting the development process of the payment functionality in e-commerce applications.

Embedding the card tokenization SDK

The steps for embedding the card tokenization SDK in your checkout page are the following:

Login into your BridgerPay dashboard , create a blox checkout in the Checkouts section and activate the checkout to generate the API credentials.
Get authorized as a merchant.
Create a server session to generate a blox session token (cashier_token).

POST https://api.bridgerpay.com/v2/cashier/session/create/{api_key}
Content-Type: application/json
Authorization: Bearer {{ACCESS_TOKEN}}
{
  "cashier_key": "{cashier_key}",
  "order_id" : "12113123",
  "customer_id": "1988", // optional field
  "email": "[email protected]",
  "type" : "single_use" //Optional - Choose either multi_use or single_use
}

Embed the card tokenization SDK script.

<body>
  <script src="https://checkout.bridgerpay.com/sdk"></script>
</body>

Create a form with four inputs: cardholder name, credit card number, expiration date, and CVV. Add an optional checkbox for 'Save Card'.

<body>
 <div class="checkout-page">
  <form id="payment-form">
    <div class="field">
      <label>Card Holder Name</label>
      <div>
        <input class="input" id="cardholder-name" placeholder="John Doe" />
      </div>
    </div>

    <div id="card-number" class="field">
      <label>Card Number</label>
      <div class="input"></div>
    </div>

    <div class="field-set">
      <div id="exp-date" class="field">
        <label>Expiration Date</label>
        <div class="input"></div>
      </div>

      <div id="cvv" class="field">
        <label>CVV</label>
        <div class="input"></div>
      </div>
    </div>

    <div id="saveCard" class="field">
      <label><input type="checkbox" />Save Card</label>
    </div>

    <button type="submit" id="pay_button">Pay now</button>
  </form>
  <script src="https://checkout.bridgerpay.com/sdk"></script>
  <script src="index.js"></script> // BLOX JavaScript reference
</body>

📘
If 'Save Card' checkbox is missing: Token is single-use by default. If multi-use token is needed without user's consent, false value should be explicitly provided on the index.js. (singleUse: false,)
If 'Save Card' is checked: Token can be used multiple times; user agrees to save card info securely.
If 'Save Card' is unchecked: Token is single-use; user doesn't want to save card for later.

BLOX JavaScript reference

Call new BP.BloxController(options) to kick off card tokenization. Pass in the session token you got from your backend via the server session endpoint for auth. You can also add custom fonts and global styles to your blox instances via the options param.

const bloxController = new BP.BloxController({
  token: '99346d84-5187-4221-9c16-dc51a8de27fa',
  fontsSources: ['https://fonts.googleapis.com/css?family=Poppins:wght@100;300;400;500;600;700'],
  style: {
    base: {
      font: "16px/1.2 'Poppins', 'Arial', 'Helvetica Neue', 'Helvetica', sans-serif",
      color: '#4e5664',
      ':focus': {
        color: '#0f213c',
      },
    },
    invalid: {
      color: '#ff6666',
    },
  },
});

Create a secure blox instance by calling bloxController.createBlox(bloxType, options?). Specify the field type and any optional settings. Then, add the blox instances to the DOM.

const cardNumber = bloxController.createBlox('cardNumber', {
  placeholder: '0000 0000 0000 0000',
  style: {
    base: {
      color: 'black',
    },
  },
});

cardNumber.on(
  'change', 
  ({ error }) => error ? console.error('cardNumber', error) : console.log('cardNumber is Valid')
);

cardNumber.on(
  'validate', 
  ({ error }) => error ? console.error('cardNumber', error) : console.log('cardNumber is Valid')
);

const cardExpiryDate = bloxController.createBlox('cardExpiryDate', {
  placeholder: 'MM / YY',
});

cardExpiryDate.on(
  'change', 
  ({ error }) => error ? console.error('cardExpiryDate', error) : console.log('cardExpiryDate is Valid')
);

cardExpiryDate.on(
  'validate', 
  ({ error }) => error ? console.error('cardExpiryDate', error) : console.log('cardExpiryDate is Valid')
);

const cardCvv = bloxController.createBlox('cardCvv', {
  placeholder: '---',
});

cardCvv.on(
  'change', 
  ({ error }) => error ? console.error('cardCvv', error) : console.log('cardCvv is Valid')
);

cardCvv.on(
  'validate', 
  ({ error }) => error ? console.error('cardCvv', error) : console.log('cardCvv is Valid')
);

await Promise.all([
  cardNumber.mount('#card-number .input'),
  cardExpiryDate.mount('#exp-date .input'),
  cardCvv.mount('#cvv .input'),
]);

Create a payment card token by calling bloxController.createPaymentCardToken(options) when the form is submitted. Make sure the cardholder's name is filled out; it's a required field and can't be skipped.

document.getElementById('payment-form').addEventListener('submit', async (event) => {
  event.preventDefault();

  if (bloxController.isAllValid === false) {
    bloxController.validateAll();
    return;
  }
  
  try {
    const result = await bloxController.createPaymentCardToken({
      cardHolderName: document.getElementById('cardholder-name').value, // This field is mandatory
      singleUse: !document.querySelector('#saveCard input').checked,
    });

    console.log(`The response is`, result);
  } catch (error) {
    console.error(error);
  }
});

Let's piece it all together:

<body>
  <div class="checkout-page">
    <form id="payment-form">
      <div class="field">
        <label>Name</label>
        <div>
          <input class="input" id="cardholder-name" placeholder="John Doe" />
        </div>
      </div>

      <div id="card-number" class="field">
        <label>Card Number</label>
        <div class="input"></div>
      </div>

      <div class="field-set">
        <div id="exp-date" class="field">
          <label>Expiration Date</label>
          <div class="input"></div>
        </div>

        <div id="cvv" class="field">
          <label>CVV</label>
          <div class="input"></div>
        </div>
      </div>

      <div id="saveCard" class="field">
        <label><input type="checkbox" /> Save Card</label>
      </div>

      <button type="submit" id="pay_button">Pay $25</button>
    </form>
  </div>
  <script src="https://checkout.bridgerpay.com/sdk"></script>
  <script src="index.js"></script>
</body>

run();

async function run() {
  const bloxController = new BP.BloxController({
    token: '99346d84-5187-4221-9c16-dc51a8de27fa',
    fontsSources: ['https://fonts.googleapis.com/css?family=Poppins:wght@100;300;400;500;600;700'],
    style: {
      base: {
        font: "16px/1.2 'Poppins', 'Arial', 'Helvetica Neue', 'Helvetica', sans-serif",
        color: '#4e5664',
        ':focus': {
          color: '#0f213c',
        },
      },
      invalid: {
        color: '#ff6666',
      },
    },
  });

  const cardNumber = bloxController.createBlox('cardNumber', {
    placeholder: '0000 0000 0000 0000',
    style: {
      base: {
        color: 'black',
      },
    },
  });

  cardNumber.on(
    'change', 
    ({ error }) => error ? console.error('cardNumber', error) : console.log('cardNumber is Valid')
  );

  cardNumber.on(
    'validate', 
    ({ error }) => error ? console.error('cardNumber', error) : console.log('cardNumber is Valid')
  );

  const cardExpiryDate = bloxController.createBlox('cardExpiryDate', {
    placeholder: 'MM / YY',
  });

  cardExpiryDate.on(
    'change', 
    ({ error }) => error ? console.error('cardExpiryDate', error) : console.log('cardExpiryDate is Valid')
  );

  cardExpiryDate.on(
    'validate', 
    ({ error }) => error ? console.error('cardExpiryDate', error) : console.log('cardExpiryDate is Valid')
  );

  const cardCvv = bloxController.createBlox('cardCvv', {
    placeholder: '---',
    unmaskedCVV: false
  });

  cardCvv.on(
    'change', 
    ({ error }) => error ? console.error('cardCvv', error) : console.log('cardCvv is Valid')
  );
  
  cardCvv.on(
    'validate', 
    ({ error }) => error ? console.error('cardCvv', error) : console.log('cardCvv is Valid')
  );
  
  await Promise.all([
    cardNumber.mount('#card-number .input'),
    cardExpiryDate.mount('#exp-date .input'),
    cardCvv.mount('#cvv .input'),
  ]);

  document.getElementById('payment-form').addEventListener('submit', async (event) => {
    event.preventDefault();
    
    if (bloxController.isAllValid === false) {
      bloxController.validateAll();
      return;
    }
    
    try {
      const result = await bloxController.createPaymentCardToken({
        cardHolderName: document.getElementById('cardholder-name').value, // This field is mandatory
        singleUse: !document.querySelector('#saveCard input').checked,
      });

      console.log(`The response is`, result);
    } catch (error) {
      console.error(error);
    }
  });
}

Styling the secure blox instances

You can style secure blox instances in two ways. First, set individual styles when calling bloxController.createBlox(bloxType,options?). Second, set global styles in new BP.BloxController(options). These styles can adapt based on input element states like valid, empty, or invalid.

Applying styles

Jump to the style objects reference

The style object has nested objects for different input states like valid input, no input, and invalid input. The base object sets foundational styles inherited by other nested objects. For example, a base object sets default styles, while an invalid object sets styles for invalid inputs. For example:

const cardNumber = bloxController.createBlox('cardNumber', {
  style: {
    base: {
      color: '#fff',
      fontWeight: 600,
      fontFamily: 'Quicksand, Open Sans, Segoe UI, sans-serif',
      fontSize: '16px',
      fontSmoothing: 'antialiased',
    },
    invalid: {
      color: '#FF0000',
    },
  },
});

You can also use pseudo-classes and pseudo-elements for more precise control over input element styling:

const cardNumber = bloxController.createBlox('cardNumber', {
  style: {
    base: {
      color: '#fff',
      fontWeight: 600,
      fontFamily: 'Quicksand, Open Sans, Segoe UI, sans-serif',
      fontSize: '16px',
      fontSmoothing: 'antialiased',
      ':focus': {
        color: '#424770',
      },
      '::placeholder': {
        color: '#9BACC8',
      },
      ':focus::placeholder': {
        color: '#CFD7DF',
      },
    },
    invalid: {
      color: '#FF0000',
      ':focus': {
        color: '#FA755A',
      },
      '::placeholder': {
        color: '#FFCCA5',
      },
    },
  },
});