Web SDK

Include stylesheet and SmartPay Subscription JavaScript Library

Include SmartPay Stylesheet

<link href="smartpay-style.css" rel="stylesheet">

The SmartPay Stylesheet file must be stored locally on your server.

Please make sure that SmartPay Subscription is allowed to access resources related to the SmartPay Stylesheet (e.g. fonts) by configuring cross-origin resource sharing in your webserver (Access-Control-Allow-Origin).

info

SmartPay Subscription Widget Components are rendered using SmartPay CSS classes. This assumes that the SmartPay Stylesheets are already loaded by the merchant site. The styles can be downloaded from the resource links above.

There is no support right now for more granular styling.

Include SmartPay Subscription WebSDK

<script src="https://...//sdk.js" type="text/javascript"></script>

info

Please check Sandbox vs. Production page for latest url.

Render SmartPay Subscription Widget

Create containers

<div id="root_container_id"></div>
<div id="submit_button_container_id"></div>
<div id="selected_payment_container_id"></div> <!-- optional -->

Container	Description	Mandatory
root_container_id	Root container where the payment options selector will be rendered.	Yes
submit_button_container_id	Root element of the container where the submit button will be rendered.	Yes
selected_payment_container_id	Id of the root element of the container where the currently selected payment option information will be rendered. Use this container if you want to display the selected payment option on a confirmation page	No

Initialize widget instance

Loading the bundle will initialize the SmartPay Subscription app instance and attach it to the window object.

const smartPaySubscriptionsApp = window.SmartPaySubscriptionsSdk;

Render widget into the container

Calling this function will trigger the SmartPay Subscription widget to load the valid payment methods for the given Subscription or Payment Serie and rendering it into the provided container.

subscriptionsSdk.renderWidget({
    containerId: 'root_container_id',
    selectedPaymentContainerId: 'selected_payment_container_id',
    submitButtonContainerId: 'submit_button_container_id',
    objectId: 'object-id',
    objectType: 'object-type',
    termsAndConditionsText: 'Terms and conditions text',
    checkboxText: 'I agree with terms and conditions',
    buttonText: 'Continue',
    successHandler: () => { ... },
    errorHandler: (errorCode, message) => { ... },
    onBeforeSubmit: (beforeSubmitPaymentData) => { ... },
    onBeforeDeleteSpo: (beforeDeleteSpoData) => { ... }
});

Configuration Options

Field	Description	Data Type	Mandatory
containerId	Id of the root container where the payment options selector will be rendered.	string	Yes
submitButtonContainerId	Id of the root element of the container where the submit button will be rendered.	string	No
selectedPaymentContainerId	Id of the root element of the container where the currently selected payment option information will be rendered. Use this container if you want to display the selected payment option on a confirmation page.	string	Yes
objectType	type of the object subject to storing the payment option Possible values: "subscription", "payment-series"	string	Yes
objectId	Id of the subscription or the payment serie	string	Yes
termsAndConditionsText	Free text, which will be displayed in the section Terms and Conditions if provided. Additional logic will be activated, where the end-user will be required to agree with these terms and conditions before continuing.	string	No
checkboxText	Label text which will be displayed next to the checkbox in the section of Terms and Conditions	string	No
buttonText	Text of the button displayed in the section of Terms and Conditions	string	No
successHandler	Use this function to trigger any logic to be executed upon a successful subscription update (storage of the payment instrument).	function	Yes
errorHandler	Use this function to trigger any logic to be executed upon an unsuccessful subscription update.	function	Yes
onBeforeSubmit	Optional function to handle additional checks before the storage of the payment option gets started. The callback is triggered when the end-user clicks on the 'Confirm' button on the widget.	function	No
onBeforeDeleteSpo	Optional function to handle additional checks before the selected stored payment option gets deleted. The callback is triggered when the end-user clicks the 'Remove' button near the stored payment option he decided to delete.	function	No
onWidgetRendered	Whenever the widget is successfully loaded, this JS callback will be visible in the console log.	function	No

