Integrating Hosted Fields

Overview

Hosted Fields is a solution that allows you to securely capture card and bank account details through a customisable UI while being PCI compliant. To achieve this, our Hosted Fields product uses Javascript iframes to display our hosted input fields on your page, including fields for capturing card accounts and bank accounts.

Card fields:

Cardholder name
Card number
Card expiration date
Card CVV/CVC

Bank account fields:

Account name
Routing number / BSB / SWIFT code
Account number

Features

PCI SAQ-A Compliance

Capturing card data using the Hosted Fields product will mean data is securely sent to Zai with minimal PCI compliance impact. When used properly, your servers will not be exposed to sensitive card information. Using this solution should assist you in obtaining a PCI SAQ-A compliance level.

Supported Cards

Hosted Fields currently support VISA, Mastercard and American Express cards.

Customised style and layout

Hosted Fields will give you full control to customise the style and layout of the UI following your specific brand guidelines.

Client-side control of validation result

As the user types, we will perform field validation. You will then have control on what to do with the validation result such as displaying an error message, customise wording, decide location of messsage display and styling of the message.

Formatting of user input

Formatting of fields as the user types to make the entered text more readable

Responsive design

Hosted Fields is responsive to your user's screen or mobile device

Accessibility

Hosted Fields is accessible by default and adheres to W3C Accessibility standards.

Supported Browsers

Chrome - last two versions
Firefox - last two versions
Safari - last two versions
Edge - last two versions
Internet Explorer 11

Whilst it will work in more browsers than those mentioned above, these are the versions we actively test.

Getting Started

Step 1: Generate Auth Token

A card or bank account auth token is used to authorise the passing of details through the client-side libraries. The generating of the card auth token occurs on the server-side.

To generate the auth token, use: Generate Token.

Step 2: Create HTML form

Create a standard HTML form. Define <div> container elements for your hosted fields, where you would usually use <input> fields.

<form>
  <label for="card-name-field">Card Holder Name</label>
  <div id="card-name-field" class="hosted-field"></div>

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

  <label for="card-expiry-field">Expiry Date</label>
  <div id="card-expiry-field" class="hosted-field"></div>
 
  <label for="card-cvv-field">CVV</label>
  <div id="card-cvv-field" class="hosted-field"></div>
	
  <button>Submit</button>
</form>

Step 3: Load Assembly.js

Add the following script to your page. To remain PCI compliant, ensure that you always load this script from our server. Do not add the script to your bundle or host it yourself.

<script src="https://hosted-fields.assemblypay.com/assembly.js"></script>

Step 4: Initialise Hosted Fields

Initialise the Hosted Fields library and configure the field types you want to include. See the library reference for complete configuration options.

Add a form submit handler that invokes the createCardAccount or createBankAccount method, depending on your form type. These methods will securely send a request to our server to create the account based on the data provided by the user. The method will return a success or error response for you to handle accordingly.

// Define your input styles (optional)
var styles = {
  input: {
    color: '#111827',
    'font-family': 'system-ui, -apple-system, BlinkMacSystemFont',
  },
  '.invalid': {
    color: '#cc0001',
  },
  '::placeholder': {
    color: '#757575',
  },
  '.invalid .card-icon': {
    color: '#cc0001',
  },
};

// Create hosted fields
var hostedFields = assembly.hostedFields({
  environment: 'pre-live'
});
var cardName = hostedFields.create('cardName', { styles });
var cardNumber = hostedFields.create('cardNumber', { styles });
var cardExpiry = hostedFields.create('cardExpiry', { placeholder: 'MM/YY', styles });
var cardCvv = hostedFields.create('cardCvv', { styles });

cardName.mount('#card-name-field');
cardNumber.mount('#card-number-field');
cardExpiry.mount('#card-expiry-field');
cardCvv.mount('#card-cvv-field');

// Handle form submit
var form = document.querySelector('form');

form.addEventListener('submit', function (event) {
  event.preventDefault();

  hostedFields
    .createCardAccount({
      token: 'ASSEMEBLY_TOKEN',
      user_id: 'ASSEMBLY_USER_ID',
    })
    .then((response) => {
      // handle create card account succeeded
      console.log(response)
    })
    .catch((response) => {
      // handle errors
      console.log(response)
    });
});