Dibsy.JS

Philosophy

Dibsy.JS is part of the Dibsy Component family, which allows you to securely collect sensitive data from your customer without needing to pass through your systems. While securing access to the data, you can fully control the look and feel of the input fields. At a high level, it works by using a Javascript API to add fields in a way that is fully PCI-DSS compliant. Moreover, we’re constantly extending Dibsy.JS functionality to bring additional value to our customers.

Advantages

• PCI Compliant
• Support for 3D Secure verification
• Fully customisable styles
• Input validation
• Card Brand Identification
• Mobile-friendly inputs
• Fast integration

Browser compatibility

• Chrome latest
• Firefox latest
• Safari 10+
• Edge

Simple flow

1. Import and add the Dibsy Javascript library to your checkout and initialise the Dibsy object with your public key.
2. Create and mount the four credit card fields (card holder, card number, expiry date, and CVC). This will inject the fields to your checkout.
3. Add a submit event listener to your form, to encrypt the card information into cardToken when your customer submits the checkout form.
4. From your server-side application, call the Create Payment API, along with the cardToken as a parameter.
5. Redirect your customer to the 3-D Secure Authentication link returned in the response. Once your customer completes the authentication, you receive a webhook notification and the customer is redirected back to your website.

Add Dibsy.JS to your checkout.

Start by adding the Javascript file that is located at cdn.dibsy.one/js/dibsy-2.0.0.js to your application.

<script src="https://cdn.dibsy.one/js/dibsy-2.0.0.js"></script>

Please note: If you are using Content Security Policy, you should whitelist the cdn.dibsy.one domain.

Initialise the Dibsy instance

Once the script has loaded, use the initialise an instance of the Dibsy object by providing your Dibsy publicKey found under API keys on your Dashboard along with the locale.

const dibsy = await Dibsy("pk_test_d70V5Wsqu263AdY4gsgrgWGMZqMRmy0BbNmi", { locale: "en_US" });

Inject Checkout Fields

After you have initialised the Dibsy object, create the four checkout field components using the dibsy.createComponent(type[, options]) function and mount them in your checkout form using the component.mount(targetElement) function.

Error handling

Dibsy.JS also provide additional functionality that allows you to handle errors if cardholder inputs illegal values, such as incorrect digits of the card number. To make use of these, add a change event listener to each component to listen for errors and display them. Errors will be localized according to the locale defined when initializing Dibsy.JS.

Example

<!--Your Checkout Form-->
<form>

  <div id="card-holder"></div>
  <div id="card-holder-error"></div>  

  <div id="card-number"></div>
  <div id="card-number-error"></div>   
  
  <div id="expiry-date"></div>
  <div id="expiry-date-error"></div>  
  
  <div id="verification-code"></div>
  <div id="verification-code-error"></div>  
  
  <button id="payment-button" type="submit">Pay</button>
</form>

// Your Script
  var cardNumber = dibsy.createComponent("cardNumber", options);
  cardNumber.mount("#card-number");

  var cardHolder = dibsy.createComponent("cardHolder", options);
  cardHolder.mount("#card-holder");

  var expiryDate = dibsy.createComponent("expiryDate", options);
  expiryDate.mount("#expiry-date");

  var verificationCode = dibsy.createComponent("verificationCode", options);
  verificationCode.mount("#verification-code");

  // Error Handling
  var cardNumberError = document.getElementById("card-number-error");
  cardNumber.addEventListener("change", function (event) {
    if (event.error && event.touched) {
      cardNumberError.textContent = event.error;
    } else {
      cardNumberError.textContent = "";
    }
  });

Submit checkout

Add a submit event listener to your form and use the dibsy.cardToken() function to retrieve the token.

form.addEventListener('submit', async e => {
  e.preventDefault();

  const { token, error } = await dibsy.cardToken();

  if (error) {
    // Error while retrieving the token.
    return;
  }

  // Submit form to the server
  form.submit();
});

Create a payment and redirect your customer to the 3-D Secure authentication page

Create a payment with the method parameter set to creditcard and cardToken parameter set to the token you generated. The cardToken is only valid for 15 minutes. You must then redirect your customer to the URL in _links.checkout object in the response returned by the API.

Styling and Customisation

Component Customisation

You can customise the components you have created and style them to match your UI.

There are 3 types of styling you can use.

1. Target element styling - This is your div element where the Dibsy components are mounted. You have complete control over styling here.
2. Component container - This is the injected component container whose classes are exposed for you to customize.
3. Input fields - Input fields itself can’t be styled from outside the iFrame because iFrames will block CSS inheritance.

Component container

The styling applied to <div class="dibsy-component" /> container applies to all your fields. You can use this class to style border and background properties.

.dibsy-component {
  background: #fff;
  box-shadow: 0px 1px 0px rgb(0 0 0 / 10%), 0px 2px 4px rgb(0 0 0 / 10%),
    0px 4px 8px rgb(0 0 0 / 5%);
  border-radius: 4px;
  padding: 13px;
  border: 1px solid transparent;
  transition: 0.15s border-color cubic-bezier(0.4, 0, 0.2, 1);
  font-weight: 500;
}

Dynamic classes

Additional classes based on the state of user interaction. This allows you to inject styles as your user interact with it. For example, use .dibsy-component.is-invalid class to give feedback to the user to try again.

/* Adds styles when the field receives focus for the first time. */

.dibsy-component.is-touched {
  border-color: #0077ff;
  transition: 0.3s border-color cubic-bezier(0.4, 0, 0.2, 1);
}

/* Adds styles when the fields receive focus and removed when the fields have lost focus */

.dibsy-component.has-focus {
  border-color: #0077ff;
  transition: 0.3s border-color cubic-bezier(0.4, 0, 0.2, 1);
}

/* Adds styles when the input values in the field are legal  */

.dibsy-component.is-invalid {
  border-color: #ff1717;
  transition: 0.3s border-color cubic-bezier(0.4, 0, 0.2, 1);
}

/* Adds styles when the input values in the field are illegal */

.dibsy-component.is-valid {
  border-color: green;
  transition: 0.3s border-color cubic-bezier(0.4, 0, 0.2, 1);
}

Input fields

Text styling properties in the checkout fields can’t be styled from outside the iFrame because iframes will block CSS inheritance. However, these properties can be applied when creating components. You can target different states of the component when applying them:

• base - The state when the user has not entered any data yet.
• valid - The state when the user has entered legal values.
• invalid - The state when the user has entered illegal values.

Properties you can customize:

Field	Data Type
backgroundColor	color
color	color
fontSize	number
fontWeight	string or number
letterSpacing	number
lineHeight	number
textAlign	string
textDecoration	string
textTransform	string

  const options = {
    styles: {
      base: {
        color: 'rgba(0, 0, 0, 0.8)',
      }
    }
  }
  const cardNumber = dibsy.createComponent("cardNumber", options);