Skip to content

Klarna payments

Target Audience: Developers

Introduction

Attention

The feature and the documentation is still under development. Do NOT start implementation before talking to Adeprimo.

This document describes how you integrate Klarna Payments in your web applications using the Payway API. The integration towards Payway is API-based which means you do not need a Payway session to use this integration, an access token is sufficient.

Before you start planning and writing code

Please read Getting started checklist

Requirements and limitations

  • At the moment only available in Sweden
  • An access token for the user about to do the purchase with scope /external/klarna_payments/w
  • HTTPS on the purchase page
  • Only direct debit is supported

Initial Payment flow

Flow

1. User requests purchase

The user must actively choose to purchase a package before you render request a purchase session. This can for example be done simply by having simply informing the user that he has hit the paywall and needs to buy access buy clicking a button. You should NOT create a purchase session each time the user hits the Paywall.

2. Create session

To proceed with rendering the Klarna payment box you must first create a session for a package or campaign using the Payway API. You also supply a confirmation url where the user should be sent at the end of the purchase flow.

A session is valid for 48 hours.

Environment Endpoint URL
Stage https://payway-api.stage.adeprimo.se/external/api/v1/klarna_payments/create_session
Production https://backend.worldoftulo.com/external/api/v1/klarna_payments/create_session

Request parameters

The request should be sent as application/json.

Parameter Description
code The code of the package or campaign e.g. adeprimo_digital
period_type limited or recurring. Always set to recurring for campaigns
confirmation_url URL to your confirmation page for the customer

Response

The response is sent as application/json.

Parameter Description
klarna_payments_session_id The id of the session that you just created. This is needed when you place the order. You should store this in the user's session in your backend
klarna_client_token You need to use this token when you build the Klarna Payments Widget on your site

Example of a successful response:

1
2
3
4
5
6
{
  "item": {
    "klarna_payments_session_id": "5aba2ca36fc93613f8000012",
    "klarna_client_token": "eyJhbGciOIJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjAwMDAwMDAwMDAtMDAwMDAtMDAwMC0wMDAwMDAwMC0wMDAwIiwidXJsIjoiaHR0cHM6Ly9jcmVkaXQtZXUua2xhcm5hLmNvbSJ9.A_rHWMSXQN2NRNGYTREBTkGwYwtm-sulkSDMvlJL87M"
  }
}

Errors

The error response is sent as application/json and will have a http status code ranging between 400-500.

An error message will contain these properties in every response. Some error responses will add additional data for troubleshooting. Third party errors from Klarna for example. See below for a couple of examples of typical errors received.

Error example

1
2
3
4
5
6
{
  "code": "error_code",
  "field": "field",
  "message": "error message",
  "correlation_id": "correlation_id only available for third party errors"
}

Parameter Description
code type of error
field the field the error concerns, can refer to a parameter or concept
message the error message
401 Unauthorized
Code Description
unauthorized Access token has no identity and is not tied to a logged in user
400 Bad request
Code Field Description
configuration_error klarna_payments Klarna payments provider not configured for title
invalid_parameter confirmation_url Confirmation url must for example be absolute
404 Not found
Code Field Description
configuration_error klarna_payments Session not found or provider misconfiguration
not_found packageble foobar Package or campaign does not exist
not_found no title found for packageable package_code No title set on package
500 Third party error
Code Field Description Correlation id
third_party_error klarna payments api Third party error received from Klarna. Errors from klarna contain a correlation id used when contacting their support Used to identify error at Klarna

3. Render purchase page

Once you have the klarna_client_token you are ready to build the Klarna Payment Widget on your purchase page. More details on how you do this can be found in the Klarna documentation. The Example app also contains a working implementation of the Klarna Payment Widget.

4. Authorize purchase against Klarna

When the user presses the buy button you must, using javascript, perform an authorize call to Klarna. You will in return get a authorization_token.

Example without error handling:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
var btn = document.getElementById("approve_purchase");
var klarna_authorization_token_input = document.getElementById('klarna_authorization_token');
var form = document.getElementById('authorize_form');

