Hosted Payment Page with Klarna Payments

Sequence diagrams

You will find here the usual integration flow of the Hosted Payment Page using a Klarna Payments session. In this flow, actors are defined as follow:

  • Consumer: a physical person that wants to buy something.
  • Browser: the browser that the Consumer is able to control, for example on a desktop or a mobile.
  • Merchant Backend: your backend that will do the API calls to HPP, KP and Order Management.
  • HPP: the Hosted Payment Page API
  • Klarna Payments: the Klarna Payments API

Sequence where you host a part of the Consumer flow

  1. Your consumer wants to proceed to a payment using one of Klarna’s payment methods: depending on the integration, this interaction can be on a website when the Consumer choose to pay with Klarna, with a telesales by phone…

  2. Create sessions on Klarna Payments and Hosted Payment Page

a. Create a Payment session on Klarna Payments: After receiving this consumer intent, create a Payment session with Klarna Payments API.

b. Associate the Payment session to an Hosted Page session: Using the session identifier provided by Klarna Payments API, create the corresponding HPP session.

  1. Distribution of the Payment session to your consumer

    a. Distribution can be done by yourself, using a redirection URL given by HPP.

    b. Request that HPP distribute the Payment session directly to your Consumer.

  2. [Invisible step for you] Consumer gets to Hosted Payment Page: Consumer goes to the Payment page using the received link, either by you or by SMS/Email received from Klarna.

  3. [Invisible step for you] Authorization of payment: When the Consumer presses the buy button on the Payment page, payment authorization will be given to the Consumer. HPP will proceed to the redirection of the Consumer to your Backend using the URL given in the session creation.

  4. Confirmation and Authorization Token

    a. Redirection of the Consumer after a successful authorization: The Consumer’s browser is redirected to your Backend, the address contains an Authorization Token that you will need to use to place the order if the order is still valid.

  5. Place the order: When everything has been validated on your side, your backend needs to place the order using the Authorization Token. This returns you an order identifier that will be needed to capture the payment.

  6. Confirmation of the order: You should show the customer that the payment authorization is successful and that the order has been validated.

  7. [This step can be asynchronous] Capture payment: When you want the payment to actually happen, usually when goods are shipped, use the Order Management API to capture the amount on the order. When creating the KP Session, you can also ask the capture to be automatic.

Success flow

After a successful authorization, the Consumer’s browser will be redirected to your success URL defined when you created the HPP session (see Step 3).

HPP will use merchant_urls.success to generate the URL, it should contain the authorization_token but can also use some additional parameters. Please see HPP Create Session Parameters and Options for dynamic parameters.

Rejection and cancellation flows

When the Consumer decides to abort the process or gets rejected by Klarna for payment authorization, the Consumer’s browser is redirected to one of the URLs defined when you created the HPP session (see Step 3).

  • merchant_urls.failure: Consumer is redirected there after being refused by Klarna.
  • merchant_urls.cancel: Consumer is redirected there after clicking on the Cancel button.

Please see HPP Create Session Parameters and Options for dynamic parameters.

Alternative Sequence: no hosting of the Consumer flow

This alternative sequence is almost the same except that you don’t need to host any page that should be shown to the Consumer. As you can’t rely on any redirection to get the status of the session, your backend needs to poll the HPP API to get it.

You can decide whether you want to host these pages by yourself or rely on HPP ones by defining the merchant_urls. You can give HPP a success url but not a cancellation one.

  1. Confirmation and Authorization Token

    b. Polling to get the successful authorization: The Consumer’s browser is shown a simple payment confirmation page, your Backend will need to get the Authorization Token using HPP API. that you will need to use to place the order if the order is still valid.

Success flow

After a successful authorization, the read session endpoint will give you the status of the Session and the Authorization Token to place the order with.

Rejection and cancellation flows

When the Consumer decides to abort the process or gets rejected by Klarna for payment authorization, the status of the session will also be updated. The Consumer will see a simple cancel or rejection page.

Step by step integration

1. Create KP Session with the Payments API

The first step is to create a KP Session with the Klarna Payment API in order to be able to host it using the Hosted Payment Page API. This is where you are going to define all you know already about your Consumer, what is the content of the order and the metadata associated to the purchase.

This call corresponds to Step 2a in the sequence diagram.

DescriptionCreates a session with KP-API
Description
Reference
Creates a session with KP-API
For a full list of accepted (optional) parameters, possible returns and error codes you can reference the KP-API documentation
Description
Url structure
Creates a session with KP-API
https://{endpoint}/payments/v1/sessions
Description
Example
Creates a session with KP-API
curl -X POST https://<endpoint>/payments/v1/sessions --header "Authorization: Basic <token> " --header "Content-Type: application/json" --header “Cache-Control: no-cache” --data “<parameters>”

