Create session with Hosted Payment Page - API Details

This page provides details on creating sessions for the Hosted Payment Page (HPP) API.

Overview

When a payment session is created with the payment provider's API, an HPP session can be generated. This allows displaying the payment provider's interface to the consumer without iframe integration on your website. The HPP session and payment session share a lifecycle, with the HPP session expiring one hour before the payment session. Updates to the payment session status also affect the HPP session. While multiple HPP sessions can be linked to a single payment session (KP), it's generally not recommended with KCO orders.

Customization

All Hosted Payment Page customizations are done during session creation. Refer to the customization guide.

Creating the Request

Payment Session URL

The URL for the payment session depends on the payment provider:

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

These URLs must be obtained from your payment session (KP) or order (KCO) creation APIs. The specific environment-domain and order/session ID should be checked in Klarna's environment and testing documentation.

Merchant URLs

Merchant URLs are used to redirect the consumer after successful payment, rejection, or cancellation.

Empty or null values for success, cancel, back, failure, or error URLs will display a generic confirmation page.

Use placeholders like {{session_id}} or {{order_id}} for context in these URLs.

Tag	Place holder Usage
`{{session_id}}`	The identifier of the HPP Session.
`{{authorization_token}}`	Authorization token for Klarna Payments order placement (used only with KP in the success URL).
`{{order_id}}`	Order identifier for KCO or KP sessions with place_order_mode (used only with KCO or KP's place_order_mode).

Branding Customization

Use optional parameters to customize the HPP's appearance and match your brand. Refer to the customization guide.

Payment Provider Specific Parameters

Klarna Payments (KP):

Specific parameters to customize the experience can be found in the KP integration guide.

Klarna Checkout (KCO):

No specific parameters are required for KCO.

Interpreting the Response

On successful HPP session creation, the response contains several URLs for interacting with the payment page:

Field Key	Type	Description
`session_id`	String	HPP session ID.
`session_url`	API Endpoint URL	Used to retrieve the HPP session. Requires merchant credentials.
`distribution_url`	API Endpoint URL	Distribute the session by email/SMS. Requires merchant credentials.
`redirect_url`	Public URL	Redirects the consumer to the payment page.
`qr_code_url`	Public URL	Displays a QR code for mobile payment.
`expires_at`	Date	Session expiration time.
`distribution_module`	Object	Contains token and URLs for standalone distribution.

These URLs should be directly used by the integration layer, as their structure might change.