Klarna Docs - Create session

Create 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 aKCO Order and may lead to unexpected behaviors.

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

DescriptionCreates a session with HPP-API
ReferenceFor a full explanation of required and accepted (optional) parameters, check HPP Create Session Options below.
Url structurehttps://<environment-domain>/hpp/v1/sessions
Examplecurl -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)

JSON
{
    "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

JSON
{
    "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": {

Request for Klarna Checkout (KCO)

JSON
{
    "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

JSON
{
    "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
Klarna Paymentshttps://<environment-domain>/payments/v1/sessions/<kp_session_id>
Klarna Checkouthttps://<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
successOptionalConsumer 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.
cancelOptionalConsumer will get redirected there when clicking on the cancellation button. See back button versus cancel button chapter.
backOptionalConsumer will get redirected there when clicking on the back button. See back button versus cancel button chapter.
failureOptionalConsumer 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.
errorOptionalConsumer 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_updateOptionalUrl that will be used for callbacks. Learn more about callbacks.
TagPlace 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 for KCO or 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.

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
session_idStringGenerated identifier for the Session, referenced as HPP Session ID afterwards.
session_urlAPI Endpoint URLUse this URL to read theHPP Session you just created. This endpoint requires Merchant Credentials to accept requests.
distribution_urlAPI Endpoint URLUse this URL to distribute to your Consumer theHPP Session you just created by Email or SMS. Learn more in the distribution of the HPP Session chapter. This endpoint requiresMerchant Credentials to accept requests.
redirect_urlPublic URLUse this URL to redirect directly the Consumer’s browser to thePayment 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.
qr_code_urlPublic URLUse this URL to display a QR Code to your Consumer, so that they will access thePayment 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.
expires_atDateDate 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.