Create a session KP: Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
    "purchase_country": "us",
    "purchase_currency": "usd",
    "locale": "en-US",
    "order_amount": 20000,
    "order_tax_amount": 0,
    "order_lines": [
        {
            "image_url": "https://www.exampleobjects.com/logo.png",
            "type": "physical",
            "reference": "Could be a Product Id or SKU #",
            "name": "Cool Bike",
            "quantity": 1,
            "unit_price": 20000,
            "tax_rate": 0,
            "total_amount": 20000,
            "total_discount_amount": 0,
            "total_tax_amount": 0
        }
    ],
    "billing_address": {
        "given_name": "John",
        "family_name": "Doe",
        "email": "email+require_signup@example.com",
        "title": "Mr",
        "street_address": "2425 Example Rd",
        "street_address2": "",
        "postal_code": "43221",
        "city": "Columbus",
        "region": "OH",
        "phone": "6145675309",
        "country": "US"
    }
}

Create a session KP: Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
    "session_id" : "<kp_session_id>",
    "client_token" : "<JWT>", // Ignore this field when using KP with HPP
    "payment_method_categories": [
        {
            "identifier": "pay_later",
            "name": "Pay later.",
            "asset_urls": {
                "descriptive": "https://cdn.klarna.com/1.0/shared/image/generic/badge/en_gb/pay_later/descriptive/pink.svg",
                "standard": "https://cdn.klarna.com/1.0/shared/image/generic/badge/en_gb/pay_later/standard/pink.svg"
            }
        }
    ]
}

How to create the Request

Please read the session creation guide of Klarna Payments API to get all details on fields and how you can use them. As you will use the Hosted Payment Page API to host your KP Session, you don’t need to read the step after.

As you won’t own and host the page that displays Klarna Payments’ Client, you have to respect additional guidelines that will depend on the use case of your integration see see special rules .

Depending on your integration use case (ie eCommerce, In Store or Telesales), you may have to respect some guidelines when creating the KP Session, see special rules .

How to interpret the Response

The KP Session is created on a successful response. On the fields present in it, only the session_id is useful when KP is used with Hosted Payment Page API. You will have to use it to build HPP’s payment_session_url.

https://api.klarna.com/payments/v1/sessions/<kp_session_id>

2. Create HPP Session with Hosted Payment Page API

The second step is to create the HPP Session using the KP Session you have just created. Sessions will have a tied lifecycle meaning that the HPP Session will expire 1 hour before the KP Session, see session lifetimes. Multiple HPP Sessions can be linked to the same KP Session if you need to have multiple customization at the same time, although it is considered as a bad practice.

All the customization of the appearance of the Payment Page is done in this call, see our customization guide.

This call corresponds to Step 2b in the sequence diagram.

DescriptionCreates a session with HPP-API
Description
Reference
Creates a session with HPP-API
For a full explanation of required and accepted (optional) parameters, check HPP Create Session Options below.
Description
Url structure
Creates a session with HPP-API
https://{endpoint}/hpp/v1/sessions
Description
Example
Creates a session with HPP-API
curl -X POST https://api.playground.klarna.com/hpp/v1/sessions --header "Authorization: Basic <token> " --header "Content-Type: application/json" --header “Cache-Control: no-cache” --data “<parameters>”

Create a session: Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
    "payment_session_url": "https://api.klarna.com/payments/v1/sessions/<kp_session_id>",
    "merchant_urls": {
        "success": "https://example.com/success?token={{authorization_token}}",
        "cancel": "https://example.com/cancel",
        "failure": "https://example.com/fail",
        "privacy_policy": "https://example.com/privacy_policy",
        "terms": "https://example.com/terms"
    },
    "options":{
        "payment_method_category": "pay_over_time",
        "logo_url": "https://example.com/logo.png",
        "logo_alignment": "LEFT",
        "background_images": [
            {
                "url": "https://example.com/bg_large.jpg",
                "width":2000
            },
            {
                "url": "https://example.com/bg_small.jpg",
                "width":600
            }
        ]
    }
}

Create a session: Response

1
2
3
4
{
    "distribution_url": "https://api.klarna.com/hpp/v1/sessions/<hpp_session_id>/distribution",
    "redirect_url": "https://payment.klarna.com/<hpp_session_id>"
}

How to create the Request

Merchants URLs

Merchant URLs are used to redirect the Consumer’s browser to your website after a successful payment, a rejection or a cancellation by the Consumer. Use this field to pass an URL to your legal terms as well as privacy policy.

