HPP (1.1)

Download OpenAPI specification:Download

Hosted Payment Page (HPP) API is a service that lets you integrate Klarna Payments without the need of hosting the web page that manages the client side of Klarna Payments. A complete HPP payment session will involve three of Klarna services:

Klarna Payments API to start a payment session.
Hosted Payment Page API to distribute a payment session.
Order Management API to capture payment or refund consumer.

sessions

Endpoint to create HPP Sessions and interact with it

Create a new HPP session

Use this API to create an HPP session after creating a payment session. Read more on Create a new HPP session.

Request

header Parameters

User-Agent

string

User-Agent

Request Body schema: application/json

sessionRequest

	object (MerchantUrlsV1)
	object (OptionsV1)
payment_session_url required	string URL of the KP Session or KCO Order to be hosted by the HPP Session
profile_id	string Profile id for default session options

Responses

201

Successfully created HPP session

400

We were unable to create a session with the provided data. Some field constraint was violated.

401

Unauthorized

403

You were not authorized to execute this operation.

404

Payment session has expired.

post/hpp/v1/sessions

Request samples

Payload
curl
JavaScript
Node.js

application/json

{"merchant_urls": {"back": "https://example.com/back?sid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&hppId={{session_id}}",
"cancel": "https://example.com/cancel?sid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&hppId={{session_id}}",
"error": "https://example.com/error?sid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&hppId={{session_id}}",
"failure": "https://example.com/fail?sid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&hppId={{session_id}}",
"status_update": "https://example.com/status_update?sid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&secret=yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy&hppId={{session_id}}",
"success": "https://example.com/success?sid=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx&hppId={{session_id}}&token={{authorization_token}}"
},
"options": {"additional_checkboxes": [{"checked": false,
"id": "string",
"required": false,
"text": "string"
}
],
"background_images": [{"url": "string",
"width": 0
}
],
"logo_url": "https://example.com/logo.jpg",
"page_title": "Complete your purchase",
"payment_fallback": true,
"payment_method_categories": ["DIRECT_DEBIT"
],
"payment_method_category": "DIRECT_DEBIT",
"place_order_mode": "PLACE_ORDER",
"purchase_type": "BUY",
"show_subtotal_detail": "HIDE"
},
"payment_session_url": "One of https://api.klarna.com/payments/v1/sessions/92d97f60-7a78-46a5-8f68-c56fe52dc4af or https://api.klarna.com/checkout/v3/orders/92d97f60-7a78-46a5-8f68-c56fe52dc4af",
"profile_id": "87ab3565-5e06-4006-9ada-8eedc6926703"
}

Response samples

application/json

{"distribution_module": {"generation_url": "string",
"standalone_url": "string",
"token": "string"
},
"distribution_url": "https://api.klarna.com/hpp/v1/sessions/9cbc9884-1fdb-45a8-9694-9340340d0436/distribution",
"expires_at": "2038-01-19T03:14:07.000Z",
"manual_identification_check_url": "https://api.klarna.com/hpp/v1/sessions/9cbc9884-1fdb-45a8-9694-9340340d0436/manual-id-check",
"qr_code_url": "https://pay.klarna.com/eu/hpp/payments/a94e7760-d135-2721-a538-d6294ea254ed/qr",
"redirect_url": "https://pay.klarna.com/eu/hpp/payments/2OCkffK",
"session_id": "9cbc9884-1fdb-45a8-9694-9340340d0436",
"session_url": "https://api.klarna.com/hpp/v1/sessions/9cbc9884-1fdb-45a8-9694-9340340d0436"
}

Read HPP session

Use this API to read an HPP session content and it's status. Read more on Read HPP session.

Request

path Parameters

session_id

required

string

HPP session id

Responses

200

Session found

401

Unauthorized

403

You were not authorized to execute this operation.

404

HPP session has expired or could not be found by provided id.

get/hpp/v1/sessions/{session_id}

Request samples

curl
JavaScript
Node.js

