Skip to main content

KC Web SDK

This section covers how to use the KC Web SDK to securely collect payment option details. The KC Web SDK is made up of a light-weight JavaScript library and a sample HTML page using the library. This approach maintains a SAQ-A compliant payment-form solution while enabling you to build forward compatible web experiences which seamlessly combine your corporate identity with the required functionalities whilst adding some additional ancillary functions to ease integration. Download the KC Web SDK from the following link.

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.

Web SDK Content Overview​

The SDK is made up of two files:

  • cwPaymentForm-X.X.X.js: a light-weight JavaScript library which has to be embedded on the page where the Payment Form is to be rendered.
  • cwPaymentForm-X.X.X.min.js: the same JavaScript Library referenced above, but Minified for better performance, recommended for Production.
  • cwPaymentForm.html: a sample HTML file with the Payment Form embedded and ready to try with a new authorization token at the click of a button.

Error Handling​

The JavaScript snippet to configure and render the payment form is enclosed within a try catch block which alongside the onError function should be used to generically handle and log any exceptions occurring during the collection of payment option details e.g., if the user remains on the page without entering any payment options details for longer than 30 minutes leading to the expiration of the authorization token's lifetime which if submitted would result in an exception if submitted for processing.

Setup​

The cwPaymentForm.html includes a working sample and can be used as a starting point for integration.

1. Include the JavaScript Library​

To gain access to the functionalities and features of the JavaScript library, you must include it in the HTML-file.

Snippet to Reference JavaScript Library:

<script src="cwPaymentForm-6.2.1.js"></script>

2. Create a Container​

To securely collect payment option details from your customers, the Web SDK continues to add all elements required to collect the payment option details to your solution rather than you creating them directly. To determine where to insert these components, create an empty DOM element (a container). We recommend a DIV with a unique ID on the page where the payment form is to be rendered and the user to enter their payment option details.

Snippet of a Sample Container:

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

3. Add the JavaScript Snippet​

Pay.ON​

Add the JavaScript snippet to configure and render the payment form.

Snippet to Configure and Render the Payment Form:

(function() {
  
  var container = document.getElementById("container"); //Get Container by ID
  
  //Only as Examle: The "authorizationToken" is taken form Window Pop-Up Prompt
  //Token should be passed form init Authorize / init Add Stored Payment Option
  var authorizationToken = window.prompt("Enter new authorizationToken:", "");
  
  try
  {
    cw.PaymentForm(container,
    {
      authorizationToken: authorizationToken,
      
      callbackUrl: "https://example.com/Payment/CompleteAuthorization",
      //confirmationUrl: "https://www.example.com/Checkout/ConfirmOrder",
      
      paymentOptionCodes: ["MSTRCRD"],
      locale: "en-US",
      paymentProviderMode: "test", //Switch to "live" ONLY for Production
      
      //isStorable: true,
      //isStorableCaption: "Store payment method?",
      
      submitButtonTitle: "Submit",
      
      onBeforeSubmit: function(data, callback)
      {
        if ( /*confirm("Are you sure ?") === */ true) { callback(); }
      },
      
      onFormLoaded: function() { /* console.log("FormLoaded"); */},
      
      onError: function(message){ console.log(message); }
    });
  }
  
  catch (e) { console.log(e); }
  
})();

PayPal​

Add the JavaScript snippet to configure and render the payment form.

note

Initializing the KC Web SDK is necessary when a given Payment Option is available through Multiple Payment Providers. The Default Payment Provider is Pay.ON.

Snippet to Configure and Render the Payment Form:

cw.initialize({ enablePayPal: true }); //Required for using PayPal Provider
  
  var container = document.getElementById("container"); //Get the Container
  
  //Only as Examle: The "authorizationToken" is taken form a Window Prompt
  //Token must be from "Init Authorize" / "Init Add Stored Payment Option"
  var getAuthToken = window.prompt('Enter the "authorizationToken":', '');
  
  try
  {
    cw.PaymentForm(container,
    {
      authorizationToken: getAuthToken,
      
      paymentOptionCodes: ["PAYPAL"],
      
      //"live" ONLY for Production
      paymentProviderMode: "test", 
      
      paypalButtonStyle: //Optional
      {
        size: "medium",  //Default "small"
        color: "blue",   //Default "gold"
        shape: "rect",   //Default "pill"
        label: "paypal", //Default "paypal"
        tagline: "false" //Default "false"
      },
      
      onError: function(msg){ console.log(msg); }
    });
  }
  
  catch (error) { console.log(error); }