When you let success, cancel or failure empty or null, the Consumer will be shown a generic action confirmation page. See our customization guide to get to see how these pages look like.

On all of these links you can use placeholders to get more context on the transaction, for example the {{session_id}} tag will be replaced by the identifier of the HPP Session.

NameRequirementUsage
Name
success
Requirement
Optional
Usage
Consumer will get redirected there after a successful authorization of payment. A place holder is required to get the authorization token.
Name
cancel
Requirement
Optional
Usage
Consumer will get redirected there when clicking on the cancellation button.
Name
failure
Requirement
Optional
Usage
Consumer will get redirected there when payment is refused by Klarna.
Name
privacy_policy
Requirement
Optional
Usage
Url of your privacy policy.
Name
terms
Requirement
Optional
Usage
Url of your terms and conditions.
TagPlace holder usage
Tag
session_id
Place holder usage
The identifier of the HPP Session.
Tag
authorization_token
Place holder usage
Authorization token to use to place the order with KP API. This placeholder works only for success.

It is required that your success URL contains the authorization_token place holder.

Payment Methods

Payment Method Category will define which category is available for the Consumer, from Pay Now, Pay Later or Slice It (Pay over time). This field is mandatory if you have multiple payment methods that are from different categories configured at Klarna.

This field is mandatory if you have payment methods in different payment method categories.

Keypayment_method_category
Key
Description
payment_method_category
Select a single payment method to show on HPP
Key
Type
payment_method_category
Enum
Key
Accepted Values
payment_method_category
PAY_NOW, PAY_LATER, PAY_OVER_TIME, DIRECT_DEBIT, DIRECT_BANK_TRANSFER
1
2
3
4
5
{
    "options": {
        "payment_method_category": "pay_later"
    }
}
Customization and optional parameters

You can use optional parameters to customize the look and feel of the Hosted Payment Page to better match your own brand. Please refer to our customization page.

All customization parameters are described in our customization guide for the Hosted Payment Page.

How to interpret the Response

The HPP Session is created on a successful response. It contains two different URLs to use for Step 3 depending on the way you intend to distribute the Payment Page.

Field KeyValueDescription
Field Key
distribution_url
Value
Endpoint URL
Description
Use this URL to make a call to the Hosted Payment Page API in order to distribute by Email or SMS the page to your Consumer, as Step 3b.
Field Key
redirect_url
Value
Consumer URL
Description
Use this URL to redirect directly by yourself the Consumer to the payment page, as Step 3a.

3. Distribute Session with HPP (Optional)

Use this endpoint if you want to distribute the Hosted Payment Page either by email or SMS.

A message will be sent directly to the Consumer using the contact information given in parameters, this message will be localised to the Consumer’s language from the HPP Session creation and will contain a link. When using the link, the Consumer will access the Payment Page.

This call corresponds to Step 3b in the sequence diagram.

DescriptionDistributes HPP via email or SMS
Description
Reference
Distributes HPP via email or SMS
For a full list of accepted parameters listed in HPP Distribute Session Parameters below
Description
Url structure
Distributes HPP via email or SMS
https://{endpoint}/hpp/v1/sessions/{session_id}/distribution
Description
Example
Distributes HPP via email or SMS
curl -X POST https://api.klarna.com/hpp/v1/sessions/<session_id>/distribution --header "Authorization: Basic <token> " --header "Content-Type: application/json" --header “Cache-Control: no-cache” --data “<parameters>"

Distribution SMS example:

1
2
3
4
5
6
7
{
    "contact_information": {
        "phone": "+46712345678",
        "phone_country": "se"
    },
    "method": "sms"
}

Distribution email example:

1
2
3
4
5
6
{
    "contact_information": {
        "email": "user@example.com"
    },
    "method": "email"
}

Contact information field

ParametersTypeDescription
Parameters
phone
Type
String
Description
Phone number of customer. Country code is optional if the number is local. Optional if distribution method is email.
Parameters
phone_country
Type
String
Description
Country of the phone number. Optional if distribution method is email.
Parameters
email
Type
String
Description
Email address of the customer. Optional if distribution method is sms.

4. Retrieve the Authorization Token

As described in the objects overview, when a Consumer gets a Payment Authorization, your backend will need to use a KP Authorization Token to place the Order.

This token can be retrieved by your system using two different ways, via the redirection of the Consumer to your own website or by making an API Call to get the status of the session.

It is advised to use both method to make sure that your system is actually placing the order whenever the Consumer has gotten a confirmation of payment by Klarna.

4.a. From the Consumer redirection

This token can be retrieved by your system using two different ways, via the redirection of the Consumer to your own website or by making an API Call to the read endpoint to get the status of the session.

