What is the Hosted Client SDK?

PowerBoard offers an extensively customisable client sdk that accepts all available payment methods, supports input validation, and built-in 3DS 2.0 capability.

• It is a solution for collecting and handling payment sources in a secure way.
• With the client SDK you can create a payment form widget as an independent part or use it directly inside your payment form.
• The SDK supports a number of methods for customising the widget to your websites needs (styling, form fields, etc)

👍

Getting started with the Client SDK

To work with the widget you will need public_key or access_token

Also you will need a gateway id from your connected services in PowerBoard.

Environments

<script src="https://widget.preproduction.powerboard.commbank.com.au/sdk/latest/widget.umd.min.js"></script> 
<script>
    var widget = new cba.HtmlWidget('#widget', 'PUBLIC_KEY', 'GATEWAY_ID');
    widget.setEnv("preproduction_cba");
    widget.load();
</script> 
<div id="widget"></div>

<script src="https://widget.powerboard.commbank.com.au/sdk/latest/widget.umd.min.js"></script> 
<script>
    var widget = new cba.HtmlWidget('#widget', 'PUBLIC_KEY', 'GATEWAY_ID');
    widget.setEnv("production_cba");
    widget.load();
</script> 
<div id="widget"></div>

Widget Customisation

📘

Please note that the steps and code samples are generalised, so you may need to adjust them to fit your application.

Widget Classes

setFormFields

Description

Set list with widget form field, which will be shown in form. Also, you can set the required validation for these fields.

widget.setFormFields(['phone',
    'email',
    'first_name*',
    'last_name',
    'phone2',
    'address_line1',
    'address_line1',
    'address_line2',
    'address_state',
    'address_country',
    'address_city',
    'address_postcode',
    'address_company'
]);

Configurable Parameters

Preview

setFormElements

Description

Allows merchants to set and configure Widget Form elements, including:

• visibility
• required
• label
• placeholder
• value

widget.setFormElements([
      {
          field:  'card_name*',
          placeholder: 'Input your card holder name...',
          label: 'Card Holder Name',
          value: 'Houston',
      },
      {
          field:  'email',
          placeholder: 'Input your email, like [email protected]',
          label: 'Email for the receipt',
          value: '[email protected]',
      },
  ])

Configurable Parameters

Preview

setStyles

Description

Allows to set and configure styling for the Widget

widget.setStyles({
      background_color: 'rgb(0, 0, 0)',
      border_color: 'yellow',
      text_color: '#FFFFAA',
      button_color: 'rgba(255, 255, 255, 0.9)',
      font_size: '20px',
      font_family: 'fantasy'
  });

Configurable Parameters

setTexts

Description

Method to set different texts within the widget.

• visibility
• required
• label
• placeholder
• value

widget.setTexts({
      title: 'Your card',
      finish_text: 'Payment resource was successfully accepted',
      title_description: '* indicates required field',
      submit_button: 'Save',
      submit_button_processing: 'Load...',
  });

Configurable Parameter

Preview

setElementStyle

Description

Method for setting customisation of the PowerBoard Widget elements and relevant states.

Element states are as follows:

• error
• focus
• hover

widget.setElementStyle('input', {
  border: 'green solid 1px'
});
 
widget.setElementStyle('input', 'focus', {
  border: 'blue solid 1px'
});
 
widget.setElementStyle('input', 'error', {
 border: 'red solid 1px'
});
 
widget.setElementStyle('input', 'hover', {
  border: 'blue solid 1px'
});

Configurable Parameter

Preview

setFormValues

Description

Method to set predefined values for the form fields inside the widget.

widget.setFormValues({
      email: '[email protected]',
      card_name: 'Houston'
  });

Configurable Parameters

Preview

setFormLables

Description

Method to set custom form field labels.

widget.setFormLabels({
      card_name: 'Card Holder Name ABC'
  })

Configurable Parameters

Preview

setFormPlaceholders

Description

Method to set custom form field labels.

widget.setFormPlaceholders({
      card_name: 'Input your card holder name...',
      email: 'Input your email, like [email protected]'
  })

Configurable Parameters

Preview

setHiddenElements

Description

Using this method, you can set hidden elements for the widget.

widget.setHiddenElements(['submit_button']);

Configurable Parameters

Preview

setRefId

Description

Method to set a custom reference when using the widget.

widget.setRefId('abc-1234567');

Configurable Parameters

Preview

{
    "event": "finish",
    "purpose": "payment_source",
    "message_source": "widget.paydock",
    "ref_id": "abc-1234567",
    "widget_id": "7ff7ff74-dedb-236d-0383-4d7afc8ad462",
    "payment_source": "27f2efcf-df0c-4d3e-b094-17d272c4ba97"
}

setSupportedCardIcons

Description

Sets icons of supported card types.