SEPA​

Add the JavaScript snippet to configure and render the payment form.

note

Initializing the KC Web SDK is necessary when a given Payment Option is available through Multiple Payment Providers. The Default Payment Provider is Pay.ON.

Snippet to Configure and Render the Payment Form:

cw.initialize( //Required to Use the SEPA Payment Provider
   {
      apiURL: <apiEndpoint>, //The KontoCloud WebAPI Endpoint
      bankAccountPaymentProvider: "sepa" //Set SEPA Provider
   });
   
   var container = document.getElementById("container"); //Find Container
   
   //Only as Example: The "authorizationToken" is taken form a Window Prompt
   //Token must be from "Init Authorize" / "Init Add Stored Payment Option"
   var getAuthToken = window.prompt('Enter the "authorizationToken":', '');
   
   //The "authorizationToken" is Base64-Encoded JSON with the Below Data
   var jsonData = JSON.parse(atob(getAuthToken)); //Decode Base64 & JSON
   var mandateReference = jsonData.mandateReference; //Mandate Reference
   var mandateSignedDate = jsonData.mandateSignedDate; //Signed Date UTC
   
   try
   {
      cw.PaymentForm(container, //Render Payment Form in Container
      {
         authorizationToken: getAuthToken, //Pass from Above Input
         
         paymentOptionCodes: ["BNKACCT"], //Only "BNKACCT" Valid
         
         locale: "en-US", // Optional, Default Value is "en-US"
         
         //Optional, Show SEPA Mandate Acceptance Page
         onBeforeSubmit: function(data, submit, cancel)
         {
            var mandate = confirm("Example SEPA Mandate Acceptance Page"
            +"\n\n"+ "Mandate = " + mandateReference +"\n"+ //From Token
            "Signed Date = " + mandateSignedDate +"\n\n"+ //From Token
            "Name = " + data.accountHolder //From Payment Form Input
            +"\n"+ "IBAN = " + data.iban); //From Payment Form Input
            
            // User Accepts or Rejects the SEPA Mandate
            if(mandate) { submit(); } else { cancel(); }
         },
         
         // Optional, Handle Error from Payment Provider
         onError: function(msg) { console.error(msg); },
         
         submitButtonTitle: "Submit" // Optional
      });
   }
   // Use it to Handle Unexpected Errors
   catch (error) { console.log(error); }

PaymentsOS​

Add the JavaScript snippet to configure and render the payment form.

Snippet to Configure and Render the Payment Form:

var container = document.getElementById("container"); //Get the Container
  
  //Only as Examle: The "authorizationToken" is taken form a Window Prompt
  //Token must be passed by BackEnd form Response of "1.38 Init Authorize"
  var getAuthToken = window.prompt('Enter the "authorizationToken":', '');
  
  try
  {
    cw.PaymentForm(container,
    {
      authorizationToken: getAuthToken,
      
      paymentOptionCodes: ["PAYU"], // Choose Only a Single One
      // Supported "PAYU", "PAYUINST", "PAYUTWST" and "PAYUBLK"
      
      locale: "en-US" // Optional
    });
  }
  
  catch (error) { console.log(error); }

4. Payment Form Configuration​

info

Please note some entries in the below table may vary depending on details such as Integration Type, Payment Provider and others.

Pay.ON​