This call corresponds to Step 6a in the sequence diagram.

4.b. From the HPP Session Status

This token can be retrieved by making an API Call to the HPP API. You can for example use a polling mechanism to check the status of the session and when the Consumer gets an authorization, you will be able to extract the KP Authorization Token from the server response.

DescriptionGets the status of the HPP Session
Description
Reference
Gets the status of the HPP Session
For a full list of returned values, please read API Reference.
Description
Url structure
Gets the status of the HPP Session
https://{endpoint}/hpp/v1/sessions/{session_id}
Description
Operation
Gets the status of the HPP Session
GET
Description
Example
Gets the status of the HPP Session
curl https://api.klarna.com/hpp/v1/sessions/<session_id> --header "Authorization: Basic <token> " --header "Content-Type: application/json" --header “Cache-Control: no-cache”
Status nameStatus description
Status name
WAITING
Status description
Session is created and Consumer has not entered the Payment Page yet
Status name
IN_PROGRESS
Status description
Consumer has entered the Payment Page on updated_at
Status name
COMPLETED
Status description
Consumer has successfully gotten an Authorization from the Payment system on updated_at, Authorization Token is contained in the kp_authorization_token field.
Status name
FAILED
Status description
Consumer has been declined for the Payment on updated_at
Status name
CANCELLED
Status description
Consumer has pressed the Back button on updated_at
Status name
DISABLED
Status description
Session was disabled by API Call on the Merchant initiative on updated_at

Get status example completed

1
2
3
4
5
{
    "updated_at": "2018-07-18T13:15:48.857Z",
    "status": "COMPLETE",
    "authorization_token": "ebe5c188-e9ba-56e1-81ad-15c7248766be"
}

Get status example other

1
2
3
4
{
    "updated_at": "2018-07-18T13:15:48.857Z",
    "status": "WAITING"
}

5. Place Order with Klarna Payments API

Now that the Consumer has gotten an Authorization from Klarna for the Payment, you have to use the Authorization Token that you retrieved in the redirection to Place the Order. After this call, Klarna will consider that the Order is actually valid and that you will be able to capture the payment when the goods are being delivered. Please read the place order guide of Klarna Payments to get all details.

Depending on your integration use case (ie eCommerce, In Store or Telesales), you may have to respect some guidelines when placing the order, see special rules .

To ease your integration and depending on your use case, you can count on the auto_capture feature of the KP API to automatically capture the order after its creation. Please read the place order guide of Klarna Payments to get all details.

This call corresponds to Step 7 in the sequence diagram.

Place order request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "purchase_country": "GB",
  "purchase_currency": "GBP",
  "locale": "en-GB",      
  "order_amount": 57064,
  "order_tax_amount": 9511,
  "order_lines": [
    {
      "image_url": "https://www.exampleobjects.com/logo.png",
      "type": "physical",
      "reference": "Could be a Product Id or SKU #",
      "name": "Cool Bike",
      "quantity": 1,
      "unit_price": 20000,
      "tax_rate": 0,
      "total_amount": 20000,
      "total_discount_amount": 0,
      "total_tax_amount": 0
    }
  ]
}

Place order response

1
2
3
4
{
  "order_id": "41c001ca-f6d4-4240-bbc5-5d2c036a2de4",
  "fraud_status": "ACCEPTED"
}

6. Capture Payment with Order Management API

After the creation of the Order, if you haven’t used the auto_capture feature of the KP API, you will need to capture the payment using the Order Management API. Until this step has been done, the payment is not really finalized and the payment won’t occur.

Please read the capture guide of Order Management to get all details.

Edge cases

Disabling an HPP Session by Merchant initiative

If for any reason the payment session has to be canceled (expiration of an offer, order was paid using another payment method, etc), the HPP API gives to the Merchant the possibility to disable an HPP Session. To do that, it is required to send a delete request on the HPP Session resource.

When an HPP Session has been disabled by the Merchant, the Consumer will get a Page Not Found error when using a previous link that has been distributed. If the Consumer was still on the payment page while the session was disabled, they will get a Page Not Found error as soon as they do an action. The value of the status of the HPP Session will be DISABLED.

DescriptionDisable an HPP Session
Description
Reference
Disable an HPP Session
For a full list of returned values, please read API Reference.
Description
Url structure
Disable an HPP Session
https://{endpoint}/hpp/v1/sessions/{session_id}
Description
Operation
Disable an HPP Session
DELETE
Description
Example
Disable an HPP Session
curl -X "DELETE" https://api.klarna.com/hpp/v1/sessions/<session_id> --header "Authorization: Basic <token> "