Skip to content
/
Create an HPP session

HPP (1.1)

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

Read more on Hosted payment page.

Download OpenAPI description
hosted-payment-page.json
hosted-payment-page.yaml
Overview
License
Klarna Bank AB
Languages
Servers
https://api.kustom.co

Create an HPP session

Request

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

Headers
User-Agentstring

User-Agent

Bodyapplication/jsonrequired

sessionRequest

merchant_urlsobject(MerchantUrlsV1)
optionsobject(OptionsV1)
payment_session_urlstringrequired

URL of the KP Session or KCO Order to be hosted by the HPP Session

Example: "One of https://api.kustom.co/payments/v1/sessions/92d97f60-7a78-46a5-8f68-c56fe52dc4af or https://api.kustom.co/checkout/v3/orders/92d97f60-7a78-46a5-8f68-c56fe52dc4af"
profile_idstring

Profile id for default session options

Example: "87ab3565-5e06-4006-9ada-8eedc6926703"
curl -i -X POST \
  https://api.kustom.co/hpp/v1/sessions \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: string' \
  -d '{
    "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": {
      "background_images": [
        {
          "url": "string",
          "width": 0
        }
      ],
      "logo_url": "https://example.com/logo.jpg",
      "page_title": "Complete your purchase",
      "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.kustom.co/payments/v1/sessions/92d97f60-7a78-46a5-8f68-c56fe52dc4af or https://api.kustom.co/checkout/v3/orders/92d97f60-7a78-46a5-8f68-c56fe52dc4af",
    "profile_id": "87ab3565-5e06-4006-9ada-8eedc6926703"
  }'

Responses

Successfully created HPP session

Bodyapplication/json
distribution_moduleobject(DistributionModuleV1)
distribution_urlstring

Endpoint for link distribution

Example: "https://api.kustom.co/hpp/v1/sessions/9cbc9884-1fdb-45a8-9694-9340340d0436/distribution"
expires_atstring(date-time)

Session expiration time

Example: "2038-01-19T03:14:07.000Z"
manual_identification_check_urlstring

Endpoint for manual identification check

Example: "https://api.kustom.co/hpp/v1/sessions/9cbc9884-1fdb-45a8-9694-9340340d0436/manual-id-check"
qr_code_urlstring

HPP url to download qr code image

Example: "https://pay.klarna.com/eu/hpp/payments/a94e7760-d135-2721-a538-d6294ea254ed/qr"
redirect_urlstring

HPP url to redirect the consumer to. ECOMMERCE only

Example: "https://pay.klarna.com/eu/hpp/payments/2OCkffK"
session_idstring

HPP session id

Example: "9cbc9884-1fdb-45a8-9694-9340340d0436"
session_urlstring

Endpoint to get the session

Example: "https://api.kustom.co/hpp/v1/sessions/9cbc9884-1fdb-45a8-9694-9340340d0436"
Response
application/json
{
  "distribution_module": {
    "generation_url": "string",
    "standalone_url": "string",
    "token": "string"
  },
  "distribution_url": "https://api.kustom.co/hpp/v1/sessions/9cbc9884-1fdb-45a8-9694-9340340d0436/distribution",
  "expires_at": "2038-01-19T03:14:07.000Z",
  "manual_identification_check_url": "https://api.kustom.co/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.kustom.co/hpp/v1/sessions/9cbc9884-1fdb-45a8-9694-9340340d0436"
}

Get details of an HPP session

Request

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

Path
session_idstringrequired

HPP session id

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

Responses

Session found

Bodyapplication/json
authorization_tokenstring

Authorization token (only for KP Sessions)

Example: "70850a20-a2a0-5c70-810c-096fa6f850bb"
customerobject(CustomerV1)
expires_atstring(date-time)

Session expiration time

Example: "2038-01-19T03:14:07.000Z"
klarna_referencestring

Kustom reference provided by MoOD

Example: "ffc25786"
manual_identificationobject(MerchantManualIdentificationV1)
order_idstring

Order id of the payment session

Example: "93d644a2-43f3-11e9-b210-d663bd873d93"
session_idstring

The id of the HPP Session

Example: "a15b228c-02ad-11e9-8eb2-f2801f1b9fd1"
statusstring

Current HPP Session status

Enum"WAITING""BACK""IN_PROGRESS""MANUAL_ID_CHECK""COMPLETED""CANCELLED""FAILED""DISABLED""ERROR"
Example: "COMPLETED"
updated_atstring(date-time)

Latest status update time

Example: "2038-01-19T03:14:07.000Z"
Response
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": { … },
    "customer_obfuscated": { … },
    "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 an HPP session

Request

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

Path
session_idstringrequired

HPP session id

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

Responses

Session was disabled

Distribute an HPP session

Request

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.

Path
session_idstringrequired

HPP session id

Bodyapplication/jsonrequired

Distribution Request parameters

contact_informationobject(DistributionContactV1)required
methodstringrequired

Method used for distribution

Enum"sms""email""token"
Example: "sms"
templatestring

Template to use for distribution. In the current version this value is not used and might be removed in the future.

Value"INSTORE_PURCHASE"
Example: "INSTORE_PURCHASE"
curl -i -X POST \
  'https://api.kustom.co/hpp/v1/sessions/{session_id}/distribution' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact_information": {
      "access_id": "klarna:09f4a78d-d096-47d4-a0f6-abcf680c70fe",
      "email": "test@example.com",
      "phone": "07000212345",
      "phone_country": "SE"
    },
    "method": "sms",
    "template": "INSTORE_PURCHASE"
  }'

Responses

Created