Create an HPP session

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.

Parameters

Request body

201

400

401

403

404

Example

Parameters1 field

• User-Agentstringoptionalin header

  User-Agent

Request body20 fields

sessionRequest

• merchant_urlsobjectoptional
  6 fields in merchant_urls

  • backstringoptional

    Back URL

  • cancelstringoptional

    Cancel URL

  • errorstringoptional

    System error URL

  • failurestringoptional

    Failure URL

  • status_updatestringoptional

    Status update URL

  • successstringoptional

    Success URL

• optionsobjectoptional
  10 fields in options

  • background_images[]array<object>optional

    List of Images to use for the background. Best matching resolution will be used.

    2 fields in background_images

    • urlstringoptional

      Url for the image

    • widthinteger · int64optional

      Width of the image

  • logo_urlstringoptional

    URL of the logo to be displayed

  • page_titlestringoptional

    Title for the Payment Page

  • payment_method_categories[]array<string>optional

    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_categorystringoptional

    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.

    • DIRECT_DEBIT
    • DIRECT_BANK_TRANSFER
    • PAY_NOW
    • PAY_LATER
    • PAY_OVER_TIME
    • KLARNA
  • place_order_modestringoptional
    • PLACE_ORDER
    • CAPTURE_ORDER
    • NONE
  • purchase_typestringoptional

    The type of this purchase

    • BUY
    • RENT
    • BOOK
    • SUBSCRIBE
    • DOWNLOAD
    • ORDER
    • CONTINUE
  • show_subtotal_detailstringoptional
    • HIDE
• payment_session_urlstringrequired

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

• profile_idstringoptional

  Profile id for default session options

201

Response11 fields

Successfully created HPP session

• distribution_moduleobjectoptional
  3 fields in distribution_module

  • generation_urlstringoptional
  • standalone_urlstringoptional
  • tokenstringoptional
• distribution_urlstringoptional

  Endpoint for link distribution

• expires_atstring · date-timeoptional

  Session expiration time

• manual_identification_check_urlstringoptional

  Endpoint for manual identification check

• qr_code_urlstringoptional

  HPP url to download qr code image

• redirect_urlstringoptional

  HPP url to redirect the consumer to. ECOMMERCE only

• session_idstringoptional

  HPP session id

• session_urlstringoptional

  Endpoint to get the session

400

Response0 fields

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

No response body — this status returns headers only.

401

Response0 fields

Unauthorized

No response body — this status returns headers only.

403

Response0 fields

You were not authorized to execute this operation.

No response body — this status returns headers only.

404

Response0 fields

Payment session has expired.

No response body — this status returns headers only.

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

RequestBodyResponse201400401403404

Request body· 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": {
    "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"
}

29 linesCopy

Response 201· Successfully created HPP session

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

14 linesCopy

Response 400· We were unable to create a session with the provided data. Some field constrain…

No response body.

This status returns headers only — there is nothing to parse.

—

Response 401· Unauthorized

No response body.

This status returns headers only — there is nothing to parse.

—

Response 403· You were not authorized to execute this operation.

No response body.

This status returns headers only — there is nothing to parse.

—

Response 404· Payment session has expired.

No response body.

This status returns headers only — there is nothing to parse.

—