KC UPCF Web SDK

The KC UPCF Web SDK provided by MPS is hosted and integrated through a static URL, eliminating the need for downloads. This SDK is a JavaScript (JS) file that is shared with marketplaces through the provided static URL, and the file is cached on the client side.

The KC UPCF Web SDK acts as a proxy between the marketplace and the KontoCloud Payment Connector Gateway. It facilitates front-end interactions such as:

• Payment Form Integration – assisting in the secure collection and transmission of payment details.
• Consumer Device Validation – verifying and validating consumer devices during payment processes.

This setup streamlines communication and ensures seamless integration without the need for direct access to backend systems.

tip

Mobile SDKs enable the native integration of various payment options in iOS and Android apps.

KC Web SDK is designed for browser-based integrations, and it is compatible with mobile devices.

KC UPCF Web SDK serves the same purpose but is required for specific web checkout scenarios, including usage on mobile devices. It is mandatory for integrating certain payment methods such as Apple Pay and Google Pay™.

If you're unsure which SDK to use for your integration, please contact your Product Solution Specialist.

1. Integrate KC UPCF Web SDK

1.1. Include the JavaScript Library

The KC UPCF Web SDK is a JavaScript (JS) file that is integrated into the webshop's code. The browser needs to load this JS file on the webshop page to enable its functionality. The URL for accessing the SDK is defined as {baseURL}/websdk/web-sdk.js, where {baseURL} represents the KontoCloud API environment URL specific to the environment being used (such as production or testing). This URL ensures that the KC UPCF Web SDK is dynamically loaded into the webshop, allowing secure and seamless interaction with the payment system.

<script src="{baseURL}/websdk/web-sdk.js"></script>

Please use the known baseURL for the required environment.

1.2. Create a Container

To securely collect payment option details from your customers, the KC UPCF Web SDK automatically adds all the necessary elements required to collect payment option details, rather than having you create them manually. To determine where to insert these components, you should create an empty DOM element in your solution. MPS recommends using a <div> element with a unique ID on the page where the payment form will be rendered. The KC UPCF Web SDK will then populate this container with the necessary fields for customers to enter their payment option details securely.

<div id="container"></div>

The SDK will target this container and handle the rendering of the payment form automatically.

1.3. Add the JavaScript Snippet (example)

<script type="text/javascript"> (function() {
    var container = document.getElementById("container"); //Get Container by ID
    //Only as Example: The "authorizationToken" is taken from Window Pop-Up Prompt
    //Token should be passed from init Authorize / init Add Stored Payment Option
  var authorizationToken = window.prompt("Enter new authorizationToken:", "");
  try
  {
    var paymentForm = kc.pcg.PaymentForm(container,
    {
      authorizationToken: authorizationToken,
      submitButtonTitle: "Submit",
      onComplete: function (){},
      onError: function(message){ console.log(message); }
    });
  }
  
  catch (e) { console.log(e); }
})(); </script>

1.4. Payment Form Configuration

KontoCloud UPCF Web SDK contains a JS-script with the following parameters for the Payment Form initialization:

Parameter	Required	Value
authorizationToken	Yes	KontoCloud Authorization Token returned in response to Init Authorize/Init Add Stored Payment option API.
css	No	If this field is provided, then payment form can use these CSS-rules as inline styles for the elements placed in the iframe-elements inside the form. .upc-container { border: 1px solid black; } .market-control-card { color: black; }
cssUrls	No	Array of valid URL values for loading CSS files which will be used to customize the payment form styling. If this field is provided, then payment form can use these URLs as the styles for the elements placed in the iframe-elements inside the form.
cssClasses	No	Mapping for the standard Connector classes and the Marketplace classes. It is formatted as: {"{standard Connector class}":"{Marketplace class or classes separated by space}"}. "{"upc-container":"market-container market-border", "upc-control":"market-control-card market-control-holder"}" See list of standard Connector classes below.
locale	No	The option which indicates the language to use for customer-facing content of payment form.
submitButtonTitle	No	String array of payment option codes. Used to show the all payment options code visible to end customer
* onComplete	Yes	This callback function is triggered after the payment form is successfully submitted and processed. It allows the merchant to implement custom logic, such as showing a success message or initiating additional server-side processes. KC UPCF Web SDK does not provide direct access to payment authorization status; merchants should use this callback to define their desired post-payment actions.
* onError	Yes	This function is triggered when a problem prevents the payment form from being successfully submitted. It is used to handle errors and ensure a smooth user experience by guiding the shopper through corrective steps.

tip

