@paydock/client-sdk v1.113.2

Client-sdk

It is a solution for collecting and handling payment sources in secure way.

With SDK you can create a payment form widget as an independent part or insert use inside your form.

The SDK supports methods for customization of widget by your needs (styling, form fields, etc)

Other information

To work with the widget you will need public_key or access_token (see Authentication)

Also you will need added gateway (see API Reference by gateway)

Get started

The Client SDK ships in JavaScript ES6 (EcmaScript 2015) in three different formats (CJS, ESM and UMD) along with respective TypeScript declarations. Below, we exemplify how to import each format.

With package manager

Our NPM package is compatible with all package managers (e.g., npm, yarn, pnpm, bun). Using npm the following command would add the Client SDK as a production dependency.

npm install @paydock/client-sdk

After installation is complete, if you are developing in NodeJS environments or using tools that expect your JavaScript code to be in CJS format (e.g., Jest, Karma, RequireJS, Webpack), you can import the Client SDK using CommonJS modules. For these environments the UMD format (@paydock/client-sdk/bundles/widget.umd.js) can also be used as a fallback. Alternatively, in case you are developing in projects that have access to modern bundlers such as Vite or others (e.g., SPA libs or SSR Metaframeworks), you can import the Client SDK features using ESM through named imports or namespaced imports.

// module import - CommonJS/Node projects ✅
const paydock = require('@paydock/client-sdk')
const api = new paydock.Api('publicKey');

// named import - ESM projects or TypeScript projects ✅
import { HtmlWidget } from '@paydock/client-sdk'
const widget = new HtmlWidget('#selector', 'publicKey', 'gatewayId');

// namespaced import - ESM projects or TypeScript projects ✅
import * as Paydock from '@paydock/client-sdk'
const widget = new Paydock.HtmlWidget('#selector', 'publicKey', 'gatewayId');

// default import - We do not provide default exports. They are handled differently by different tools!
 ❌
import paydock from '@paydock/client-sdk'
>>> "Uncaught SyntaxError: The requested module does not provide an export named 'default'"

Download from CDN

For browser environments, you can import the Client SDK directly from our CDN to your project's HTML. To accomplish this, include the Client SDK in your page using one and only of the two script tags below. After this step you will be able to access the Client SDK features via the global variable paydock.

For production we recommend using the compressed version (.min.js) since it will result in faster loading times for your end users.

• Compressed version for production: https://widget.paydock.com/sdk/latest/widget.umd.min.js

• Full version for development and debug: https://widget.paydock.com/sdk/latest/widget.umd.js

You may download the production version of the Client SDK scripts here, and, the development version here.

For more advanced use-cases, the library has UMD format that can be used in RequireJS, Webpack, etc.

<script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js"></script>
<script>
    var widget = new paydock.HtmlWidget('#tag', 'publicKey', 'gatewayId');
</script>

Widget

You can find description of all methods and parameters here

A payment form where it is possible to enter card data/bank accounts and then receive a one-time token for charges, subscriptions etc. This form can be customized, you can customize the fields and set styles. It is possible in real-time to monitor the actions of user with widget and get information about payment-source using events.

Widget simple example

Container

<div id="widget"></div>

You must create a container for the widget. Inside this tag, the widget will be initialized

Initialization

var widget = new paydock.HtmlWidget('#widget', 'publicKey');
widget.load();

// ES2015 | TypeScript

import { HtmlWidget } from '@paydock/client-sdk';

var widget = new HtmlWidget('#widget', 'publicKey');
widget.load();

Then write only need 2 lines of code in js to initialize widget

Full example

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <style>iframe {border: 0;width: 100%;height: 300px;}</style>
</head>
<body>
    <form id="paymentForm">
        <div id="widget"></div>
        <input name="payment_source_token" id="payment_source_token" type="hidden">
    </form>
    <script src="https://widget.paydock.com/sdk/latest/widget.umd.min.js" ></script>
    <script>
        var widget = new paydock.HtmlWidget('#widget', 'publicKey');
        widget.onFinishInsert('input[name="payment_source_token"]', 'payment_source');
        widget.load();
    </script>
