Web SDK handler

Last changes: 04-26-2023

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 tiggered.

void successHandler ( data );

Parameters

Parameter

Details

Type

data

Object

kind

Defines type of success handler. Can take one of the following values:

Returned value	Condition
CALLBACK	It is returned in case of payment process.
ADD_METHOD_CALLBACK	It is returned in case of payment option registration process.

string

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 albe to start / initiated. When the SmartPay SDK can not be initiated correctly, this callback is tiggered.

void errorHandler ( errorCode, message );

Parameters

Parameter

Details

Type

errorCode

Code of the error occurred, can take one of the following values:

Error code	Description	Retry
ERROR_INIT_PAYMENT	Error on payment initialization, consumer need to choose a different payment option.	Yes
ERROR_INIT_STORE_PAYMENT_OPTION	Error while storing payment option, consumer need to choose a different payment option.	Yes
ERR_PAYMENT_CALLBACK	Payment failed during Authorization or Capturing. This is a hard failure, recreation of transaction is required.	No
ERR_CONFIG	Error while loading payment methods configuration or widget.	No
ERROR_INVALID_INPUT	Invalid configuration passed to renderWidget method.	No
ERROR	Any other unhandled error.	No

string

message

Error message.

string

These error codes will be discontinued with SmartPay 2.3 release:

Error code	Description
ERR_PAYMENT_CONFIG	Error while loading payment methods configuration.
ERROR_UNSUPPORTED_PAYMENT_OPTION	Error while rendering payment selection widget.
ERROR_PAYMENT_FORM	Error while rendering payment form.
ERROR_AUTHORIZE_KLARNA	Klarna authorization failed, initiated via Klarna WebSDK
ERROR_PAYPAL	Error while redirecting to completion of the paypal payment.
ERROR_FAILED_CALLBACK	Error while payment completion.
ERROR_FAILED_SEPA_MANDATE	Error while getting SEPA mandate details.
ERROR_CALLBACK	Payment failed during Authorization or Capturing.

Change of existing integration is not required, as these error codes are internally mapped to the remaining and handling logic remains as is.

Before Submit Handler

Description

Callback is beeing 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	Promise<boolean> \| boolean
Return value description	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.

Return value type

Promise<boolean> | boolean

Return value description

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' parmaeter 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 subsriptions. 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
	storedPaymentOprionReference		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	Promise<boolean> \| boolean
Return value description	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.

Return value type

Promise<boolean> | boolean

Return value description

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.

Document version 1.1

2021-07-09 - Payment Method Selection Changed Handler

2021-03-10 - Initial release

Previous

Next