Web SDK

Last changes: 07-15-2021

Include stylesheet and SmartPay Subscription JavaScript Library

Include bronson stylesheet

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

The BronsonStylesheet file must be stored locally on your server.

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

Get the Bronson Toolkit: https://bronson.vwfs.tools/

SmartPay Subscription Widget Components are rendered using Bronson CSS classes. This assumes that the Bronson 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>

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) => { ... }
});

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

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(beforeSubmitPaymentData) { return true; },
            onBeforeDeleteSpo: function(beforeDeleteSpoData) { return true; }
        });
     
        return true;
    }
 
    // Loading the bundle will initialize the smart pay subsription 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);
        }
    });
})();

Previous

Next