</body>
</html>

Widget advanced example

Customization

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'
	});

This example shows how you can customize to your needs and design

Customization from html

<div id="widget"
	 widget-style="text-color: #FFFFAA; border-color: #yellow"
	 title="Payment form"
	 finish-text="Payment resource was successfully accepted"></div>

This example shows how you can set style and texts from html

Settings

widget.setRefId('id'); // your unique identifier to identify the data

widget.setFormFields(['phone', 'email']); // add additional fields for form of widget

widget.setSupportedCardIcons(['mastercard', 'visa']); // add icons of supported card types

This example shows how you can use a lot of other methods to settings your form

Full example

<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<title>Title</title>
	<style>iframe {border: 0;width: 100%;height: 400px;}</style>
</head>
<body>
<form id="paymentForm">
    <div id="widget"
        widget-style="text-color: #FFFFAA; border-color: #yellow"
        title="Payment form"
        finish-text="Payment resource was successfully accepted"></div>
</form>

<script src="https://widget.paydock.com/sdk/latest/widget.umd.js" ></script>
<script>
	var widget = new paydock.HtmlWidget('#widget', 'publicKey', 'gatewayId');

	widget.setSupportedCardIcons(['mastercard', 'visa']);
	widget.setFormFields(['phone', 'email']);
	widget.setRefId('custom-ref-id');
    widget.onFinishInsert('input[name="payment_source_token"]', 'payment_source');z

	widget.load();
</script>
</script>
</body>
</html>

Classes

Constants

Interfaces

IFormValidation

Interface of data from validation event.

Kind: global interface

IEventMetaData

Contains basic information associated with the event and additional meta data specific to the event. E.g., card info, gateway info, etc.

Kind: global interface

IEventAfterLoadData

Interface of data from event.

Kind: global interface

IEventFinishData

Interface of data from event.

Kind: global interface

IPayPalMeta

Interface for PayPal checkout meta information

Kind: global interface

IStyles

Interface for classes that represent widget's styles.

Kind: global interface

ITexts

Interface for classes that represent widget's text.

Kind: global interface

IBamboraMeta

Interface for Bamboora meta information

Kind: global interface

IElementStyleInput

Interface for styling input element.

Kind: global interface

IElementStyleSubmitButton

Interface for styling submit_button element.

Kind: global interface

IElementStyleLabel

Interface for styling label element.

Kind: global interface

IElementStyleTitle

Interface for styling title element.

Kind: global interface

IElementStyleTitleDescription

Interface for styling title_description element.

Kind: global interface

ITriggerData

Interface for classes that represent a trigger data.

Kind: global interface

HtmlWidget ⇐ HtmlMultiWidget

Class Widget include method for working on html and include extended by HtmlMultiWidget methods

Kind: global class
Extends: HtmlMultiWidget, MultiWidget

• HtmlWidget ⇐ HtmlMultiWidget
  • new HtmlWidget(selector, publicKey, [gatewayID], [paymentType], [purpose])
  • .setWebHookDestination(url)
  • .setSuccessRedirectUrl(url)
  • .setErrorRedirectUrl(url)
  • .setFormFields(fields)
  • .setFormElements(elements)
  • .setMeta(object)
  • .load()
  • .afterLoad()
  • .trigger(triggers, data)
  • .getValidationState() ⇒ IFormValidation
  • .isValidForm() ⇒ boolean
  • .isInvalidField(field) ⇒ boolean
  • .isFieldErrorShowed(field) ⇒ boolean
  • .isInvalidFieldByValidator(field, validator) ⇒ boolean
  • .hide([saveSize])
  • .show()
  • .reload()
  • .hideElements(elements)
  • .showElements(elements)
  • .updateFormValues(fieldValues)
  • .updateFormValue(key, value)
  • .onFinishInsert(selector, dataType)
  • .interceptSubmitForm(selector)
  • .useCheckoutAutoSubmit()
  • .useAutoResize()
  • .setStyles(fields)
  • .usePhoneCountryMask([options])
  • .setTexts(fields)
  • .setElementStyle(element, [state], styles)
  • .setFormValues(fieldValues)
  • .setFormLabels(fieldLabels)
  • .setFormPlaceholders(fieldPlaceholders)
  • .setIcons()
  • .setHiddenElements(elements)
  • .setRefId(refId)
  • .useGatewayFieldValidation()
  • .setSupportedCardIcons(elements, validateCardNumberInput)
  • .setEnv(env, [alias])
  • .loadIFrameUrl()
  • .setLanguage(code)

new HtmlWidget(selector, publicKey, gatewayID, paymentType, purpose)

Example

var widget = new HtmlWidget('#widget', 'publicKey', 'gatewayID'); // short

var widget = new HtmlWidget('#widget', 'publicKey', 'gatewayID', 'bank_account', 'payment_source'); // extend

var widget = new HtmlWidget('#widget', 'publicKey', 'not_configured'); // without gateway

htmlWidget.setWebHookDestination(url)

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

Kind: instance method of HtmlWidget

Example

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

htmlWidget.setSuccessRedirectUrl(url)

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

Kind: instance method of HtmlWidget

Example

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

htmlWidget.setErrorRedirectUrl(url)

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

Kind: instance method of HtmlWidget

Example

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

htmlWidget.setFormFields(fields)

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

Kind: instance method of HtmlWidget

Example

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

htmlWidget.setFormElements(elements)

The method to set the full configuration for the all specific form elements (visibility, required, label, placeholder, value) You can also use the other method for the partial configuration like: setFormFields, setFormValues, setFormPlaceholder, setFormLabel

Kind: instance method of HtmlWidget
Overrides: setFormElements

Example

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

htmlWidget.setMeta(object)

The method to set meta information for the checkout page

Kind: instance method of HtmlWidget

Example

config.setMeta({
            brand_name: 'paydock',
            reference: '15',
            email: 'wault@paydock.com'
        });

htmlWidget.load()

Loads the widget.

Calling this method results in an iframe element being inserted and rendered in the DOM.

Kind: instance method of HtmlWidget
Overrides: load
 

htmlWidget.afterLoad()

Registers a form validation callback for validation events.

Kind: instance method of HtmlWidget
Overrides: afterLoad
 

htmlWidget.trigger(triggers, data)

Registers callback that will be invoked for every trigger.

Kind: instance method of HtmlWidget
Overrides: trigger

htmlWidget.getValidationState() ⇒ IFormValidation

Gets a reference to the form current validation state.

!Warning: do not directly modify the values of the returned object.

Kind: instance method of HtmlWidget
Overrides: getValidationState
Returns: IFormValidation - Form validation object
 

htmlWidget.isValidForm() ⇒ boolean

Checks if a given form is valid.

A form is valid if all form fields are valid.

Kind: instance method of HtmlWidget
Overrides: isValidForm
Returns: boolean - Indicates wether or not form is valid.
 

htmlWidget.isInvalidField(field) ⇒ boolean

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

Kind: instance method of HtmlWidget
Overrides: isInvalidField
Returns: boolean - Field is invalid

htmlWidget.isFieldErrorShowed(field) ⇒ boolean

Checks if a given form field is displaying an error.

Kind: instance method of HtmlWidget
Overrides: isFieldErrorShowed
Returns: boolean - Indicates wether or not the Error message is being displayed on the associated field.

htmlWidget.isInvalidFieldByValidator(field, validator) ⇒ boolean

Checks if a given form field is valid or invalid by name.

Kind: instance method of HtmlWidget
Overrides: isInvalidFieldByValidator
Returns: boolean - Indicates wether or not the field is invalid based on validator intepretation.

htmlWidget.hide(saveSize)

Hides the widget.

E.g., use this method to hide the widget after it loads.

Kind: instance method of HtmlWidget
Overrides: hide

htmlWidget.show()

Shows the widget.

E.g., use this method to show the widget after it was explicitly hidden.

Kind: instance method of HtmlWidget
Overrides: show
 

htmlWidget.reload()

Reloads the widget.

Kind: instance method of HtmlWidget
Overrides: reload
 

htmlWidget.hideElements(elements)

Hides the specified Widget elements by their identifier.

Kind: instance method of HtmlWidget
Overrides: hideElements

Example

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

htmlWidget.showElements(elements)

Shows the specified Widget elements by their identifier.

Kind: instance method of HtmlWidget
Overrides: showElements

Example

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

htmlWidget.updateFormValues(fieldValues)

Updates the form field values inside the widget.

Kind: instance method of HtmlWidget
Overrides: updateFormValues

Example

widget.updateFormValues({
  email: 'predefined@email.com',
  card_name: 'Houston'
});

htmlWidget.updateFormValue(key, value)

Updates a single form field values inside the widget by the form field name.

Kind: instance method of HtmlWidget
Overrides: updateFormValue

Example

widget.updateFormValue("card_name", "John Doe");

htmlWidget.onFinishInsert(selector, dataType)

Inserts the event data (after finish event) onto the input field associated with the provided CSS selector.

Kind: instance method of HtmlWidget
Overrides: onFinishInsert

htmlWidget.interceptSubmitForm(selector)

Intercepts a form submission and delegates processing to the widget.

An simplified example of the process:

• User clicks submit button in your form
• This implicitly triggers a submission to the widget
• The widget submits your form

Kind: instance method of HtmlWidget
Overrides: interceptSubmitForm
Note: The widget's submit button will be hidden.

Example

<body>
 <form id="myForm">
     <input name="amount">
     <button type="submit">Submit</button>
 </form>
 <script>
    widget.interceptSubmitForm('#myForm');
 </script>
</body>

htmlWidget.useCheckoutAutoSubmit()

This method hides a submit button and automatically execute form submit

Kind: instance method of HtmlWidget
Overrides: useCheckoutAutoSubmit
 

htmlWidget.useAutoResize()

Use this method for resize iFrame according content height

Kind: instance method of HtmlWidget
Overrides: useAutoResize
Example

widget.useAutoResize();

htmlWidget.setStyles(fields)

Object contain styles for widget

Kind: instance method of HtmlWidget
Overrides: setStyles

Example

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'
      fort_family: 'fantasy'
  });

htmlWidget.usePhoneCountryMask(options)

Method to set a country code mask for the phone input.

Kind: instance method of HtmlWidget
Overrides: usePhoneCountryMask

Example

widget.usePhoneCountryMask();

Example

widget.usePhoneCountryMask({
      default_country: 'au',
      preferred_countries: ['au', 'gb'],
      only_countries: ['au', 'gb', 'us', 'ua']
  });

htmlWidget.setTexts(fields)

Method for set different texts inside the widget

Kind: instance method of HtmlWidget
Overrides: setTexts

Example

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

htmlWidget.setElementStyle(element, state, styles)

Method for set styles for different elements and states

Kind: instance method of HtmlWidget
Overrides: setElementStyle

Example

widget.setElementStyle('input', {
  border: 'green solid 1px'
});

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

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

htmlWidget.setFormValues(fieldValues)

The method to set the predefined values for the form fields inside the widget

Kind: instance method of HtmlWidget
Overrides: setFormValues

Example

widget.setFormValues({
      email: 'predefined@email.com',
      card_name: 'Houston'
  });

htmlWidget.setFormLabels(fieldLabels)

The method to set custom form field labels

Kind: instance method of HtmlWidget
Overrides: setFormLabels

Example

widget.setFormPlaceholders({
      card_name: 'Card Holder Name',
      email: 'Email For Receipt'
  })

htmlWidget.setFormPlaceholders(fieldPlaceholders)

