Web SDK handler

Last changes: 02-21-2022

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

ParameterDetailsType

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

Unique transaction identifier.

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

Unique transaction identifier, if any

 

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

Unique transaction identifier.

 

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.

 

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

 usedForRecurringPaymentsFlag shows if the payment option is used in subscriptions.boolean
 recurringPaymentsAn array of objects, providing the merchant with information about where the storedPaymentOptionReference is used.  array
  objectTypeDescribes the object (e.g. subscription, payment serie) that uses the storedPaymentOptionReferencestring
  objectIdProvides 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.

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

ParameterDetails
data 
 transactionIdUnique transaction identifier, if any

 

name

Display name of the payment option which has been stored.
 codeCode of the payment option which has been stored.
 carrierNumber

Masked carrier number of the payment instrument which has been stored.

E.g.: 401288****1881

 isDefaultFlag showing whether the stored payment option was chosen by the consumer to be the default one,
 referenceStored payment option reference.
 isExpiredIn 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

 storedPaymentOptionDataContains payment method specific information used for storing the payment option. Currently used for SEPA only. 
  mandateReferenceSepa mandate reference
  mandateSignedDate

Mandate signature date, format: YYYY-MM-DD

  mandateSignedTime

Mandate signature time, format: HHmmss

Guest payment option selected 

 ParameterDetails
data 
 transactionIdUnique transaction identifier = reconciliation reference of authorize transaction.
 

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