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