Klarna Docs - Klarna payments SDK reference.

Klarna payments SDK reference.

This is the library reference for the Klarna payments Javascript SDK. Here you find a description of the different methods, their required parameters, and their returns.

This method initializes the Klarna payments library. It is mandatory and expects the client_token received when initiating a payment.

For more information about initializing the JavaScript SDK, see the Check out section.

The following is an example of this method:

JAVASCRIPT
try {
Klarna.Payments.init({
    client_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.dtxWM6MIcgoeMgH87tGvsNDY6cHWL6MGW4LeYvnm1JA'
})
} catch (e) {
// Handle error.
}

Initializing the Klarna Payments JS library.

The parameter for this method is the following:

options (Object)

Property NameDescription
options.client_token (String)The client token received when initiating a payment.

InvalidClientTokenError: If options.client_token is not a valid JSON Web Token.

This callback occurs with the result of the load() call.

For more examples of the potential responses, see the Displaying the widget article.

The following is an example of this method:

OutcomeResponse
Successful response{ show_form: true }
Error response{ show_form: false }

The parameters for this method are the following:

res (Object) Response

Property nameDescription
res.show_form (Boolean)If true, you should display the widget, if false you can decide to hide it from the user.
res.error (Object)If there are any adjustable errors, these are displayed here.

Display the Klarna widget in your checkout using the load() call.

For more information, see the Displaying the widget article.

The following is an example of this method:

