Setup

Last changes: 04-12-2023

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

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

Snippet to Configure and Render the Payment Form

<script type="text/javascript"> (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); }
  
})(); </script>

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

Initializing the WebSDK 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

<script type="text/javascript">
  
  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); }
  
</script>

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

Initializing the WebSDK 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

<script type="text/javascript">
   
   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 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":', '');
   
   //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); }
   
</script>

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

Snippet to Configure and Render the Payment Form

<script type="text/javascript">
  
  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); }
  
</script>

4. Payment Form Configuration

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

Property	Required	Description
authorizationToken	Yes	Expects a new authorization token to collect and associate payment option details with.
callbackUrl	Yes	Expects 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.
confirmationUrl	No	Relevant 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.
paymentOptionCodes	Yes	The payment option code associated with the payment option chosen by the customer (see Payment Options).
locale	Yes	Expects ISO 639-1 for languages and ISO 3166-1 alpha-2 for countries.
paymentProviderMode	Yes	Expects either: test live Use "test" throughout development and testing, switching to "live" only for your production deployment.
submitButtonTitle	Yes	The specified text is shown on the submit button. Localization must be handled for this element by yourself.
onBeforeSubmit	No	A 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"
isStorable	No	Relevant 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
isStorableCaption	No	Relevant 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.
onFormLoaded	No	A function to handle any logic to be executed upon the form having been loaded.
onError	Yes	A function to handle any exception handling logic. By default all events should be handled generically and logged for later analysis.

Property	Required	Description
authorizationToken	Yes	The 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.
paymentOptionCodes	Yes	Array of payment options. Must contain only the "PAYPAL" option.
locale	No	Defines 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".
paypalButtonStyle	No	a JSON Object with the Desired "Button Styling" Options. More detailed description is provided in the below table.
paymentProviderMode	No	Defines 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.

"Button Styling" Options:

Property	Description
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

Property	Required	Description
apiURL	Yes	The KontoCloud WebAPI Base URL for the Specified Environment. Contact your Payment Solutions Specialist / Key Account Manager.
authorizationToken	Yes	The Payment Token is a Base64-Encoded JSON string returned by the "1.38 Init Authorize" or "1.53 Init Add Stored Payment Option" APIs.
paymentOptionCodes	Yes	Array of payment options. Must contain only the "BNKACCT" option.
locale	No	Defines 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".
submitButtonTitle	No	The Text shown on the Payment Form "Submit" Button. Any Text Localization must be hanged by the Integrator.
showLabels	No	Sets Visibility of Payment Form Input Elements Labels. "true" - Default, Enable Visibility of Input Labels "false" - Disable the Visibility of the Input Labels
showPlaceholders	No	Sets Visibility of Payment Form Input Elements Placeholders. "true" - Default, Enable Visibility of Input Placeholders "false" - Disable the Visibility of the Input Placeholders
iframeCss	No	String with CSS Notation to Style the Payment Form as desired.
iframeCssUrls	No	Array of Strings with the Absolute URLs to External CSS Files.
onBeforeSubmit	No	Defines 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
onError	No	Function to handle any Errors returned from Payment Provider.

Property	Required	Description
authorizationToken	Yes	The Payment Token returned by the "1.38 Init Authorize" Response.
paymentOptionCodes	Yes	Array of Payment Options supported for the PaymentsOS provider.
locale	No	Defines 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".

Previous

Next