This guide covers everything you need to know to integrate Klarna HPP payments through the Ping Payments API.

Klarna HPP (Hosted Payment Page) is a full-page redirect payment experience hosted entirely by Klarna. The customer is redirected to Klarna's payment page to complete the purchase and then redirected back to your site. This means there is no iframe integration — the payment page cannot be embedded in your site. The entire checkout is handled on Klarna's domain.

Merchant Onboarding

Each merchant that will receive Klarna payments must be individually onboarded with Klarna. This process is handled by Ping Payments.

New Merchants

For merchants going through the KYC process, Klarna terms acceptance is included as part of the standard onboarding flow. No additional steps are required — once KYC is completed and Klarna terms are accepted, the merchant will be enabled for Klarna payments.

Existing Merchants

For merchants that are already onboarded with Ping Payments, a separate Klarna terms agreement will be sent. The merchant must accept these terms before they can be used for Klarna HPP payments.

Merchant Approval Status

Once a merchant has been onboarded with Klarna, their approval status is managed by Ping Payments.

The Designated Merchant

Every Klarna HPP payment requires a designated_merchant_id in the provider_method_parameters. This is the Ping Payments Merchant ID (UUID) of the merchant that the payment is processed through on Klarna's side.

Key points:

• The designated merchant must be Klarna-approved and not suspended.
• The designated merchant must appear in at least one of the payment's order_items (i.e. the merchant_id of at least one order item must match the designated_merchant_id).
• For payments involving multiple merchants, only one merchant is designated — this is the merchant whose Klarna account the payment session is created under.

Initiating a Payment

Use provider: "klarna" and method: "hpp" in the initiate payment request.

Required Parameters

Redirect URLs

All five redirect URLs are required:

Optional Parameters

HPP Options

The hpp_options object allows customization of the Klarna payment page:

Supported Currencies

SEK, NOK, EUR, DKK

Payment Flow

1. Initiate a payment — the response contains a redirect_url.
2. Redirect the customer to the redirect_url to complete payment on Klarna's hosted page.
3. After the customer completes (or abandons) the payment, they are redirected to the corresponding redirect URL provided in the request.
4. The payment status is delivered via the standard Ping Payments callback.

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": {
    "designated_merchant_id": "{{merchantId}}",
    "purchase_country": "SE",
    "locale": "sv-SE",
    "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"
  }
}

Refunds

Klarna HPP payments support refunds through the standard Ping Payments refund flow. Refunds are processed immediately and are marked as completed upon initiation.

KlarnaAddress

The KlarnaAddress object is used for both billing_address and shipping_address: