Web SDK handler
Success Handler
Description
This callback function is used to trigger any logic to be executed upon the payment and user journey having been completed (successfully and unsuccessfully). When payment data has been submitted and processed by payment provider, user journey is completed and callback triggered.
void successHandler ( data );
Parameters
| Parameter | Details | Type |
|---|---|---|
| data | Object | |
| kind | Defines type of success handler. Can take one of the following values: | string |
CALLBACK: It is returned in case of payment process. | ||
ADD_METHOD_CALLBACK: It is returned in case of payment option registration process. | ||
| transactionId or checkoutToken | Payment identifier field. | string |
| transactionReference | Transaction identifier, that must be used by the end-customer while initiating transaction with 'Prepayment' and 'Pay Upon Invoice' payment options. | string |
| transactionStatus | Defines current status of the initial transaction. | string |
| message | Defines result of the submitted payment. | string |
| storedPaymentOptionReference | The stored payment reference showing the registered payment option. | string |
Error Handler
Description
This callback function is used to trigger any logic in the merchant system that needs to be executed upon any error that may be encountered by the SmartPay WebSDK workflow. The error codes listed below provide further insights on the step at which the error may have occurred.
void errorHandler ( errorCode, message );
Parameters
| Error code | Description | Consumer to select another payment method and retry |
|---|---|---|
| ERROR_INIT_PAYMENT | Error on payment initialization, consumer need to choose a different payment option. | Yes |
| ERR_CONFIG | Error while loading payment methods configuration or widget. | No |
| ERROR_INVALID_INPUT | Invalid configuration passed to renderWidget method. | No |
| ERR_PAYMENT_CALLBACK | Payment failed during Authorization or Capturing. This is a hard failure, recreation of transaction is required. | No |
| ERROR_INIT_STORE_PAYMENT_OPTION | Error while storing payment option, consumer need to choose a different payment option. | Yes |
| ERROR | Any other unhandled error. | No |
| ERROR_CHECKOUT_TOKEN_EXPIRED | checkoutToken or transactionId is expired. Refer here for more details. | No |
Before Submit Handler
Description
The onBeforeSubmit callback is triggered when the customer has selected a payment option in the SmartPay widget and confirms it by clicking the Confirm button. This allows you to run your own checks or business logic before the payment request is submitted to SmartPay. Typical use cases include validating checkout data, updating order records or logging analytics events.
Promise<boolean> | boolean onBeforeSubmit ( data );
Parameters
The handler receives a data object representing the customer's selected payment option. Depending on whether the customer is paying with a stored option or a guest option, different fields will be returned. This object can be used to identify the payment option and confirm that the correct details are being submitted.
Depending on the selection which end-user made in selector area, the data object can have two sets of data described in tables below.
Stored payment option selected
| Parameter | Details |
|---|---|
| data | |
| transactionId or checkoutToken | Payment identifier field. |
| name | Display name of the payment option which has been stored. |
| code | Code of the payment option which has been stored. |
| carrierNumber | Masked carrier number of the payment instrument which has been stored. E.g.: 401288****1881. |
| isDefault | Flag showing whether the stored payment option was chosen by the consumer to be the default one. |
| reference | Stored payment option reference, to be used as input for MIT authorize API method. |
| isExpired | In case of CC, shows whether the card is expired or not. |
| expiryDate | When stored payment option belongs to 'CC' group, this value provides the expiration date of the card. For non-CC payment methods value is empty string. Format: MM/YYYY |
| storedPaymentOptionData | Contains payment method specific information used for storing the payment option. Currently used for SEPA only. |
| mandateReference | SEPA mandate reference. |
| mandateSignedDate | Mandate signature date, format: YYYY-MM-DD |
| mandateSignedTime | Mandate signature time, format: HHmmss |
Guest payment option selected
| Parameter | Details |
|---|---|
| data | |
| transactionId or checkoutToken | Payment identifier field. |
| name | Display name of the payment option which has been selected. |
| code | Code of the payment option which has been selected. |
Return value
| Return value type | Return value description |
|---|---|
| Promise<boolean> | Returns true or a resolved Promise with true to let SmartPay continue with the payment submission. Returns false, undefined, or a non-boolean value to stop the submission. |
Important notes
The onBeforeSubmit callback only applies to payment methods that rely on the SmartPay widget's Confirm button. Examples include card payments and other methods that display an entry form directly inside the widget.
For payment methods that use their own provider-hosted buttons or popups (such as Apple Pay, Google Pay™, PayPal or certain Open Banking flows) the SmartPay Confirm button is not involved. Because of this, the onBeforeSubmit callback is not triggered for these flows. In such cases, customers interact directly with the provider and SmartPay receives the result afterward.
This distinction is important for integration design: merchants should not assume that onBeforeSubmit will run uniformly across all payment methods. Its availability depends entirely on whether the method uses the SmartPay widget's own submit action.
Related handlers
If you need to detect when a customer abandons the flow, use the Before Delete handler. The handler is called when:
- A customer dismisses the SmartPay widget.
- The customer navigates back from the card entry form.
- A provider popup (e.g., PayPal, Apple Pay, Google Pay™) is closed without completing the payment.
For provider-button methods where onBeforeSubmit is not supported, you can still use the onSelectionChanged handler. This lets you implement custom logic when a customer selects one of these payment methods, even if the submission itself is handled by the provider.
- Use
onBeforeSubmitto perform last checks or enrich order data just before SmartPay submits the payment. - Do not rely on it for all methods as it only works with in-widget flows.
- For provider-button methods (Apple Pay, Google Pay™, PayPal), implement your custom logic either via
onSelectionChangedor at method initialization, and use the cancel handler to track exits. - Plan your integration around per-method behavior: SmartPay ensures consistent status reporting through the Get Payment Status API, even if the
onBeforeSubmithandler is not triggered.
Before Delete Stored Option Handler
Description
When enableDeleteSpo parameter was provided into the renderWidget method with value true, the deletion of the consumer's stored payment options becomes available in the stored options list on the main screen. Once Delete button clicked, SmartPay Widget will check if the selected stored payment option is in use by consumer's subscriptions. Regardless of the usage check result, widget will trigger the onBeforeDeleteSpo callback function and provide Subscriptions information which use the selected stored option along with stored option reference.
Promise<boolean> | boolean onBeforeDeleteSpo ( data );
Parameters
SmartPay widget provides data object into the callback function as an argument.
| Parameter | Details | Type |
|---|---|---|
| data | Object | |
| storedPaymentOptionReference | Stored payment option reference. | string |
| usedForRecurringPayments | Flag shows if the payment option is used in subscriptions. | boolean |
| recurringPayments | An array of objects, providing the merchant with information about where the storedPaymentOptionReference is used. | array |
| objectType | Describes the object (e.g., subscription, payment serie) that uses the storedPaymentOptionReference | string |
| objectId | Provides the ID of the object | string |
Return value
| Return value type | Return value description |
|---|---|
| Promise<boolean> | If callback function returns true, the payment needs to be continued. If callback function returns false or non-boolean value or undefined, the payment needs to be prevented. |
Payment Method Selection Changed Handler
Description
This callback will be triggered, when the a payment method has been selected by the end-customer in SmartPay widget.
void onSelectionChanged ( data );
Parameters
SmartPay widget provides a data object into the callback function as an argument.
Depending on the selection which your consumer made in selector area, the data object can have two sets of data described in tables below.
Stored payment option selected
| Parameter | Details |
|---|---|
| data | - |
| transactionId or checkoutToken | Payment identifier field. |
| name | Display name of the payment option which has been stored. |
| code | Code of the payment option which has been stored. |
| carrierNumber | Masked carrier number of the payment instrument which has been stored. E.g.: 401288****1881 |
| isDefault | Flag showing whether the stored payment option was chosen by the consumer to be the default one. |
| reference | Stored payment option reference. |
| isExpired | In case of CC, shows whether the card is expired or not. |
| expiryDate | When stored payment option belongs to 'CC' group, this value provides the expiration date of the card. For non-CC payment methods value is empty string. Format: MM/YYYY |
| storedPaymentOptionData | Contains payment method specific information used for storing the payment option. Currently used for SEPA only. |
| mandateReference | SEPA mandate reference |
| mandateSignedDate | Mandate signature date, format: YYYY-MM-DD |
| mandateSignedTime | Mandate signature time, format: HHmmss |
Guest payment option selected
| Parameter | Details |
|---|---|
| data | - |
| transactionId or checkoutToken | Payment identifier field. |
| name | Display name of the payment option which has been stored. |
| code | Code of the payment option which has been stored. |
Widget Rendered Handler
Description
This callback function will be triggered to execute any logic both during the loading of the SmartPay widget and upon its successful rendering. This handler plays a critical role in managing and responding to different stages of the widget's lifecycle, ensuring that any required actions, such as updating the UI, logging events, or handling errors, are performed at the appropriate time. By leveraging this function, you can ensure a smoother user experience, particularly in scenarios where the loading process may take longer due to network conditions or other factors.
void onWidgetRendered ( data );
Parameters
| Parameter | Details | Type |
|---|---|---|
| data | Object | |
| transactionId (for payment transaction context) OR subscriptionId (for subscriptions context) | Unique transaction identifier. | guid |