init

In this mandatory step, the Klarna Payments library is initialized. The method expects an option with the client_token received when creating the session.

init
Parameters
options (Object)
Name Description
options.client_token String The client token received when creating the session.
Throws
  • InvalidClientTokenError: If options.client_token is not a valid JSON Web Token.
Example
try {
  Klarna.Payments.init({
    client_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.dtxWM6MIcgoeMgH87tGvsNDY6cHWL6MGW4LeYvnm1JA'
  })
} catch (e) {
  // Handle error.
}

load

In this step the actual credit form is shown to the customer. First a pre-assessment is made, based on the known order details, to see if Klarna might offer the customer credit. If the pre-assessment passes, the credit form is rendered.

As a merchant, you choose when to present the form to the customer, probably when the customer selects Klarna Credit as payment method.

If you have received new or additional information about the customer (e.g. billing address) you can call the method again, which will update the current session.

load
Parameters
options (Object)
Name Description
options.container (HTMLElement | String) The container in which to render the application. Should be an HTML element or valid CSS selector.
options.payment_method_category String The category of payment methods that should be loaded.
options.preferred_payment_method String? The payment method to be pre-selected, if possible.
data (Object?) An optional object with data to update on the session.
callback (load~callback) A function that will be called when the pre-assessment is completed.
Throws
  • ApplicationNotInitializedError: If called without options and 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 when required.
  • PaymentMethodCategoryNotSupportedError: If options.payment_method_category is not supported.
  • PreferredPaymentMethodNotSupportedError: If options.preferred_payment_method is not supported.
Example
try {
  Klarna.Payments.init({ client_token: '...' })
  Klarna.Payments.load({
    container: '#klarna-payments-container',
    payment_method_category: 'category'
  }, { // Data to be updated
    billing_address: {
      // ...
    }
  }, function (res) { // load~callback
    // ...
  })
} catch (e) {
  // Handle error. The load~callback will have been called
  // with "{ show_form: false }" at this point.
}

load~callback

Called with the result of the load operation.

load~callback
Parameters
res (Object) Response
Name Description
res.show_form Boolean A boolean indicating the result of the pre-assessment.
res.error Object Only available in case of solvable errors.
Example
Positive pre-assessment -> { show_form: true }
Negative pre-assessment -> { show_form: false }
Example error -> { show_form: true, error: { invalid_fields: ["billing_address.email"] } }

loadPaymentReview~callback

Called with the result of the loadPaymentReview operation.

loadPaymentReview~callback
Parameters
res (Object) Response
Name Description
res.show_form Boolean A boolean indicating the result of the pre-assessment.

loadPaymentReview

If your checkout offers the customer an opportunity to review the order after the payment step (e.g. an order review page) it can make sense to present the payment method the customer selected on a previous page. This gives the customer a change to review the payment method and its terms to the user.

Klarna supports this by offering a payment review widget in which all relevant data around the customers payment method is presented.

Note: This feature is currently only available in the United States.

loadPaymentReview
Parameters
options (Object)
Name Description
options.container (HTMLElement | String) The container in which to render the application. Should be an HTML element or valid CSS selector.
callback (loadPaymentReview~callback) A function that will be called when the operation is completed.
Throws
  • ApplicationNotInitializedError: If called without options and 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.
Example
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.
}

authorize

This is the final credit risk assessment. As a merchant, you will not handle the potentially sensitive information that is entered in the credit form, this information is only available to Klarna. A successful authorization guarantees that the order can be created within 60 minutes.

Upon authorizing the credit, Klarna will validate the input in the credit form. If there are any errors, the relevant fields are highlighted and corresponding error messages are shown.

The authorization is made with a client side call to authorize. The result of a successful authorization is an authorization_token that should be used when creating the order. The response object also includes a key called show_form, which indicates whether or not the Klarna payment option should remain available (i.e. success case or errors that the user can resolve) or if you should remove the option entirely (i.e. final rejection).

When new or additional information about the customer is received (e.g. billing address), authorize can be called again, which will update the current session.