btn.addEventListener("click", function() {
Klarna.Payments.authorize({
    payment_method_category: "direct_debit"
},{}, function (response) {
    if(response.approved) {
        klarna_authorization_token_input.value = response.authorization_token;
        form.submit(); //post the authorization token to your backend
    }
});

More details on how to do the authorize call can be found in Klarna documentation. The Example app also contains a working example of how to do the authorize call.

Note that you should not create any customer token yourself (3.3 Create Customer Token). You should simply forward the authorization token to the Payway API Place Order.

5. Place order

Once you you have done the authorize call and sent the authorization token to you backend you are ready to place the order. The place order will charge the Payment from Klarna and create the order, payment and subscription in Payway.

Environment Endpoint URL
Stage https://payway-api.stage.adeprimo.se/external/api/v1/klarna_payments/place_order
Production https://backend.worldoftulo.com/external/api/v1/klarna_payments/place_order

Request parameters

The request should be sent as application/json.

Parameter Description Default value Required
klarna_authorization_token The authorization token you aquired in step 4. Yes
klarna_payments_session_id The id of the session that was returned to you in the create_session call in step 2. Yes
browser_ip The ip of the browser e.g. 81.208.13.50 Yes
browser_language The browser language e.g. sv-SE Yes
browser_user_agent The user agent Yes
traffic_source The source of the purchase. E.g. facebook, web. Traffic sources need to be setup in PAP No
raise_on_ssn_already_taken_error If set to true the request will raise an exception if the ssn is already taken by another user in Payway true No
raise_on_ssn_already_set_error If set to true the request will raise an exception if an ssn update is performed on a user with an ssn false No
raise_on_account_update_error If set to true the request will raise an exception if errors are encountered during an account update. An account update consists of "name", "birth date" and "account address" updates. false No
raise_on_delivery_address_error If set to true the request will raise an exception if errors are encountered during the order delivery address validation false No

Response

The response is sent as application/json.

Parameter Description
redirect_url Url where you should redirect the user

Example:

1
2
3
4
5
{
  "item": {
    "redirect_url": "http://url.to.klarna.se"
  }
}

Errors

The error response is sent as application/json and will have a http status code ranging between 400-500.

An error message will contain these properties in every response. Some error responses will add additional data for troubleshooting. Third party errors from Klarna for example. See below for a couple of examples of typical errors received.al data for troubleshooting. Third party errors from Klarna for example.

Parameter Description
code type of error
field the field the error concerns, can refer to a parameter or concept
message the error message

Error example

1
2
3
4
5
6
{
  "code": "error_code",
  "field": "field",
  "message": "error message",
  "correlation_id": "correlation_id only available for third party errors"
}

401 Unauthorized
Code Description
unauthorized Access token has no identity and is not tied to a logged in user
400 Bad request
Code Field Description
configuration_error klarna_payments Klarna payments provider not configured for title
404 Not found
Code Field Description
configuration_error klarna_payments Session not found or provider misconfiguration
not_found limited klarna period for packageble package_code Requested package/campaign has no limited klarna purchase period configured
not_found recurring klarna period for packageble package_code Requested package/campaign has no recurring klarna purchase period configured
409 Conflict
Code Field Description
payments_session_expired payment session expired Session expired (48h)
already_exists national_identification_number Ssn already exists in Payway
update_account address/birth_date/name Error occurs when trying to merge Klarna account info with Payway
set_order_delivery_address delivery_address Error occurs when trying to merge Klarna account info with Payway
traffic_source_not_belonging_to_organisation traffic_source Traffic source is not set up in PAP
500 Third party error
Code Field Description Correlation id
third_party_error klarna payments api Third party error received from Klarna. Errors from klarna contain a correlation id used when contacting their support Used to identify error at Klarna
403 - Payment method failed

Reasons for this error can be:

  • Customers are in debt when Klarna does an external lookup.
  • Customers are in debt to Klarna.
  • Customer did not pass Klarna risk policy assessment.

Action taken due to error

  • Subscription terminated

500 Internal server error

Code Message Description
internal_server_error Ooops something unexpected happened This is an unhandled error. Contact support

6. Update account details

After the order has been placed we fetch account and order information from klarna and complement the Payway account with available properties. See below for more info on what paramters are updated.

Information updated

Property Description
Account address The billing address of the klarna order
Name First name and last name as set in the billing address of the klarna order
Birth date Birth date of the customer attached to the klarna order
Ssn National identification number of the customer attached to the klarna order

Errors

If either of the parameters below are set to true and an exception occurs in either operation the purchase will not be completed.

Parameter Description Default value
raise_on_account_update_error If set to true the request will raise an exception if errors are encountered during account update false
raise_on_delivery_address_error If set to true the request will raise an exception if errors are encountered during the order delivery address validation false

7. Redirect the user to Klarna

You should redirect the user to the redirect uri that you received in the previous step. The reason for this redirect is to allow Klarna to recognize the customer's device in future interactions. The user does not need to do any interaction in this step.

8. Show confirmation

After visiting Klarna the browser will be sent to the confirmation url that you gave in step 2.

Example app

Sample app