widget.setSupportedCardIcons(['mastercard', 'visa', 'amex']);

Configurable Parameters

Preview

validateCardNumberInput

Description

Validation extension will only enforce the supported cards listed prior and everything else will get a not supported prompt

widget.setSupportedCardIcons(['mastercard', 'visa'], validateCardNumberInput = true);

setWebHookDestination

Description

Destination where customer will receive all successful responses. Response will contain “data” object with “payment_source” or other parameters, in depending on 'purpose'

widget.setWebHookDestination('http://google.com');

Configurable Parameters

setSuccessRedirectUrl

Description

URL to which the Customer will be redirected to after the success finish

widget.setSuccessRedirectUrl('google.com/search?q=success');

Configurable Parameters

setErrorRedirectUrl

Description

URL to which the Customer will be redirected to if an error is triggered in the process of operation

widget.setErrorRedirectUrl('google.com/search?q=error');

Configurable Parameters

setFormFields

Description

Set list with widget form field, which will be shown in form. Also you can set the required validation for these fields

widget.setFormFields(['phone', 'email', 'first_name*']);

Configurable Parameters

load

Description

The final method to beginning, the load process of widget to html

on

Description

htmlWidget.on(eventName, [cb]) ⇒ Promise.<(IEventData|IEventMetaData|IEventFinishData|IFormValidation)> | void

Listen to events of widget.

widget.on('form_submit', function (data) {
     console.log(data);
});
// or
 widget.on('form_submit').then(function (data) {
     console.log(data);
});

Configurable Parameters

trigger

Description

This callback will be called for every specified trigger

Configurable Parameters

getValidationState

Description

This method will check the validation state of the form

Returns IFormValidation response

widget.getValidationState();

isValidForm

Description

This method will check if the form is valid

Returns Boolean - Form is valid

widget.isValidForm();

isInvalidForm

Description

Using this method you can check if a specific form field is invalid

Returns Boolean - Field is invalid

widget.isInvalidField(field);

Configurable Parameters

isInvalidFieldByValidator

Description

Using this method you can check if a specific field is invalid

Returns Boolean - Field is invalid

widget.isInvalidFieldByValidator(field, validator);

Configurable Parameters

hide

Description

Using this method you can hide the widget after load

widget.hide([saveSize = False]);

Configurable Parameters

show

Description

This method will show the widget after using hide

widget.show()

reload

Description

This method will reload the widget

widget.reload()

hideElements

Description

Use this method to hide any elements inside the widget

widget.hideElements(['submit_button', 'email']);

Configurable Parameters

interceptSubmitForm

Description

Widget will intercept submit of your form for processing widget

Process: click by submit button in your form --> submit widget ---> submit your form

Kind: instance method of HtmlWidget
Note: submit button in widget will be hidden.

<form id="myForm">
     <button type="submit">Submit</button>
 </form>
<!--
-->
<script>
    widget.interceptSubmitForm('#myForm');
</script>

showElements

Description

Use this method to show elements inside the widget

widget.showElements(['submit_button', 'email']);

Configurable Parameters

updateFormValues

Description

Method for updating values of the form fields within the widget

widget.updateFormValues({
      email: '[email protected]',
      card_name: 'Houston'
  });

Configurable Parameters

onFinishInsert

Description

After the finish event of the widget, data (dataType) will be inserted into the input (selector)

widget.onFinishInsert(selector, dataType);

Configurable Parameters

useAutoResize

Description

Use this method to resize the iFrame according to content height

widget.useAutoResize();

usePhoneCountryMask

Description

Method to set a country code mask for the phone input

widget.usePhoneCountryMask([options]);

Configurable Parameters

Events

List of available event names

Interfaces

IEventData

IEventMetaData

IEventFinishData

IFormValidation

Appendix A - Advanced Widget Customisation

Elements which can accept custom styling are as follows:

• input
• submit_button
• label
• title
• title_description

Please refer to https://developer.mozilla.org/en-US/docs/Web/CSS for further information on CSS properties.

Input Example

  widget.setElementStyle('input', {
        border: 'red solid 10px',
        border_radius: '30px'
    });

Submit Button Example

 widget.setElementStyle('submit_button', {
        border: 'green solid 10px',
        border_radius: '30px'
    });

Label Example

 widget.setElementStyle('label', {
        color: 'rebeccapurple'
    });

Title Example

 widget.setElementStyle('title', {
        text_decoration: 'underline'
    });

Title Description Example

 widget.setElementStyle('title_description', {
        font_size: '42px'
    });

Appendix B - Manual Submission Trigger

If you wish to manually submit the credit card form and not use the pre-rendered 'submit' button, please use the following:

widget.setHiddenElements(['submit_button']); // Hides Pre-Rendered Submit Button

widget.trigger('submit_form'); // Manually triggers form submission and generates One-Time-Token