Klarna payments - Implementation guide¶
Target Audience: Developers
Introduction¶
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
Initial Payment 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, and will be invalidated immediately if a successful purchase is made.
See Create Session API for details on performing the request.
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:
var btn = document.getElementById("approve_purchase");
var klarna_authorization_token_input = document.getElementById('klarna_authorization_token');
var form = document.getElementById('authorize_form');
var payment_method_category = 'direct_debit/pay_now or any of the payment methods available to you in your Klarna payments setup.'
btn.addEventListener("click", function() {
Klarna.Payments.authorize({
payment_method_category: payment_method_category
},{}, 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.
Trial order¶
If you want to sell a free campaign that transitions to a standard package please use Place trial order API.
Be aware that trial orders are only supported when initiating the klarna widget with direct debit.
Regular order¶
If you want to sell a regular campaign or package please use Place order API
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
{
"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_closed | payment session closed | Session has been closed due to a successful purchase |
| 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 |
| Mobile phone number | Mobile phone number of the customer attached to the klarna order |
| Delivery address | The delivery address of 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.
Errors¶
This API uses the common error conventions of the Payway API