How to configure the Paydock Widget?

What is the Paydock Widget?

The widget is a PCI-DSS compliant payment form that allows you to collect billing details, such as credit card and bank account data, and exchange it for a one-time token to run charges. 

The widget itself does not process the payment. It only collects the data, sends it to Paydock, and returns the one-time token. Since the payment details are submitted through the Paydock iFrame, they are never sent to your server in their pure form, only in the form of the token. The backend of your website or application where you want to integrate the widget should be able to process such requests and handle the token. From your server, the token and the amount are sent to PayDock to make the payment using the API request:

 POST /v1/charges

It will look like this:

curl --location --request POST '{{url}}/v1/charges' \
--header 'x-user-secret-key: {{secretkey}}' \
--header 'Content-Type: application/json' \
--data-raw '{

How is it set up?

To proceed with the widget setup, first, you should either install the Client SDK with the help of the package manager or download it from the CDN. Both these options are described here. With the help of this JavaScript library, you can create an iFrame on your site where the widget will appear. 

For the widget to start working, you will need your public key (that can be found in your PayDock dashboard -> My Account -> API & Settings) and gateway ID. 

Then you can customize the fields in the form and set styles. This article on how to style the widget can come in handy.

You can monitor the user's actions with the widget in real-time and get information about the payment source using events. There are many events that can be handled in the widget based on your needs.

The iFrame (widget) and your site are isolated from each other. Still, the widget should be able to pass the one-time token required for running charges. It can be done with the help of various Events.

In short, the steps after you install the Client SDK are as follows:

1. Create an HTML element to contain the widget.

2. Initiate the widget, set various styles, configure inputs and subscribe to events.

3. Use a trigger to interact with the widget.

NB: Use events to catch any information (meta, validation, token, status). Use triggers for interacting with the widget (fill inputs in real-time, submit, change tabs, etc).

Below you can find the piece of code required for the basic setup:

<!DOCTYPE html>
<html lang="en">
	<meta charset="UTF-8">
		iframe {
			border: 0;
			width: 100%;
			height: 300px;
<h1>Simple Widget</h1>

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

<script src="" ></script>
<script src="../../../bundles/widget.umd.js" ></script>

	var widget = new paydock.HtmlWidget('#widget', 'yourpublickey', 'gatewayID');

For more details, please refer to the official documentation.

Types of Widget

There are several widget types also called Classes. You can choose the ones that will suit your needs most: 

  1. HtmlWidget
  2. HtmlMultiWidget
  3. Configuration
  4. PaymentSourceWidget
  5. Canvas3ds
  6. CheckoutButton
  7. MultiWidget
  8. WalletButtons

Below you will find a brief outline of their main functions and use cases. You can use several widget types at once.


This is a basic and the most common type of widget that supports one gateway and allows working with HTML. It generates a one-time token using the credit card or bank account details of your customer.


With this widget class, you can also support many gateways and payment types (bank account and card). Every gateway is configured separately as all of them have different settings and mandatory fields. Unlike MultiWidget, this widget class allows working with HTML and subscribing to events.


In this class of the widget, you can create a configuration for a specific gateway using its ID and the payment type (credit card or bank account). The widget of this class supports several gateways. You need to set up every gateway separately. You create a massive new Configuration with a particular gateway ID. As a result, you have a separate tab for a certain gateway in the widget. The method configuration.setFormFields(fields) allows you to define the mandatory fields for every tab. 


It populates all the payment sources added previously for a customer. PaymentSourceWidget requires a query token, which is a pre-generated and secure token for limiting the list of payment sources specific for a customer or reference. You will need your secret key to get the query token. First, you send the GET request get the customers list to receive a query token. Then you can use this query token as a one-time token for running charges.


This widget class supports the integration with 3D Secure. It renders challenging UI for payment authentication. It is an additional verification step when making a payment that prevents third parties from a malicious usage of credit and debit cards.


It is used for working with eWallets. Not all gateways support this option. Currently, you can use the checkout widget for PayPal Classic, Afterpay, and Zipmoney. It contains a checkout button, clicking on which you will see a pop-up window prompting you to log into the eWallet account to confirm the charge.  


This widget class will generate an iFrame link but it will not allow working with HTML elements and events. Usually, you choose this class when you want to write an integration for the widget yourself. This widget supports several gateways and payment types (bank account and card) too. Every gateway should be set up separately. 
NB: It is used rather rarely.


This class of widget is used to work with Google Pay and Apple Pay wallets. Google Pay is compatible with the Google Chrome browser and Apple Pay - with Safari. This widget works along with this charge endpoint.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us