# Create an HPP session

> `POST https://api.kustom.co/hpp/v1/sessions`

Use this API to create an HPP session after creating a payment session.
Read more on **[Create a new HPP session](../v3/hosted-payment-page/api-documentation/create-session/)**.

## Parameters

- `User-Agent` (string, header) — User-Agent

## Request body

sessionRequest

`application/json`

- `merchant_urls` (object)
  - `back` (string) — Back URL
  - `cancel` (string) — Cancel URL
  - `error` (string) — System error URL
  - `failure` (string) — Failure URL
  - `status_update` (string) — Status update URL
  - `success` (string) — Success URL
- `options` (object)
  - `background_images[]` (array<object>) — List of Images to use for the background. Best matching resolution will be used.
    - `url` (string) — Url for the image
    - `width` (integer) — Width of the image
  - `logo_url` (string) — URL of the logo to be displayed
  - `page_title` (string) — Title for the Payment Page
  - `payment_method_categories[]` (array<string>) — Payment Method Categories to show on the Payment Page. All available categories will be given to the customer if none is specified using payment_method_category or payment_method_categories. Ignored field for KCO Orders.
  - `payment_method_category` (string) — Payment Method Category to show on the Payment Page. All available categories will be given to the customer if none is specified using payment_method_category or payment_method_categories. Ignored field for KCO Orders. Enum: `DIRECT_DEBIT`, `DIRECT_BANK_TRANSFER`, `PAY_NOW`, `PAY_LATER`, `PAY_OVER_TIME`, `KLARNA`.
  - `place_order_mode` (string) Enum: `PLACE_ORDER`, `CAPTURE_ORDER`, `NONE`.
  - `purchase_type` (string) — The type of this purchase Enum: `BUY`, `RENT`, `BOOK`, `SUBSCRIBE`, `DOWNLOAD`, `ORDER`, `CONTINUE`.
  - `show_subtotal_detail` (string) Enum: `HIDE`.
- `payment_session_url` (string, required) — URL of the KP Session or KCO Order to be hosted by the HPP Session
- `profile_id` (string) — Profile id for default session options

### Example request

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

### 201

Successfully created HPP session

`application/json`

- `distribution_module` (object)
  - `generation_url` (string)
  - `standalone_url` (string)
  - `token` (string)
- `distribution_url` (string) — Endpoint for link distribution
- `expires_at` (string) — Session expiration time
- `manual_identification_check_url` (string) — Endpoint for manual identification check
- `qr_code_url` (string) — HPP url to download qr code image
- `redirect_url` (string) — HPP url to redirect the consumer to. ECOMMERCE only
- `session_id` (string) — HPP session id
- `session_url` (string) — Endpoint to get the session

```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"
}
```

### 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.