HPP API: Create the HPP Session

When you have created a Payment Session with the Payment Provider’s API, you will be able to create an HPP Session. This HPP Session will let you show the Payment Provider’s interface to the Consumer without any iframe integration on your website.

The HPP Session is deeply linked to the Payment Session, both Sessions will have a tied lifecycle meaning that the HPP Session will expire 1 hour before the Payment Session, see session lifetime . Additionally, when the Payment Session status is updated, HPP Session’s one is too.

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. This is not the case with a KCO Order and may lead to unexpected behaviors.

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

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://<environment-domain>/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>”

Examples

Request for Klarna Payments (KP)

1
2
3
4
5
6
7
8
9
10
{
    "payment_session_url": "https://<environment-domain>/payments/v1/sessions/<kp_session_id>",
    "merchant_urls": {
        "success": "https://example.com/success?token=<random_uuid>&sid={{session_id}}&token={{authorization_token}}",
        "cancel": "https://example.com/cancel?token=<random_uuid>&sid={{session_id}}",
        "back": "https://example.com/back?token=<random_uuid>&sid={{session_id}}",
        "failure": "https://example.com/fail?token=<random_uuid>&sid={{session_id}}",
        "error": "https://example.com/error?token=<random_uuid>&sid={{session_id}}"
    }
}

Request for Klarna Payments (KP) with Place Order

1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "payment_session_url": "https://<environment-domain>/payments/v1/sessions/<kp_session_id>",
    "merchant_urls": {
        "success": "https://example.com/success?token=<random_uuid>&sid={{session_id}}&order_id={{order_id}}",
        "cancel": "https://example.com/cancel?token=<random_uuid>&sid={{session_id}}",
        "back": "https://example.com/back?token=<random_uuid>&sid={{session_id}}",
        "failure": "https://example.com/fail?token=<random_uuid>&sid={{session_id}}",
        "error": "https://example.com/error?token=<random_uuid>&sid={{session_id}}"
    },
    "options": {
      "place_order_mode": "PLACE_ORDER"
    }
}

Request for Klarna Checkout (KCO)

1
2
3
4
5
6
7
8
9
10
{
    "payment_session_url": "https://<environment-domain>/checkout/v3/orders/<kco_order_id>",
    "merchant_urls": {
        "success": "https://example.com/success?token=<random_uuid>&sid={{session_id}}",
        "cancel": "https://example.com/cancel?token=<random_uuid>&sid={{session_id}}",
        "back": "https://example.com/back?token=<random_uuid>&sid={{session_id}}",
        "failure": "https://example.com/fail?token=<random_uuid>&sid={{session_id}}",
        "error": "https://example.com/error?token=<random_uuid>&sid={{session_id}}"
    }
}

Response

1
2
3
4
5
6
7
8
{
    "session_id": "<hpp_session_id>",
    "redirect_url": "https://payment.klarna.com/7fBBmV2",
    "session_url": "https://api.klarna.com/hpp/v1/sessions/<hpp_session_id>",
    "qr_code_url": "https://payment.klarna.com/<hpp_session_id>/qr",
    "distribution_url": "https://api.klarna.com/hpp/v1/sessions/<hpp_session_id>/distribution",
    "expires_at": "2019-05-29T08:22:05.563Z"
}

The integration layer should use the URLs sent back in the create session call when interacting with the HPP Session as the structure of the URLs may change. Do not recreate URLs by generating a made up structure.

How to create the Request

Payment Session URL

After creating the KP Session or KCO Order you need to compute the corresponding URL to one of them. To do so, simply use the URL that you are using to access them via API.

Payment ProviderURL Structure
Payment Provider
Klarna Payments
URL Structure
https://<environment-domain>/payments/v1/sessions/<kp_session_id>
Payment Provider
Klarna Checkout
URL Structure
https://<environment-domain>/checkout/v3/orders/<kco_order_id>

Exact domain names for environments and regions can be found in our environments and testing guidelines .

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.

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. When error is empty or null, the failure definition will be used.

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 for both KP and KCO. When using KP as Payment Provider, a place holder will be required to get the KP Authorization Token to place the order.
Name
cancel
Requirement
Optional
Usage
Consumer will get redirected there when clicking on the cancellation button. See back button versus cancel button chapter.
Name
back
Requirement
Optional
Usage
Consumer will get redirected there when clicking on the back button. See back button versus cancel button chapter.
Name
failure
Requirement
Optional
Usage
Consumer will get redirected there when payment is refused by Klarna. If an error occurs and no error URL was given, then the consumer will also get redirect to this URL.
Name
error
Requirement
Optional
Usage
Consumer will get redirected there when an error occurred in the flow. If this parameter is not set and a failure URL is present, the Consumer will get redirected there.
Name
status_update
Requirement
Optional
Usage
Url that will be used for callbacks. Learn more about callbacks .
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 KP as Payment Provider in a success URL.
Tag
{{order_id}}
Place holder usage
Order identifier to use to handle post-purchase experience. This placeholder works only for KCO or when using place_order_mode with KP as Payment Provider.

Branding Customization

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 .

Payment provider specific parameters

Klarna Payments

The Klarna Payments integration has some specific parameters that you can pass to the HPP Session creation call to better configure what the consumer will see. Please read our KP integration guide .

Klarna Checkout

No additional parameter is available when using Klarna Checkout.

How to interpret the Response

The HPP Session is created on a successful response. It contains different URLs that you may use to interact with depending on the way you intend to distribute the Payment Page.

It is recommended to use these links directly and to avoid recreating them in your backend as the way they are defined may change without notice.

Field KeyTypeDescription
Field Key
session_id
Type
String
Description
Generated identifier for the Session, referenced as HPP Session ID afterwards.
Field Key
session_url
Type
API Endpoint URL
Description
Use this URL to read the HPP Session you just created. This endpoint requires Merchant Credentials to accept requests.
Field Key
distribution_url
Type
API Endpoint URL
Description
Use this URL to distribute to your Consumer the HPP Session you just created by Email or SMS. Learn more in the distribution of the HPP Session chapter . This endpoint requires Merchant Credentials to accept requests.
Field Key
redirect_url
Type
Public URL
Description
Use this URL to redirect directly the Consumer’s browser to the Payment Page or the HPP Session you just created. This URL is public and doesn’t need any credential. Learn more in the distribution of the HPP Session chapter .
Field Key
qr_code_url
Type
Public URL
Description
Use this URL to display a QR Code to your Consumer, so that they will access the Payment Page or the HPP Session you just created by scanning it with their phone. This URL is public and doesn’t need any credential. Learn more in the distribution of the HPP Session chapter .
Field Key
expires_at
Type
Date
Description
Date when this session will not be able for the consumer to pay anymore. You can read more about lifetime in our session lifetime article . Dates format is described here.