Examples

After creating a Payment Session, you can create a hosted payment page session, allowing consumer access to the payment interface without iframe integration.

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.

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

Description	Creates a session with HPP-API
Reference	For a full explanation of required and accepted (optional) parameters, check HPP Create Session Options below.
Url structure	https://`environment-domain`/hpp/v1/sessions
Example	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`”

Request for Klarna Payments (KP)

JSON

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}}&authorization_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

JSON

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}}&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": {

HPP Session Creation Response

JSON

1 2 3 4 5 6 7 8 9 10

{
    "session_id": "<hpp_session_id>",
    "redirect_url": "https://pay.klarna.com/eu/hpp/payments/2OCkffK",
    "session_url": "https://api.klarna.com/hpp/v1/sessions/<hpp_session_id>",
    "qr_code_url": "https://pay.klarna.com/eu/hpp/payments/<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",
    "distribution_module": {
      "token": "<distribution_token>",
      "standalone_url": "https://pay.klarna.com/eu/hpp/distributions/<distribution_id>?profile_id={{profile_id}}&view_id={{view_id}}",

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 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 Provider	URL Structure
Klarna Payments	https://`environment-domain`/payments/v1/sessions/`kp_session_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.

Name	Requirement	Usage
success	Optional	Consumer will get redirected there after a successful authorization of payment for KP. When using KP as Payment Provider, a place holder will be required to get the KP Authorization Token to place the order.
cancel	Optional	Consumer will get redirected there when clicking on the cancellation button. See back button versus cancel button chapter.
back	Optional	Consumer will get redirected there when clicking on the back button. See back button versus cancel button chapter.
failure	Optional	Consumer will get redirected there when payment is refused by Klarna. If an error occurs and noerrorURL was given, then the consumer will also get redirect to this URL.
error	Optional	Consumer will get redirected there when an error occurred in the flow. If this parameter is not set and afailureURL is present, the Consumer will get redirected there.
status_update	Optional	Url that will be used for callbacks. Learn more about callbacks.

Tag	Place holder usage
{{session_id}}	The identifier of the HPP Session.
{{authorization_token}}	Authorization token to use to place the order with KP API. This placeholder works only for KP as Payment Provider in a success URL.
{{order_id}}	Order identifier to use to handle post-purchase experience. This placeholder works only when usingplace_order_modewith 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.

Field Key	Type	Description
session_id	String	Generated identifier for the Session, referenced as HPP Session ID afterwards.
session_url	API Endpoint URL	Use this URL to read the HPP Session you just created. This endpoint requires Merchant Credentials to accept requests.
distribution_url	API Endpoint URL	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.
redirect_url	Public URL	Use this URL to redirect directly the Consumer’s browser to the Payment Page or the HPP Session you just created. Learn more in the distribution of the HPP Session chapter.
qr_code_url	Public URL	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. Learn more in the distribution of the HPP Session chapter.
expires_at	Date	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.
distribution_module	Object	Distribution module data containing the following fields: `token`, `standalone_url`, and `generation_url`.

Examples

Request for Klarna Payments (KP)

Request for Klarna Payments (KP) with Place Order

HPP Session Creation Response

How to create the Request

Payment Session URL

Merchants URLs

Branding Customization

Payment provider specific parameters

Klarna Payments

How to interpret the Response