Skip to main content

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 -->
ContainerDescriptionMandatory
root_container_idRoot container where the payment options selector will be rendered.Yes
submit_button_container_idRoot element of the container where the submit button will be rendered.Yes
selected_payment_container_idId 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 pageNo

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

FieldDescriptionData TypeMandatory
containerIdId of the root container where the payment options selector will be rendered.stringYes
submitButtonContainerIdId of the root element of the container where the submit button will be rendered.stringNo
selectedPaymentContainerIdId 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.stringYes
objectTypetype of the object subject to storing the payment option Possible values: "subscription", "payment-series"stringYes
objectIdId of the subscription or the payment seriestringYes
termsAndConditionsTextFree 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.stringNo
checkboxTextLabel text which will be displayed next to the checkbox in the section of Terms and ConditionsstringNo
buttonTextText of the button displayed in the section of Terms and ConditionsstringNo
successHandlerUse this function to trigger any logic to be executed upon a successful subscription update (storage of the payment instrument).functionYes
errorHandlerUse this function to trigger any logic to be executed upon an unsuccessful subscription update.functionYes
onBeforeSubmitOptional 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.functionNo
onBeforeDeleteSpoOptional 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.functionNo
onWidgetRenderedWhenever the widget is successfully loaded, this JS callback will be visible in the console log.functionNo

"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 codeDescription
ERROR_UPDATE_SUBSCRIPTIONError while updating the subscription/payment serie
ERROR_VALUE_TYPE'objectType': Incorrect value provided
ERROR_REFERENCECannot find a subscription or a payment-serie with the provided value
ERROR_PROCESSINGAn 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 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);
}
});
})();