PropertyRequiredDescription
authorizationTokenYesExpects a new authorization token to collect and associate payment option details with.
callbackUrlYesExpects a URL to redirect the user to, following the collection of their payment option details. The destination URL should call the next API method to either complete the initiated adding of a payment option or complete the initiated authorization as is the case during guest payments.
confirmationUrlNoRelevant to Guest Payments, if specified expects a URL to the payment summary page; the page is expected to accept authorizationToken as a query string parameter, e.g., www.example.com/Checkout/OrderConfirmation.
paymentOptionCodesYesThe payment option code associated with the payment option chosen by the customer (see Payment Options).
localeYesExpects ISO 639-1 for languages and ISO 3166-1 alpha-2 for countries.
paymentProviderModeYesExpects either: test, live. Use "test" throughout development and testing, switching to "live" only for your production deployment.
submitButtonTitleYesThe specified text is shown on the submit button. Localization must be handled for this element by yourself.
onBeforeSubmitNoA function expecting two parameters data and callback, the latter being a function to be called once execution is to resume e.g., after the user has explicitly confirmed something by clicking a button or other logic has been executed prior to execution being permitted to continue.
Information: SEPA Direct Debits require the bank account holder to accept a mandate (debit authorization) that allows their bank account to be debited; onBeforeSubmit would permit a form to this effect be displayed and prevent further execution (by not calling the "callback(); function) unless the user accepts the mandate.
The data object contains key value pairs reflecting the contents of the Payment Form which you are permitted to access such as:
In the case of a credit card: cardHolder : "John Smith", expiryDate : "12 / 22".
In the case of a SEPA direct debit: accountHolder : "John Smith", iban : "DE12500105170648489890".
isStorableNoRelevant only to the collection and adding of payment option details as part of guest payments to Business Accounts.
Important: This property should NOT be set if the authorizationToken has been returned by the API method 1.53 Init Add Stored Payment Option. Expects either: true, false.
isStorableCaptionNoRelevant only to the collection of payment option details as part of guest payments to Business Accounts.
Information: Should only be defined if the property isStorable has been specified. Expects the text which is to be shown within the label to the right of the checkbox which if ticked will persist the payment option details entered. Localization must be handled for this element by yourself.
onFormLoadedNoA function to handle any logic to be executed upon the form having been loaded.
onErrorYesA function to handle any exception handling logic. By default all events should be handled generically and logged for later analysis.

PayPal​

PropertyRequiredDescription
authorizationTokenYesThe value of the Payment Token or Billing Agreement Token returned by the 1.38 Init Authorize or 1.53 Init Add Stored Payment Option APIs.
paymentOptionCodesYesArray of payment options. Must contain only the PAYPAL option.
localeNoDefines the Language of the Rendered Button and the Payment Form. Please consult with the "Locale Codes" officially supported by PayPal: https://developer.paypal.com/docs/api/reference/locale-codes. The Default Value is en_US.
paypalButtonStyleNoA JSON Object with the Desired "Button Styling" Options. More detailed description is provided in the below table.
paymentProviderModeNoDefines which PayPal environment to use.
live - for "production",
test - for "sandbox". Use "test" throughout your development and testing, switch to "live" only for your production deployment.

Paypal "Button Styling" Options:

PropertyDescription
size• "small" - Default Value, 150px by 25px
• "medium" - Dimensions: 250px by 35px
• "large" - Dimensions: 350px by 40px
• "responsive" - Matches width of container, Min width is 100px and Max width is 500px.
color• "gold" - The Default Value
• "blue" - Light-Blue Aesthetic
• "silver" - Cool and Simplistic
• "black" - Monochromatic Style
shape• "pill" - Default, Pill-Shaped Button
• "rect" - A more Rectangular Button
label• "paypal" - Default, the Generic "PayPal"
• "checkout" - Displays "PayPal Checkout"
• "pay" - Displays the "Pay With PayPal"
• "buynow" - An Unbranded "Buy Now"
tagline• true - Show "The safer, easier way to pay"
• false - Default, No Text Under the Button

SEPA​

PropertyRequiredDescription
apiURLYesThe KontoCloud WebAPI Base URL for the Specified Environment. Contact your Product Solution Specialist / Customer Relationship Manager.
authorizationTokenYesThe Payment Token is a Base64-Encoded JSON string returned by the 1.38 Init Authorize or 1.53 Init Add Stored Payment Option APIs.
paymentOptionCodesYesArray of payment options. Must contain only the BNKACCT option.
localeNoDefines the Language used for Rendering the Payment Form. ISO 639-1 for Languages, ISO 3166-1 alpha-2 for Countries. Values: en-US (Default), de-DE, es-ES, it-IT, fr-FR.
submitButtonTitleNoThe Text shown on the Payment Form "Submit" Button. Any Text Localization must be hanged by the Integrator.
showLabelsNoSets Visibility of Payment Form Input Elements Labels.
"true" - Default, Enable Visibility of Input Labels,
"false" - Disable the Visibility of the Input Labels
showPlaceholdersNoSets Visibility of Payment Form Input Elements Placeholders.
"true" - Default, Enable Visibility of Input Placeholders,
"false" - Disable the Visibility of the Input Placeholders
iframeCssNoString with CSS Notation to Style the Payment Form as desired.
iframeCssUrlsNoArray of Strings with the Absolute URLs to External CSS Files.
onBeforeSubmitNoDefines a Function to call before Submitting the Payment From. Can be used to Render the SEPA Mandate (Debit Authorization).
The "data" object contains the key-value pairs defined below:
"accountHolder" - the Name(s) from the Form Input,
"iban" - Bank Account Number from the Form Input
onErrorNoFunction to handle any Errors returned from Payment Provider.

PaymentsOS​

PropertyRequiredDescription
authorizationTokenYesThe Payment Token returned by the 1.38 Init Authorize Response.
paymentOptionCodesYesArray of Payment Options supported for the PaymentsOS provider.
localeNoDefines the Language used for Rendering the Payment Form. ISO 639-1 for Languages, ISO 3166-1 alpha-2 for Countries. The Default Value is en-US.

KC Web SDK Customization for ACI Pay.ON​

The KC Web SDK payment form is designed with flexibility in mind, allowing merchants to seamlessly integrate it into their existing checkout experience. The form follows structured CSS framework that ensures a consistent layout while providing extensive customization options.

Merchants can modify the appearance of the payment form by applying custom CSS styles in their stylesheet. To ensure consistency, we recommend using a default style of plain, while allowing custom stylesheets to be combined with any of the default style options. All class names and container structures are static and will not change in the future to maintain compatibility and existing integrations. Any planned modifications will be communicated in advance to allow for code migration and continued support.

CSS Classes and Selectors​

The KC Web SDK includes predefined CSS classes that control the layout and styling of various elements. Merchants can modify these classes to adjust the visual presentation of the payment widget. For optimal performance, every element has a base CSS class along with an individual CSS class. For instance, the credit card payment form container has a base .wpwl-container class and an individual .wplw-container-card class that specifies the credit card form container.

Container​

.wpwl-container wraps the payment form, allowing for custom styling such as margin adjustments between the payment form and other elements on the page.

<div class="wpwl-container">
   ...
</div>

Individual classes:

  • .wpwl-container-card

Form​

.wpwl-form styles all payment forms, enabling modifications such as background color, padding and shadow effects.

<form class="wpwl-form wpwl-clearfix" action="https://eu-test.oppwa.com/v1/checkouts/{checkoutId}/payment" method="POST" target="cnpIframe" lang="en">
    ...
</form>

Individual classes:

  • .wpwl-form-card

Groups​

.wpwl-group wraps the label and the input wrapper, allowing the styling of input fields and labels together (position or width).

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

Individual classes:

  • .wpwl-group-brand
  • .wpwl-group-cardNumber
  • .wpwl-group-expiry
  • .wpwl-group-cardHolder
  • .wpwl-group-cvv
  • .wpwl-group-submit (styles the "Pay now" button)
  • .wpwl-group-button (styles buttons containing payment brand options)

Labels​

.wpwl-label defines the label for an input field.

<div class="wpwl-label">
    Card Number
</div>

Individual classes:

  • .wpwl-label-brand
  • .wpwl-label-cardNumber
  • .wpwl-label-expiry
  • .wpwl-label-cardHolder
  • .wpwl-label-cvv

Input and Select Wrappers​

To improve styling control, input and select elements are enclosed within a wrapper. .wpwl-wrapper controls the width of input or select elements.

<div class="wpwl-wrapper">
    ...
</div>

Individual classes:

  • .wpwl-wrapper-brand
  • .wpwl-wrapper-cardNumber
  • .wpwl-wrapper-expiry
  • .wpwl-wrapper-cardHolder
  • .wpwl-wrapper-cvv
  • .wpwl-wrapper-submit

Input and Select Elements​

All textual <input>, <textarea> and <select> elements use the .wpwl-control base class and default to width: 100%. The width should be set via .wpwl-wrapper. .wpwl-control controls the borders, backgrounds or paddings of all <input> and <select> elements.

<input class="wpwl-control wpwl-control-cardNumber" name="card.number" autocomplete="off" type="tel" placeholder="Card Number">
<select class="wpwl-control wpwl-control-brand" name="paymentBrand">
    <option value="MASTER">Mastercard</option>
    <option value="VISA">Visa</option>
</select>

Individual classes:

  • .wpwl-control-brand
  • .wpwl-control-cardNumber
  • .wpwl-control-expiry
  • .wpwl-control-cardHolder
  • .wpwl-control-cvv

Buttons​

.wpwl-button styles the submit buttons.

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

Individual classes:

  • .wpwl-button-pay (styles the "Pay now" button)
  • .wpwl-button-brand (styles buttons containing a brand)

Brands​

.wpwl-brand styles brands icons.

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

Individual classes:

  • .wpwl-brand-card (styles card brands)
  • .wpwl-brand-BRAND (styles a specific brand)

Error Hints​

.wpwl-has-error applies an error styling (red background, border and color) to an input field, and .wpwl-hint displays an error message.

<input autocomplete="off" type="tel" name="card.number" class="wpwl-control wpwl-control-cardNumber wpwl-has-error" placeholder="Card Number">
<div class="wpwl-hint wpwl-hint-cardNumberError">
    Invalid card number or brand
</div>

Individual classes:

  • .wpwl-hint-cardNumberError
  • .wpwl-hint-expiryError
  • .wpwl-hint-cardHolderError
  • .wpwl-hint-cvvError

Helpers​

.wpwl-clearfix ensures floated elements inside .wpwl-group are properly contained. If .wpwl-label and .wpwl-wrapper are floated, .wpwl-group needs .wpwl-clearfix.

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

Example: Credit Card Payment Form​

Below is an example of a credit card payment form with appropriate CSS classes.

<div id="card_220921339056" class="wpwl-container wpwl-container-card">
    <form class="wpwl-form wpwl-form-card wpwl-clearfix" action="https://eu-test.oppwa.com/v1/checkouts/{checkoutId}/payment" method="POST" target="cnpIframe" lang="en">
        <div class="wpwl-group wpwl-group-brand wpwl-clearfix">
            <div class="wpwl-label wpwl-label-brand">Brand</div>
            <div class="wpwl-wrapper wpwl-wrapper-brand">
                <select class="wpwl-control wpwl-control-brand" name="paymentBrand">
                    <option value="MASTER">Mastercard</option>
                    <option value="VISA">Visa</option>
                </select>
            </div>
            <div class="wpwl-brand wpwl-brand-card wpwl-brand-MASTER"></div>
        </div>
        <div class="wpwl-group wpwl-group-cardNumber wpwl-clearfix">
            <div class="wpwl-label wpwl-label-cardNumber">Card Number</div>
            <div class="wpwl-wrapper wpwl-wrapper-cardNumber">
                <input autocomplete="off" type="tel" name="card.number" class="wpwl-control wpwl-control-cardNumber" placeholder="Card Number">
            </div>a
        </div>
        <div class="wpwl-group wpwl-group-expiry wpwl-clearfix">
            <div class="wpwl-label wpwl-label-expiry">Expiry Date</div>
            <div class="wpwl-wrapper wpwl-wrapper-expiry">
                <input autocomplete="off" type="tel" name="card.expiry"b class="wpwl-control wpwl-control-expiry" placeholder="MM / YY">
            </div>
        </div>
        <div class="wpwl-group wpwl-group-cardHolder wpwl-clearfix">
            <div class="wpwl-label wpwl-label-cardHolder">Card holder</div>
            <div class="wpwl-wrapper wpwl-wrapper-cardHolder">
                <input autocomplete="off" type="text" name="card.holder" class="wpwl-control wpwl-control-cardHolder" placeholder="Card holder">
            </div>
        </div>
        <div class="wpwl-group wpwl-group-cvv wpwl-clearfix">
            <div class="wpwl-label wpwl-label-cvv">CVV</div>
            <div class="wpwl-wrapper wpwl-wrapper-cvv">
                <input autocomplete="off" type="tel" name="card.cvv" class="wpwl-control wpwl-control-cvv" placeholder="CVV">
            </div>
        </div>
        <div class="wpwl-group wpwl-group-submit wpwl-clearfix">
            <div class="wpwl-wrapper wpwl-wrapper-submit">
                <button type="submit" name="pay" class="wpwl-button wpwl-button-pay">Pay now</button>
            </div>
        </div>
        <input type="hidden" name="shopperResultUrl" value="https://eu-test.oppwa.com/v1/checkouts/{checkoutId}/payment">
        <input type="hidden" name="card.expiryMonth" value="">
        <input type="hidden" name="card.expiryYear" value="">
    </form>
</div>
 Imprint
|
Data protection and privacy
© 2025 J.P. Morgan Mobility Payments Systems GmbH. All rights reserved.