Please note that the authorize call may trigger additional information requirements on the consumer. The callback can therefore be instant, take a very long time (i.e. the time it takes the customer to complete the form), or may never happen (if the consumer drops out). The integration should therefore not be relying on an immediate response, and should not implement any timeouts on the merchant side, but wait for the callback function to be called.

Also, to ensure that customers understand that some processing is going on in the background, when authorize is called, it should be visually shown that something is happening (e.g. a spinner in the button that triggered the authorize call).

authorize
Parameters
options (Object)
Name Description
options.payment_method_category String The payment method category that was provided in the previous load call.
options.auto_finalize Boolean? An optional flag used 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 that will be called when authorization is completed.
Throws
  • PaymentMethodCategoryOrInstanceIDRequiredError: If options.payment_method_category is not provided when required.
  • PaymentMethodCategoryNotSupportedError: If options.payment_method_category is not supported.
  • ApplicationNotLoadedError: If called prior to load .
Example
try {
  Klarna.Payments.authorize({
    payment_method_category: 'category'
  }, { // Data to be updated
    billing_address: {
      // ...
    }
  }, function (res) { // authorize~callback
    // ...
  })
} catch (e) {
  // Handle error. The authorize~callback will have been called
  // with "{ show_form: false, approved: false }" at this point.
}

authorize~callback

Called with the result of the authorize operation.

authorize~callback
Parameters
res (Object) Response
Name Description
res.authorization_token String If credit is approved, needed to place order.
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_required Boolean A boolean indicating that the finalize method should be called in order to complete the authorization.
res.error Object Only available in case of solvable errors.
Example
A successful authorization -> { authorization_token: "b4bd3423-24e3", approved: true, show_form: true }
An authorization that requires finalization -> { approved: true, show_form: true, finalize_required: true }
A rejected authorization with solvable errors -> { approved: false, show_form: true, error: { invalid_fields: ["billing_address.email"] } }
A rejected authorization (non-resolvable) -> { approved: false, show_form: false }

reauthorize

If your checkout offers the customer to change any details of the order (e.g. customer details, shopping cart, shipping, discount code, gift cards etc.) after the payment step (e.g. an order review page) you will need to reauthorize if the customer changes anything.

This as the authorization_token you received originally is only valid for that specific state of the order (e.g. changes to the order will be rejected, if not authorized).

On such an order review page you typically don't have a payment selector, and hence the standard way of authorizing (init + load + authorize) is not possible here. Reauthorize can be used without a payment selector, and any necessary customer communication will be handled in fullscreen modals.

We recommend that you trigger reauthorize as few times as possible, but as many times as necessary. We would suggest that you store when a change has happened, and if so is the case, you trigger reauthorize once the customer clicks on "Complete order" (i.e. only if a change has happened). As with authorize, you can provide an optional update object including all order details. It is however also possible to chain this in a way where you start with a server-side session update per REST API, followed by an empty client-side call to reauthorize.

Please note that the reauthorize call may trigger confirmation from the consumer on changed financing details. The callback can therefore be instant, take a very long time (i.e. the time it takes the customer to complete the form), or may never happen (if the consumer drops out). The integration should therefore not be relying on an immediate response, and should not implement any timeouts on the merchant side, but wait for the callback function to be called.

Also, to ensure that customers understand that some processing is going on in the background, when reauthorize is called, it should be visually shown that something is happening (e.g. a spinner in the button that triggered the reauthorize call).

If on a different page than where you originally ran init, Klarna Payments needs to be initialized.

reauthorize
Parameters
options (Object)
Name Description
options.payment_method_category String The payment method category of the previously authorized payment method.
data (Object?) An optional object with data to update on the session.
callback (reauthorize~callback) A function that will be called when the reauthorization is completed.
Throws
  • ApplicationNotInitializedError: If called prior to init .
  • PaymentMethodCategoryNotProvidedError: If options.payment_method_category is not provided when required.
  • PaymentMethodCategoryNotSupportedError: If options.payment_method_category is not supported.
