Payment Widget

Overview

Payment Widget is a low-code script that adds Apple Pay and Google Pay buttons directly to the merchant's store – on product pages and/or in the cart – enabling one-tap checkout on supported devices without leaving your domain.

The problem we propose to solve

Long, multi-step checkouts and low-converting card forms hurt revenue. Reducing steps and keeping buyers on-page improves completion rates and trust.

About our solution

Embed payment widget where intention is highest (e.g., the product page) to skip the cart and complete payment in a secure native wallet sheet. No external redirects. Typical setup takes less than a day.

Key Benefits

• On-page payments: buyers pay without leaving your site
• Native wallets: Apple Pay & Google Pay out of the box
• SCA/PSD2 ready: 3DS2 is handled automatically for card flows when required by your acquirer
• Low-code integration: drop-in script, minimal config
• Reduced PCI scope: card data never touches your servers
• Flexible config & UI options: placement, amount, currency, callbacks, styles and more
• Apple domain verification made easy: guided one-file upload
• Fast Integration process: less than 1 day

Script connection

Adding file

On the merchant's page, in the <head> tag, it is necessary to add a link to the pay-buttons.js file.

The pay-buttons.js file must be located in the pay-buttons folder, on the same level with merchants folder (with payment pages).

Script declaration must contain id="pay-buttons".

<head>
  ...
  <script
    src="https://uat.dskbank.bg/payment/pay-buttons/pay-buttons.js"
    id="pay-buttons">
  </script>
  ...
</head>

Initialization

<script>
  document.addEventListener("DOMContentLoaded", function () {
    var widget = payButtonsWidget("containerId"); // where `containerId` is and id of the DOM-element where the buttons should be added
 
    widget.init({
      gatewayInfo: { // Information for Payment gateway
        token: "i29v9o5hkmuv2590l7661p9vcu", // Merchant's token
        amount: 852300, // Order amount in minor units
        returnUrl: "http\:\/\/yourwebsite.com\/success.html", // Target address after payment
        merchantLogin: "buttonApple",
      },
 
      applePay: { // Information for ApplePay session
        merchantId: "yourwebsite.com", // id of the merchant in Apple
      },
 
      googlePay: {
        environment: "TEST",
      },
    });
  });
</script>

Initialization parameters

Below is the complete list of the parameters used for the script initialization.

Parameters of cartItems block

Example of cartItems block:

[
  {
    name: 'Ball pen',
    quantity: {
        value: 1,
        measure: "pcs"
    },
    itemAmount: (totalAmount * 100) / 2,
    itemCurrency: "978",
    itemCode: 'number_1'
  },
  {
    name: 'Cheese',
    quantity: {
        value: 1.4,
        measure: "kg"
    },
    itemAmount: (totalAmount * 100) / 2,
    itemCurrency: "978",
    itemCode: 'number_2'
  }
]

Parameters of gatewayInfo object

A block with the client's registration data (address, postal code).

Description of parameters in shippingPayerData object:

Description of parameters in preOrderPayerData object:

Description of parameters in orderPayerData object:

Description of parameters in orderBundle object:

Description of parameters in customerDetails object:

Description of parameters in deliveryInfo object.

Description of parameters in cartItems object.

Description of parameters in items object.

Description of parameters in quantity object.

Description of parameters in itemDetails object.

Description of parameters in itemDetailsParams object.

Parameters of applePay block

See more details in the button constructor.

Example of paymentRequest:

{
  countryCode: 'DE',
  currencyCode: 'EUR',
  supportedNetworks: [
    'masterCard',
    'visa',
    'electron',
    'maestro'
  ],
  merchantCapabilities: [
    'supports3DS',
    'supportsCredit',
    'supportsDebit'
  ],
  total: {
    label: '',
    amount: 1.00 // major units
  },
  requiredShippingContactFields: [
    'postalAddress',
    'name',
    'phone',
    'email'
  ]
}

Parameters of googlePay block

Shipping methods

The customer selects the shipping address and method right in the Apple Pay or Google Pay window. No separate shipping form on your site is needed: the address comes from the wallet, and the total amount with shipping is recalculated instantly.

• Checkout in one window: product, shipping, and payment — without going to the cart or filling in forms
• Transparent price: the customer sees the shipping cost and the total amount before paying
• Only real options: for each shipping method, you can set countries, regions, and postal codes. The customer sees only the methods available for their address
• Shipping data in the order: the address and the selected shipping method are saved in the order in Payment gateway

How to enable

1. Specify gatewayInfo.merchantLogin.
2. Specify the cost of goods without shipping in gatewayInfo.amount — the widget adds the shipping cost itself.
3. List the shipping methods in the deliveryOptions parameter. The first method in the list is offered to the customer by default.
4. For Google Pay, specify googlePay.countryCode — the country code of the acquiring bank.

widget.init({
  gatewayInfo: {
    token: "i29v9o5hkmuv2590l7661p9vcu",
    amount: 10000, // Cost of goods without shipping, in minor units
    returnUrl: "http\:\/\/yourwebsite.com\/success.html",
    merchantLogin: "buttonApple",
  },

  applePay: {
    merchantId: "yourwebsite.com",
  },

  googlePay: {
    environment: "TEST",
    countryCode: "DE", // Acquiring bank country, not the shipping country
  },

  deliveryOptions: [
    {
      id: "courier",
      label: "Courier",
      description: "1-2 days",
      amount: 500, // Shipping cost in minor units
      countries: ["DE"],
      regions: ["DE-BE"],
    },
    {
      id: "pickup",
      label: "Pickup",
      amount: 0,
      countries: ["DE"],
      postalPrefixes: ["10"],
    },
  ],
});

