Integrating Hosted Payment Page
Components and Objects
Klarna’s Hosted Payment Page (HPP) requires that you integrate three different server-side REST APIs but requires no client-side integration. The three different APIs correspond to the three different Klarna products and have some defined objects that interact with each other.
- Payments REST API: create payment session, place order
a. KP Session: a payment session on Klarna Payments API. It contains everything regarding the transaction and has a 48 hours lifetime.
b. KP Authorization Token: an authorization for the payment of a KP Session to the corresponding Consumer. The token is valid for 60 minutes and has to be used by your backend to create the corresponding OM Order. An authorization can be given multiple times to the same Consumer for the same KP Session, but only one can be used to create an OM Order.
- Hosted Payment Page REST API: host payment session, distribute
a. HPP Session: a session on HPP that is linked to a KP Session. When a KP Session is being completed, canceled or expires, it is also the case for the HPP Session. An HPP Session has an unique URL where the Consumer can be redirected to.
- Order Management REST API: capture payment
a. OM Order: a due payment from the Consumer for defined goods. It is created using a KP Authorization Token with the KP Session. The OM Order will allow you to capture the payment when goods or service have been delivered, and manage the post purchase experience of the Consumer.
When creating the KP Session, you can configure it to automatically capture the payment. In that case you won’t have to integrate Order Management API. This should be limited to digital goods or when you limit it to some payment methods,
KP session and HPP Session both have an expiration time, but the expiration is driven by the KP session which expires 48 hours after its creation. A Consumer will be able to pay on HPP until 1 hour before KP session expiration.
After payment authorization, your backend will have 1 hour to actually place the order and confirm it to the Consumer.
Klarna uses HTTP’s Basic auth to authenticate requests from Merchants. Use your API Credentials to add the corresponding HTTP headers to your requests, the credentials consist of two elements:
- Username: a username linked to your Merchant ID at Klarna
- Password: a unique password that is associated with the username
Use your credentials to generate the token:
UsernameCalculated basic auth
UsernameExample of request
Environments and tests
Klarna offers a test environment named Playground and a production environment. The different API are available on each environment. URL structures are the same for both environment, targeted environment will be defined by the domain you are using. To be able to test your integration, you will need a Test Account.
The HPP API follows the same rules as other Klarna public APIs, we try to update our APIs regularly in a non breaking way, ensuring backward compatibility. You can find more in our and see how we define backward compatibility and non-breaking changes.
- Accept any 2xx codes as success, do not code for a specific error response code
- Interpret any 4xx as an error, do not code for a specific error response code
- Interpret any 5xx as an error, do not code for a specific error response code