Introduction

This migration guide outlines the changes introduced in the 2025-07-18 release. In this version, we add support for Klarna Hosted Payment Page (HPP) as a new payment method, allowing customers to pay via Klarna's hosted checkout experience.

Overview of Changes

New Payment Provider: Klarna

klarna has been added as a new payment provider. The PaymentProviderEnum now includes klarna as a valid value.

New Payment Method: HPP

hpp (Hosted Payment Page) has been added as a new payment method. The PaymentMethodEnum now includes hpp as a valid value.

Initiating a Klarna HPP Payment

To initiate a Klarna HPP payment, use provider: "klarna" and method: "hpp" in the initiate payment request. The provider_method_parameters must include the following Klarna HPP-specific fields:

Required Parameters

Parameter	Type	Description
`purchase_country`	`string`	ISO 3166 alpha-2 country code (e.g. `"SE"`)
`locale`	`string`	Locale for the purchase (e.g. `"sv-SE"`)
`designated_merchant_id`	`string (uuid)`	The primary Ping Payments Merchant ID for the payment
`redirect_urls`	`object`	URLs for handling the payment flow outcome

Redirect URLs (all required)

Field	Description
`success`	URL to redirect to after successful payment
`cancel`	URL to redirect to when payment is cancelled
`error`	URL to redirect to when an error occurs
`back`	URL to redirect to when the user goes back (clicks/taps the X button)
`failure`	URL to redirect to when payment fails

Optional Parameters

Parameter	Type	Description
`billing_address`	`KlarnaAddress`	Customer's billing address
`shipping_address`	`KlarnaAddress`	Customer's shipping address
`merchant_reference`	`string`	Reference displayed in the Klarna app
`extra_merchant_data`	`object`	Additional merchant data for risk assessment. May be required depending on the type of transactions being processed.
`hpp_options`	`object`	Options for customizing the Klarna Hosted Payment Page (logo, background images, payment method categories, etc.)

Response

A successful initiation returns a redirect_url pointing to Klarna's hosted payment page. Redirect the customer to this URL to complete the payment.

Supported Currencies

Klarna HPP supports SEK, NOK, EUR, and DKK.

Example Request

{
  "currency": "SEK",
  "method": "hpp",
  "order_items": [
    {
      "amount": 10000,
      "merchant_id": "{{merchantId}}",
      "name": "Product A",
      "vat_rate": 25.0
    }
  ],
  "provider": "klarna",
  "total_amount": 10000,
  "provider_method_parameters": {
    "purchase_country": "SE",
    "locale": "sv-SE",
    "designated_merchant_id": "{{merchantId}}",
    "redirect_urls": {
      "success": "https://example.com/success",
      "cancel": "https://example.com/cancel",
      "error": "https://example.com/error",
      "back": "https://example.com/back",
      "failure": "https://example.com/failure"
    }
  }
}

Example Response

{
  "id": "15c44587-7ebb-43a3-b437-8d00e5f8df7a",
  "provider_method_response": {
    "redirect_url": "https://payment.klarna.com/pay/abc123"
  }
}

Affected Endpoints

Initiate payment