Klarna payments - Implementation guide - new customer¶
Target Audience: Developers
Introduction¶
This document describes how you integrate Klarna Payments in your web applications using the Payway API when the customer does not have an account in Tulo Payway. You will still need an access token, but the access token will not require an identity.
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¶
Creating a session using the new customer approach is straight forward. All you need to worry about is performing the request using an access token that is NOT connected to an identity. 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 without account 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.
Placing an order using the new customer approach is pretty much the same as the existing customer one. Except you will need to supply a contact_email so we can create the account for you. If you want you can also supply a first_name and a last_name.
Depending on your what systems Payway integrate with, first_name and a last_name might be required for certain exports.
Trial order¶
If you want to sell a free campaign that transitions to a standard package please use Place trial order without account 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 without account API
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.
How and when is account information from Klarna synced with Payway¶
- Account information from Klarna always takes precedence. To disable this behaviour please set
disable_account_info_overwrite=truewhen creating the session. - During trial purchases we do not receive any account information from Klarna until the first recurring charge.
What information is 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 |
Custom error handling¶
You can configure Payway to raise an error if certain conditions are met during the account update. 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_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 |
| 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 |
| 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 |
| 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¶
The klarna integration adheres to the common error conventions of the Payway API.
See
Errors that we know of and are specific to 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