"onWidgetRendered" optional callback

The "onWidgetRendered" callback is an optional JavaScript function that signals when the SmartPay widget has been successfully loaded and rendered in the user's browser. This callback is particularly useful for enhancing the integration's reliability on slower connections, ensuring that merchants are informed when the widget is ready.

Upon each successful render of the SmartPay widget, the "onWidgetRendered" callback is triggered. This callback is logged and returned to the merchant's website, confirming that the widget is operational. In scenarios where there might be network delays or slow connections, merchants can leverage this callback to implement additional UI elements, such as a loading icon or message, to inform users that the transaction process is still ongoing.

To view the "onWidgetRendered" callback information in the Event Log within the SDK Testing Tool, ensure that the "Handle onWidgetRendered callback" checkbox is enabled. This will allow you to monitor and verify the callback during the testing phase.

For further details on how to handle the "onWidgetRendered" callback, refer to the Widget Rendered Handler.

Introduce success handling

When the payment instrument details has been submitted and added to the Subscription, the user journey is completed. SmartPay Subscription widget notifies the merchant's website about it via the 'successHandler' callback function which needs to be provided.

function successHandler(){
 
   // adding SPO to the Subscription completed successfully
   
  }

 
subscriptionsSdk.renderWidget({
   objectId: 'object-id',
   objectType: 'object-type',
   containerId: 'root_container_id',
   successHandler: successHandler
});

Introduce error handling

Errors in the Subscription SmartPay Widget need to be handled through the callback function provided into the renderPaymentSelection method.

The errorCode parameter contains the actual error code as per the table below. The second parameter of the callback provides the exact message of the error to be used in debugging and as reference for our customer support.

function errorHandler(code, message) {
   console.error(code + ': ' + message);
 
   // handle the error
 
}
 
subscriptionsSdk.renderWidget({
   objectId: 'object-id',
   objectType: 'object-type',
   container: "root_container_id",
   successHandler: successHandler,
   errorHandler: errorHander
});

Error code	Description
ERROR_UPDATE_SUBSCRIPTION	Error while updating the subscription/payment serie
ERROR_VALUE_TYPE	'objectType': Incorrect value provided
ERROR_REFERENCE	Cannot find a subscription or a payment-serie with the provided value
ERROR_PROCESSING	An error occurred during the processing

Complete integration sample

(function () {
 
    // Adding SPO completed unsuccessfully 
    function errorHandler(errorCode, error) {
        // handle failed SPO storing
        console.error({code: errorCode, message: error});
    }
 
    // Adding SPO completed successfully
    function successHandler() {
        // handle success logic here
    }
 
    function tryRenderSubscriptionForm(objectId) {
         subscriptionsSdk.renderWidget({
            containerId: "root_container_id",
            selectedPaymentContainerId: "selected_payment_container_id",
            submitButtonContainerId: "submit_button_container_id",
            objectId: objectId, // could be a subscriptionId or a PaymentSerieId
            objectType: objectType, // either "subscription" or "payment-series"
            termsAndConditionsText: "Terms and conditions text",
            checkboxText: "I agree with terms and conditions",
            buttonText: "Continue",
            successHandler: completeHandler,
            errorHandler: errorHandler,
            onBeforeSubmit: function(data) { return true; },
            onBeforeDeleteSpo: function(data) { return true; },
            onWidgetRendered: function(data) { return true; }
        });
     
        return true;
    }
 
    // Loading the bundle will initialize the SmartPay Subscription app
    // instance and attach it to the window object.
    const smartPaySubscriptionsApp = window.SmartPaySubscriptionsSdk;
 
    document.getElementById("subscribe-button").addEventListener("click", function (e) {
        if (e.target) {
            // provide here objectId (subscriptionID or paymentSeriesId) received from the back-end
            tryRenderSubscriptionForm(objectId);
        }
    });
})();