Example
try {
  Klarna.Payments.init({ client_token: '...' })
  Klarna.Payments.reauthorize({
    payment_method_category: 'category'
  }, { // Data to be updated
    billing_address: {
      // ...
    }
  }, function (res) { // reauthorize~callback
    // ...
  })
} catch (e) {
  // Handle error. The reauthorize~callback will have been called
  // with "{ show_form: false, approved: false  }" at this point.
}

reauthorize~callback

Called with the result of the reauthorize operation.

a) Successful reauthorize Response: { approved: true, authorization_token: string } Continue with the order placement.

b) Rejected reauthorize Response: { approved: false } Do not do anything. As the failed reauthorize is triggered by a customer change, the customer might want to change the details back in order to be eligible for credit again. Appropriate error messages will be handled by Klarna.

Note: Reauthorize currently also includes { show_form: true/false } in the response. This is deprecated and shall not be used. Instead only a { approved: true, authorization_token: string } response should require any action for reauthorize.

reauthorize~callback
Parameters
res (Object) Response
Name Description
res.authorization_token String If credit is approved, needed to place order.
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.error Object Only available in case of solvable errors.
Example
A successful reauthorization -> { authorization_token: "b4bd3423-24e3", approved: true }
A rejected reauthorization due to an invalid update -> { approved: false, error: { invalid_fields: ["billing_address.email"] } }
A rejected or aborted reauthorization -> { approved: false }

finalize~callback

Called with the result of the finalize operation.

finalize~callback
Parameters
res (Object) Response
Name Description
res.authorization_token String If credit is approved, needed to place order.
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.error Object Only available in case of solvable errors.
Example
A successful finalization -> { authorization_token: "b4bd3423-24e3", approved: true, show_form: true }
A rejected finalization due to an invalid update -> { approved: false, show_form: true, error: { invalid_fields: ["billing_address.email"] } }
A rejected or aborted finalization -> { approved: false, show_form: false }

finalize

A finalization will be required for some payment methods. Whenever a finalization is required, the authorize call will return finalize_required: true. The finalize response will then contain the authorization token if the user successfully completes required steps.

The finalization should be done just before the purchase is completed, meaning the last step in a multi-step checkout.

finalize
Parameters
options (Object)
Name Description
options.payment_method_category String The payment method category of the authorized payment method.
data (Object?) An optional object with data to update on the session.
callback (finalize~callback) A function that will be called when the finalization is completed.
Throws
  • ApplicationNotInitializedError: If called prior to init .
  • PaymentMethodCategoryNotProvidedError: If options.payment_method_category is not provided when required.
  • PaymentMethodCategoryNotSupportedError: If options.payment_method_category is not supported.
Example
try {
  Klarna.Payments.init({ client_token: '...' })
  Klarna.Payments.finalize({
    payment_method_category: 'category'
  }, { // Data to be updated
    billing_address: {
      // ...
    }
  }, function (res) { // finalize~callback
    // ...
  })
} catch (e) {
  // Handle error. The finalize~callback will have been called
  // with "{ show_form: false, approved: false }" at this point.
}

on~eventHandler

Called whenever the associated event is emitted inside Klarna Payments.

on~eventHandler
Parameters
payload (Object?) The payload may vary between events. See the list of supported events for details.

on

Registers an event handler for the given eventName. The events are triggered internally in Klarna Payments. The supported events are:

  • heightChanged: Emitted when the height of the iframe changes. The registered event handler is called with the new height (in pixels) as a number (integer).
  • fullscreenOverlayShown: Emitted when the fullscreen overlay is shown.
  • fullscreenOverlayHidden: Emitted when the fullscreen overlay is hidden.
on
Parameters
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.
Throws
  • EventNotSupportedError: If trying to register an unsupported event.
Example
Klarna.Payments.on('heightChanged', function (newHeight) {
  console.log('got new iframe height', newHeight)
})

off

Unregisters an event handler for the given eventName.

off
Parameters
eventName (String) The name of the event from which you want to unsubscribe.
eventHandler (on~eventHandler?) The function that was previously registered for the eventName . Omit if you want to unregister all handlers for the eventName .
Example
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')