The method to set custom form fields placeholders

Kind: instance method of HtmlWidget
Overrides: setFormPlaceholders

Example

widget.setFormPlaceholders({
      card_name: 'Input your card holder name...',
      email: 'Input your email, like test@example.com'
  })

htmlWidget.setIcons()

Deprecated

The method to change the widget icons

Kind: instance method of HtmlWidget
Overrides: setIcons
 

htmlWidget.setHiddenElements(elements)

Using this method you can set hidden elements inside widget

Kind: instance method of HtmlWidget
Overrides: setHiddenElements

Example

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

htmlWidget.setRefId(refId)

Current method can set custom ID to identify the data in the future

Kind: instance method of HtmlWidget
Overrides: setRefId

Example

widget.setRefId('id');

htmlWidget.useGatewayFieldValidation()

Current method can add visual validation from gateway to widget's form fields

Kind: instance method of HtmlWidget
Overrides: useGatewayFieldValidation
Example

widget.useGatewayFieldValidation();

htmlWidget.setSupportedCardIcons(elements, validateCardNumberInput)

Current method can set icons of supported card types

Kind: instance method of HtmlWidget
Overrides: setSupportedCardIcons

Example

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

htmlWidget.setEnv(env, alias)

Current method can change environment. By default environment = sandbox. Also we can change domain alias for this environment. By default domain_alias = paydock.com

Kind: instance method of HtmlWidget
Overrides: setEnv

Example

widget.setEnv('production', 'paydock.com');

htmlWidget.loadIFrameUrl()

Method for creating iframe url

Kind: instance method of HtmlWidget
Overrides: loadIFrameUrl
Example

widget.loadIFrameUrl(function (url) {
     console.log(url);
}, function (errors) {
     console.log(errors);
});

htmlWidget.setLanguage(code)

Method for setting a custom language code

Kind: instance method of HtmlWidget
Overrides: setLanguage

Example

config.setLanguage('en');

HtmlMultiWidget ⇐ MultiWidget

Class HtmlMultiWidget include method for working with html

Kind: global class
Extends: MultiWidget

• HtmlMultiWidget ⇐ MultiWidget
  • new HtmlMultiWidget(selector, publicKey, conf)
  • .load()
  • .afterLoad()
  • .trigger(triggers, data)
  • .getValidationState() ⇒ IFormValidation
  • .isValidForm() ⇒ boolean
  • .isInvalidField(field) ⇒ boolean
  • .isFieldErrorShowed(field) ⇒ boolean
  • .isInvalidFieldByValidator(field, validator) ⇒ boolean
  • .hide([saveSize])
  • .show()
  • .reload()
  • .hideElements(elements)
  • .showElements(elements)
  • .updateFormValues(fieldValues)
  • .updateFormValue(key, value)
  • .onFinishInsert(selector, dataType)
  • .interceptSubmitForm(selector)
  • .useCheckoutAutoSubmit()
  • .useAutoResize()
  • .setStyles(fields)
  • .usePhoneCountryMask([options])
  • .setTexts(fields)
  • .setElementStyle(element, [state], styles)
  • .setFormValues(fieldValues)
  • .setFormLabels(fieldLabels)
  • .setFormPlaceholders(fieldPlaceholders)
  • .setFormElements(elements)
  • .setIcons()
  • .setHiddenElements(elements)
  • .setRefId(refId)
  • .useGatewayFieldValidation()
  • .setSupportedCardIcons(elements, validateCardNumberInput)
  • .setEnv(env, [alias])
  • .loadIFrameUrl()
  • .setLanguage(code)

new HtmlMultiWidget(selector, publicKey, conf)

Example

var widget = new MultiWidget('#widget', 'publicKey','configurationToken'); // With a pre-created configuration token

var widget = new MultiWidget('#widget', 'publicKey',['configurationToken', 'configurationToken2']); // With pre-created configuration tokens

var widget = new MultiWidget('#widget', 'publ