* The onComplete callback function is invoked when the payment form is successfully submitted and processed, indicating a successful payment initiation. The onError callback function is triggered if there is an issue during the payment process, such as a validation error or a failed submission. Merchants should implement appropriate handling in these callbacks to manage the user experience, such as retrying the process for errors or confirming the success of the transaction. Please note that these callbacks only indicate the outcome of the form submission and not the final payment authorization status. Both callbacks are essential for managing the end-to-end payment process, ensuring that successful submissions are handled properly and errors are addressed promptly.

1.5. Standard Connector Classes

Standard Connector Classes are predefined CSS classes provided in the KC UPCF Web SDK to help merchants easily customize the appearance of the payment form. These classes ensure that the payment form is rendered correctly while allowing the merchant to apply their own CSS styling. When a merchant applies their custom CSS, the standard connector classes are used to define the base structure of the form, including input fields, buttons, and labels, while the merchant's styles control the design aspects like colors, fonts, and spacing. This setup ensures that the payment form remains functional and properly structured while matching the merchant's overall site design.

Payment Form HTML Sample:

<div class="upc-container">
    <form class="upc-form" action="https://testsecureacceptance.cybersource.com/silent/pay" method="POST" >
        <div class="upc-group upc-group-brand upc-clearfix">
            <div class="upc-label upc-label-brand">Brand</div>
		 	<div class="upc-wrapper upc-wrapper-brand">
            	<div class="upc-brand upc-brand-MASTER"></div>
			</div>
        </div>
        <div class="upc-group upc-group-input upc-clearfix">
            <div class="upc-label upc-label-input">Card Number</div>
            <div class="upc-wrapper upc-wrapper-input">
                <input autocomplete="off" type="tel" name="card_number" class="upc-control" placeholder="Card Number">
            </div>
        </div>
        <div class="upc-group upc-group-input upc-clearfix">
            <div class="upc-label upc-label-input">Expiry Date</div>
            <div class="upc-wrapper upc-wrapper-input">
                <input autocomplete="off" type="tel" name="card_expiry" class="upc-control" placeholder="MM / YY">
            </div>
        </div>
        <div class="upc-group upc-group-input upc-clearfix">
            <div class="upc-label upc-label-input">Card holder</div>
            <div class="upc-wrapper upc-wrapper-input">
                <input autocomplete="off" type="text" name="card_holder" class="upc-control" placeholder="Card holder">
            </div>
        </div>
        <div class="upc-group upc-group-input upc-clearfix">
            <div class="upc-label upc-label-input">CVV</div>
            <div class="upc-wrapper upc-wrapper-input">
                <input autocomplete="off" type="tel" name="card_cvv" class="upc-control" placeholder="CVV">
            </div>
        </div>
        <div class="upc-group upc-group-submit">
            <div class="upc-wrapper upc-wrapper-submit">
                <button type="submit" name="pay" class="upc-button">Pay</button>
            </div>
        </div>
    </form>
</div>

The HTML markup for the payment form follows a specific structure and class definitions to ensure proper styling and functionality.

Container and Form

(container) - container div (see paragraph 2. Create a Container), wraps the payment form; class: upc-container
(form) - form element, contains groups of labeled input elements and hidden inputs; class: upc-form

Groups

Each group wraps the label (when necessary) and the wrapper of the input element.

<div class="upc-group ... upc-clearfix">
    <div class="upc-label ... ">...</div>
    <div class="upc-wrapper ... ">...</div>
</div>

Individual groups and their classes:

• (brand) - Brand group - .upc-group-brand
  
• (input) - Input group - .upc-group-input
  
• (submit) - Submit button group - .upc-group-submit
  

Labels

Contained in a group. Visibility of the labels is defined be the styles (see 'css', 'cssUrls' and 'cssClasses' option values in the table above).

<div class="upc-label ...">
   Card Number
</div>

Individual labels classes:

• (brand) - Brand group - .upc-label-brand
  
• (input) - Input group - .upc-label-input
  
• (submit) - no label

Input Wrappers

Input elements must by wrapped in a <div> to gain more control over their styles, especially their width.

<div class="upc-wrapper ...">
   <input>...</input>
</div>

Individual wrapper classes:

• (brand) - Brand group - .upc-wrapper-brand
  
• (input) - Input group - .upc-wrapper-input
  
• (submit) - Submit button group - .upc-wrapper-submit

Input elements

All <input> elements must have a base .upc-control class and set to width: 100%; by default. The width of these elements should be set via .upc-wrapper.
.upc-control styles the borders, backgrounds or paddings of all <input> elements.