Parameters of a deliveryOptions array element

What the customer sees

1. The customer clicks the Apple Pay or Google Pay button and selects a shipping address from the wallet.
2. The wallet shows the shipping methods available for this address. If you do not ship to this address, the wallet notifies the customer about this before payment.
3. The customer selects a shipping method and sees the total amount.
4. The customer confirms the payment. The order is created for the total amount, and the address and the shipping method are saved in the order.

onClick handler

Create an order in your system only when the customer actually pays. The widget calls onClick right after the payment is confirmed in Apple Pay or Google Pay — before the order is created in Payment gateway. In the handler, you can get the order number from your accounting system, set the return page or the notification address for a specific order.

The handler receives the gatewayInfo object, can be asynchronous, and returns the changed object. The customer waits in the wallet window meanwhile, so the handler must run quickly.

widget.init({
  gatewayInfo: {
    token: "i29v9o5hkmuv2590l7661p9vcu",
    amount: 852300,
    returnUrl: "http\:\/\/yourwebsite.com\/success.html",
    merchantLogin: "buttonApple",
  },
  applePay: {
    merchantId: "yourwebsite.com",
  },
  googlePay: {
    environment: "TEST",
  },
  onClick: async function (gatewayInfo) {
    // Get the order number from the store server
    var response = await fetch("/api/orders", { method: "POST" });
    var order = await response.json();

    gatewayInfo.orderNumber = order.number;
    gatewayInfo.returnUrl = "https://yourwebsite.com/orders/" + order.number;
    return gatewayInfo;
  },
});

Parameters that can be changed in the handler:

The customer has already confirmed the amount, currency, and cart in the wallet window, so they are set only when the widget is initialized. If the handler fails, the payment does not go through and the customer sees a message about it.

Saving the customer's card

Save the customer's card during an Apple Pay or Google Pay payment to process further payments with a stored credential. In all cases, pass the customer identifier in your system in gatewayInfo.clientId.

During payment. Passing clientId is enough: after a successful payment, the stored credential is created automatically if the merchant is allowed to create stored credentials.

Guaranteed card saving. Add FORCE_CREATE_BINDING to gatewayInfo.features so that a stored credential is created with every payment. The feature must be enabled for the merchant in Payment gateway.

Card saving without payment. Pass features: ["VERIFY", "FORCE_CREATE_BINDING"]. The customer confirms the card in the wallet, no money is charged, and the card is saved. Suitable for setting up a subscription or linking a card in a personal account.

widget.init({
  gatewayInfo: {
    token: "i29v9o5hkmuv2590l7661p9vcu",
    amount: 0,
    returnUrl: "http\:\/\/yourwebsite.com\/success.html",
    merchantLogin: "buttonApple",
    clientId: "customer-12345", // Customer identifier in the store system
    features: ["VERIFY", "FORCE_CREATE_BINDING"],
  },
  applePay: {
    merchantId: "yourwebsite.com",
  },
  googlePay: {
    environment: "TEST",
  },
});

Button size and corner radius

You can fit the Apple Pay and Google Pay buttons into the design of your site: set the width, height, and corner radius. Three CSS variables on the button container are enough — the settings apply to both buttons at once.

<style>
  #containerId {
    --pay-buttons-button-width: 320px;
    --pay-buttons-button-height: 48px;
    --pay-buttons-button-border-radius: 8px;
  }
</style>

<div id="containerId"></div>

The color and label of the buttons are set with the applePay.buttonStyle, applePay.paymentType, googlePay.buttonColor, and googlePay.buttonType parameters.

Code generator

You can also quickly generate the code of Payment Widget script via Merchant Portal. To do so, go to Quick buttons -> Code generator tab in your Personal Area.

This page contains a constructor that looks like as follows:

The tab has the following sections that contain parameters for the script initialization:

• Common settings - specify the common information for order generation in Payment Gateway:
  • Enable payments via Apple Pay and/or Google Pay payments,
  • Order number,
  • Amount (mandatory),
  • Currency (select from the list),
  • Language (select from the list),
  • Environment where you want to use the script (Test or Production).
  • Succesful payment page and Failed payment page (specify URL or select standard URL).
• User data request - specify the data that should be required during payment via PaymentRequest API for Google Pay. Select corresponding check boxes: Name, Email, Phone number, Postal address.
• Payment button settings - specify button type and style for Apple Pay and Google Pay buttons. You can see the buttons preview in this section.
• Code to embed on your page - this section displays preview of the script initialization code according to the specified parameters. This code should be embedded on your page.

Supporting by browsers

Testing and deployment

Test environment (UAT)

Connect the script with https://uat.dskbank.bg/payment/ address.

<script
  src="https://uat.dskbank.bg/payment/pay-buttons/pay-buttons.js"
  id="pay-buttons">
</script>

Production environment (PROD)

Connect the script with https://uat.dskbank.bg/payment/ address.

<script
  src="https://epg.dskbank.bg/payment/pay-buttons/pay-buttons.js"
  id="pay-buttons">
</script>