curl -i -X GET \
  'https://api.klarna.com/hpp/v1/sessions/{session_id}'

Response samples

application/json

{"authorization_token": "70850a20-a2a0-5c70-810c-096fa6f850bb",
"customer": {"date_of_birth": "1987-08-15",
"family_name": "string",
"given_name": "string",
"national_identification_number": "19870815-84932",
"title": "Mr"
},
"expires_at": "2038-01-19T03:14:07.000Z",
"klarna_reference": "ffc25786",
"manual_identification": {"challenge": "A78",
"customer": {"date_of_birth": "1987-08-15",
"family_name": "string",
"given_name": "string",
"national_identification_number": "19870815-84932",
"title": "Mr"
},
"customer_obfuscated": {"date_of_birth": "1987-08-15",
"family_name": "string",
"given_name": "string",
"national_identification_number": "19870815-84932",
"title": "Mr"
},
"expires_at": "2038-01-19T03:14:07.000Z"
},
"order_id": "93d644a2-43f3-11e9-b210-d663bd873d93",
"session_id": "a15b228c-02ad-11e9-8eb2-f2801f1b9fd1",
"status": "COMPLETED",
"updated_at": "2038-01-19T03:14:07.000Z"
}

Disable HPP session

Use this API to disable an HPP session if payment session had to be cancelled for any reason. Read more on Disable HPP session.

Request

path Parameters

session_id

required

string

HPP session id

Responses

204

Session was disabled

400

HPP session has already been successfully completed.

401

Unauthorized

403

You were not authorized to execute this operation.

404

HPP session has expired or could not be found by provided id.

delete/hpp/v1/sessions/{session_id}

Request samples

curl
JavaScript
Node.js

curl -i -X DELETE \
  'https://api.klarna.com/hpp/v1/sessions/{session_id}'

Distribute link to the HPP Session to the Consumer

Use this API to distribute to the Consumer a link to the Hosted Payment Page either by e-mail or SMS after you have created an HPP session. Read more on Distribute link to the HPP Session to the Consumer.

Request

path Parameters

session_id

required

string

HPP session id

Request Body schema: application/json

Distribution Request parameters

required	object (DistributionContactV1)
method required	string Method used for distribution Enum: "sms" "email" "token"
template	string Template to use for distribution. In the current version this value is not used and might be removed in the future. Value: "INSTORE_PURCHASE"

Responses

201

Created

204

Successfully distributed the HPP Session

400

We were unable to distribute the link with the provided data. Some field constraint was violated. Or session is disabled by merchant.

401

Unauthorized

403

Forbidden

404

HPP session not found or access token not found

503

We were unable to distribute the link due to an internal error. Please try again

post/hpp/v1/sessions/{session_id}/distribution

Request samples

Payload
curl
JavaScript
Node.js

application/json

{"contact_information": {"access_id": "klarna:09f4a78d-d096-47d4-a0f6-abcf680c70fe",
"email": "test@example.com",
"phone": "07000212345",
"phone_country": "SE"
},
"method": "sms",
"template": "INSTORE_PURCHASE"
}

Inform decision of session manual identification check

Use this API to record decision of manual identification check for an HPP session.

Request

path Parameters

session_id

required

string

HPP session id

Request Body schema: application/json

manualIdentificationCheckRequest

associate_id	string Associate identification code
decision required	string Manual identification decision type Enum: "VERIFIED" "NOT_VERIFIED"
pos_id	string Point of Sale identification code
terminal_id	string Terminal identification code

Responses

201

Created

204

Manual identification check decision successfully registered.

400

Manual identification check outcome could not be recorded.

401

Unauthorized

403

You were not authorized to execute this operation.

404

HPP session has expired or could not be found by provided id.

post/hpp/v1/sessions/{session_id}/manual-id-check

Request samples

Payload
curl
JavaScript
Node.js

application/json

{"associate_id": "string",
"decision": "VERIFIED",
"pos_id": "string",
"terminal_id": "string"
}