<input class="upc-control" name="..." autocomplete="off" type="..." placeholder="...">

Submit Button

• (submit) - Submit button must have .upc-button class.

<button type="submit" name="pay" class="upc-button">Pay</button>

Brands

Brands logic is only applicable for Cards. Brands group must have a brand image <div> element without any <input> elements.

<div class="upc-brand upc-brand-MASTER"></div>

The ollowing classes must be applied to brand element:

• .upc-brand - styles the brand icons
• .upc-brand-BRAND - styles the specific brand, where BRAND can have one of Payment Option Codes.

Brand icons behavior depends on the Brand Auto Detect (see below):

1. If Brand Auto Detect is not enabled, i.e., single payment option is provided, then the corresponding brand icon must be displayed in brand section of the payment form.
2. If Brand Auto Detect is enabled:
   • If card number is not entered, invalid or card scheme cannot be identified, then the brand icon must be hidden
   • If card scheme identified, then the corresponding brand icon must be shown.

Brand Auto Detect:

1. Brand auto-detection must be enforced when more than one payment option is specified in 'paymentOptionCodes' field (see the table above).
2. Once the user changed the card number value, the brand must be identified. Brand identification must be performed within the types specified in 'paymentOptionCodes' only.
3. Every time the identified brand changed 'card_type' hidden input value must be set. If card brand is unidentified or became unidentified, 'card_type' input value must be emptied.
4. When single payment option specified in 'paymentOptionCodes' array, auto-detect function must be disabled, 'card_type' hidden input value must be set to single payment option specified in array.

Error hints

• (hint) - when a validation error occurs at some input elements, the error hint must be shown under the each erroneous element. .upc-has-error class must be added into each erroneous <input> element to style the element when it is not valid.

<input class="upc-control ... upc-has-error">
<div class="upc-hint upc-hint-...">
    Validation error text
</div>

Helpers

• .upc-clearfix allows elements to contain floats without re-sorting. Assuming that .upc-label and .upc-wrapper are floated, .upc-group needs .upc-clearfix.

<div class="upc-group">
    <div class="upc-label">...</div>
    <div class="upc-wrapper">...</div>
</div>

This structure ensures that the form is properly organized and that its elements can be easily styled and managed within the page.

1.6. Payment Form Disposing

If the Marketplace needs to destroy the payment form and remove the iframe from the container element, it can trigger the paymentForm.dispose() function. This function ensures that the payment form and its associated elements, including the iframe, are properly removed from the DOM, cleaning up any resources used by the form. This is particularly useful when navigating away from the payment page or resetting the form to prevent memory leaks or unwanted behavior.

2. Verify Supported Payment Methods on a Device

To verify whether Apple Pay or Google Pay™ methods are supported by a device, the merchant should invoke the SDK method:

kc.webSdk.PreviewablePaymentOptionsAsync
({ 
   programCode: "PROG", 
   paymentOptions: ["GGLPAY", "APPLPAY"], 
   programConnectorReferences: ["cb0b83****4d957", "dc1c94****5e068"] 
})

This optional method queries the SDK to determine the available payment options when Apple Pay or Google Pay™, or both, are supported on the user's device. The SDK responds with a payment options list containing the relevant payment option codes for Apple Pay or Google Pay™, or both, based on the device's compatibility. Merchants can use this information to display only the supported payment methods to the consumer, ensuring that only functional options are available for selection.

Parameter	Required	Value
programCode	Yes	Code of the Program.
paymentOptions	Conditional	String array of payment option codes, "APPLPAY" or "GGLPAY", or both.
programConnectorReferences	No	String array of references related to Program Connectors configured in KontoCloud.

3. Initiate Authorization or Initiate Storing of A New Payment Option

Please refer to the process described for Apple Pay - Initiate Authorization and Google Pay™ - Initiate Authorization.

For merchants looking to enable stored payment option under a technical account, follow the steps outlined for Apple Pay - Initiate Storing of A New Payment Option and Google Pay™ - Initiate Storing of A New Payment Option.

4. Consumer Interaction and Checkout

Please refer to the process described for Apple Pay Guest Payments and Google Pay™ Guest Payments.

5. Complete Authorization or Complete Storing of A New Payment Option

Please refer to the process described for Apple Pay - Complete Authorization and Google Pay™ - Complete Authorization.

For merchants looking to enable stored payment option under a technical account, follow the steps outlined for Apple Pay - Complete Storing of A New Payment Option and Google Pay™ - Complete Storing of A New Payment Option.