JAVASCRIPT
try {
Klarna.Payments.init({ client_token: '...' })
Klarna.Payments.load({
    container: '#klarna-payments-container',
    payment_method_category: 'pay_later'
}, { // Data to be updated
    billing_address: {
    // ...
    }
}, function (res) { // load~callback

Calling the load() method to display the Klarna widget.

The parameters for this method are the following:

options (Object)

Property nameDescription
options.container (HTMLElement/String)The container to render the application. It should be an HTML element or a valid CSS selector.
options.preferred_payment_method (String)The payment method to be pre-selected, if possible.
options.payment_method_category (String)The category of payment methods to be loaded. Only one can be included. Using payment_method_category lets you load one payment method per widget. This value will later be useful to refer to the widget also when calling authorize().
  • ApplicationNotInitializedError: If load() is called without options and/or prior to init().
  • InvalidContainerSelectorError: If options.container is neither an HTML element nor a valid CSS selector.
  • PaymentMethodCategoryNotProvidedError: If options.payment_method_category is not provided as a parameter in the load() call.
  • PreferredPaymentMethodNotSupportedError: If options.preferred_payment_method is not supported.

This method only applies to the US market and is only relevant if you have a multi-step checkout with an order review page.

If your checkout enables the customer to review the order after the payment step, you can also share in this review page the payment method your customer selected previously. For this, Klarna offers a payment review widget.

The following is an example of this method:

JAVASCRIPT
try {
Klarna.Payments.init({ client_token: '...' })
Klarna.Payments.loadPaymentReview({
    container: '#klarna-payments-container'
}, function (res) { // loadPaymentReview~callback
    // ...
})
} catch (e) {
// Handle error. The loadPaymentReview~callback will have been called
// with "{ show_form: false }" at this point.

Using the loadPaymentReview() method.

The parameter for this method is the following:

options (Object)

Property nameDescription
options.container (HTMLElement/String)The container to render the application. Should be an HTML element or valid CSS selector.
  • ApplicationNotInitializedError: If called without options and/or prior to init().
  • OperationNotSupportedError: If the operation is not supported for the current purchase country.
  • InvalidContainerSelectorError: If options.container is neither an HTML element nor a valid CSS selector.

This call occurs with the result of the loadPaymentReview operation.

The parameter for this method is the following:

res (Object) Response

Property nameDescription
res.show_form (Boolean)A boolean indicating the result of the pre-assessment.

This callback occurs with the result of the authorize() call.

For more information, see the Get authorization section.

The following are examples of this method:

res (Object) Response

Successful authorization.{ authorization_token: "b4bd3423-24e3", approved: true, javascript show_form: true }
Authorization that requires finalization.{ approved: true, show_form: true, finalize_required: true }
Rejected authorization with fixable errors.{ approved: false, show_form: true, error: {invalid_fields: ["billing_address.email"] } }
Rejected authorization with no-fixable errors.{ approved: false, show_form: false}

The parameters for this method are the following:

res (Object) Response

Property nameDescription
res.authorization_token (String)If the purchase is approved, this token is needed to place an order or to create a customer token.
res.show_form (Boolean)A boolean indicating whether to keep showing the form or to remove it.
res.approved (Boolean)A boolean indicating the result of the credit assessment.
res.finalize (Boolean)A boolean indicating that the finalize method should be called in order to complete the authorization.
res.error (Object)Object specifying an error. Only available in case of fixable errors.

This call triggers the credit risk and fraud assessment in Klarna’s system to decide whether or not to accept the purchase.

For more information, see the Get authorization section.

A successful authorization guarantees that the order can be created within 60 minutes.

The following is an example of this method:

JAVASCRIPT
try {
Klarna.Payments.authorize({
    payment_method_category: 'pay_later'
}, { // Data to be updated
    billing_address: {
    // ...
    }
}, function (res) { // authorize~callback
    // ...
})

Using the authorize() call.

The parameters for this method are the following:

options (Object)

Property nameDescription
options.auto_finalize (Boolean)An optional flag to turn off auto-finalization for the direct bank transfer payment method.
data (Object)An optional object with data to update on the session.
callback (authorize~callback)A function to be called when the authorization is completed.
options.payment_method_category (String)The payment method category that was provided in the previous load call.
  • PaymentMethodCategoryNotSupportedError: If options.payment_method_category is not supported.
  • ApplicationNotLoadedError: If called prior to load().

This callback occurs with the result of a reauthorization.

The following are examples of this method:

Successful reauthorize{ authorization_token: "b4bd3423-24e3", approved: true }
Rejected reauthorize{ approved: false }
Rejected reauthorization due to an invalid update{ approved: false, error: { invalid_fields: ["billing_address.email"] } }

Reauthorize currently also includes { show_form: true/false } in the response. This is deprecated. Instead, only an { approved: true, authorization_token: string } response is correct for any action for reauthorizing.

The parameters for this method are the following:

res (Object) Response

Property nameDescription
res.show_form (Boolean)A boolean indicating whether to keep showing the form or to remove it.
res.authorization_token (String)If credit is approved, this token is needed to place an order or create a customer token.
res.approved (Boolean)A boolean indicating the result of the credit assessment.
res.error (Object)Only available in case of fixable errors.

You need to get a reauthorization if your customer made a change in the order. This applies to multi-step checkouts, where you offer a review page after selecting the payment method.

The authorization_token you received originally is only valid for that specific state of the order. If you attempt to place an order without doing a reauthorize, it will fail.

If the payment method widget is still visible, use a regular authorize() call instead.

We suggest you trigger reauthorize once the customer clicks to complete the order. As with authorize(), you can provide an optional update object including all order details. It is also possible to start with a server-side session update per REST API, followed by an empty client-side call to reauthorize. The reauthorize call may trigger your customer confirmation on changed financing details. The integration should wait for the callback function.

If it happens on a different page than where you originally ran init(), you need to initialize the SDK before doing reauthorize.

The following is an example of this method:

JAVASCRIPT
try {
Klarna.Payments.init({ client_token: '...' })
Klarna.Payments.reauthorize({
    payment_method_category: 'pay_later'
}, { // Data to be updated
    billing_address: {
    // ...
    }
}, function (res) { // reauthorize~callback
    // ...

Using the reauthorize() call.

The parameters for this method are the following:

options (Object)

Property nameDescription
data (Object)An optional object with data to update on the session.
callback (Object)A function to be called when the reauthorization is completed.
options.payment_method_category (String)The category of payment methods to be loaded. Only one can be included.
  • ApplicationNotInitializedError: If called prior to init().
  • PaymentMethodCategoryNotSupportedError: If options.payment_method_category is not supported.
  • PaymentMethodCategoryNotProvidedError: If options.payment_method_category is not provided when required.

This callback occurs with the result of the finalize() operation.

For more information, see the Finalize an authorization section.

This is only relevant if you have a multi-step checkout and are offering direct debit through Klarna’s widget.

The following are examples of this method:

OutcomeResponse
Successful finalization{ authorization_token: "b4bd3423-24e3", approved: true, show_form: true }
Rejected or aborted finalization{ approved: false, show_form: false }
Rejected finalization due to an invalid update{ approved: false, show_form: true, error: { invalid_fields: ["billing_address.email"] } }

The parameters for this method are the following:

res (Object) Response

Property nameDescription
res.show_form (Boolean)A boolean indicating whether to keep showing the form or to remove it.
res.authorization_token (String)If the purchase is approved, this token is needed to place an order or create a customer token.
res.approved (Boolean)A boolean indicating the result of the credit assessment.
res.error (Object)Only available in case of fixable errors.

Finalizing the authorization is required for some payment methods.

For more information, see the Finalize an authorization section.

This section is only relevant if you have a multi-step checkout and offer direct debit in the Klarna widget.

The following is an example of this method.

JAVASCRIPT
try {
Klarna.Payments.init({ client_token: '...' })
Klarna.Payments.finalize({
    payment_method_category: 'pay_later'
}, { // Data to be updated
    billing_address: {
    // ...
    }
}, function (res) { // finalize~callback
    // ...

Using the finalize() call.

The parameter for this method are the following:

options (Object)

Property nameDescription
data (Object)An optional object with data to update on the session.
callback (authorize~callback)A function to be called when the authorization is completed.
options.payment_method_category (String)The payment method category that was provided in the previous load() call.
  • ApplicationNotInitializedError: If called prior to init().
  • ApplicationNotLoadedError: If called prior to load().
  • PaymentMethodCategoryNotProvidedError: If options.payment_method_category is not provided when required.
  • PaymentMethodCategoryNotSupportedError: If options.payment_method_category is not supported.

This evenHnadler occurs whenever the associated event is emitted inside Klarna payments.

The parameter for this method is the following:

res (Object) Response

Property nameDescription
payload (Boolean)The payload may vary between events. See the list of supported events for details.

This method registers an event handler for the given eventName. The events are triggered internally in Klarna payments. The supported events are:

EventComment
heightChangedEmitted when the height of the iframe changes. The registered event handler is called with the new height (in pixels) as a number (integer).
fullscreenOverlayShownEmitted when the fullscreen overlay is shown.
fullscreenOverlayHiddenEmitted when the fullscreen overlay is hidden.

The following is an example of this method:

JAVASCRIPT
Klarna.Payments.on('heightChanged', function (newHeight) {
console.log('got new iframe height', newHeight)
})

Sample event listener definition for heightChanged.

The parameters for this method are the following:

NameDescription
eventName (String)The name of the event to which you want to subscribe.
eventHandler (on~eventHandler)The function that should be called when the event is emitted.

EventNotSupportedError: If trying to register an unsupported event.

This method unregisters an event handler for the given eventName.

JAVASCRIPT
var theEventHandler = function () { ... }
Klarna.Payments.on('heightChanged', theEventHandler)

// unregister this specific listener for heightChanged
Klarna.Payments.off('heightChanged', theEventHandler)

// unregister _all_ listeners for heightChanged
Klarna.Payments.off('heightChanged')

De-registering event listeners.

The parameters for this method are the following:

NameDescription
eventName (String)The name of the event to which you want to subscribe.
eventHandler (on~eventHandler)The function that was previously registered for the eventName. Omit if you want to unregister all handlers for the eventName.