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 process 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 | Checkout token associated with payment. | guid |
| transactionReference | Transaction identifier, that must be used by the end-customer while initiating transaction with 'Pre-payment' and 'Pay upon invoice' payment options. | string |
| transactionStatus | Defines current status of the initial transaction. | string |
| message | Defines result of the submitted payment. | string |
Error Handler
Description
This callback function is used to trigger any logic to be executed upon the payment and user journey having not been able to start / initiated. When the SmartPay SDK can not be initiated correctly, this callback is triggered.
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_TIMEOUT | checkoutToken or transactionId is expired. Refer here for more details. | No |
Before Submit Handler
Description
Callback is being triggered, when a payment method has been selected by the end-customer in the SmartPay widget and he/she clicks on 'Confirm' button.
Promise<boolean> | boolean onBeforeSubmit ( data );
Parameters
SmartPay widget must provide 'data' object into the callback function as an argument. 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 | Checkout Token associated with payment. |
| 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 belong 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 | Checkout Token associated with payment. |
| 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> | boolean If callback function returns true, the the payment need to be continued. If callback function returns false or non-boolean value or undefined, the the payment need to be prevented. |
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 gets 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 issued by the KontoCloud. | 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> | boolean If callback function returns true, then deletion of the stored payment option must be continued. If callback function returns false or non-boolean value or undefined, then deletion of the stored payment option must 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 | Checkout Token associated with payment. |
| 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 belong 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 | Checkout Token associated with payment. |
| 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 |