Build checkout form with Klarna Presentation API (Worldpay orchestrated)

Before you integrate, check that you meet the following prerequisites:

1. 1.
   Ensure that you have Klarna enabled with Worldpay.
2. 2.
   Confirm you have access to the Klarna Partner Portal.
3. 3.
   Inside Klarna Partner Portal:

   1. 3.1.
      Confirm that you have generated an API key with permission to call the Klarna Payment Presentation API.
4. 4.
   Add Terms and Conditions for presenting Klarna.

Here's an overview of all the steps to display Klarna and initiate payments without the Web SDK in the Worldpay-orchestrated flow:

• Your server calls Klarna's Payment Presentation API to retrieve assets and display instructions for the current purchase context.
• You render Klarna as a payment option in your payment selector using the returned assets.
• Customer selects Klarna and clicks the Klarna payment button.
• Your server forwards the purchase details to Worldpay to create the payment session.
• If customer authentication is required, Worldpay returns a payment_request_url and you redirect the customer's browser to it. The customer then completes the Klarna Purchase Journey on Klarna's hosted page — you don't render or orchestrate anything during this phase.
• Worldpay notifies you when the order is completed.
• You redirect the customer to your confirmation page.

Presenting Klarna in the payment form involves retrieving the visual assets, localized texts, and display instructions required to correctly render Klarna as a payment option and display the payment button. In this flow you request the presentation server-side and render the option yourself using the returned assets.

On a high level, the process involves:

1. 1.
   Request Klarna's payment presentation for the current payment context from your server.
2. 2.
   Render Klarna payment option(s) in the payment form according to the instruction returned.
3. 3.
   Allow the customer to select and deselect the Klarna payment option.
4. 4.
   Display the Klarna button and start the payment process when clicked.

The expected outcomes are as follows:

Initial presentation	When Klarna is selected

Call the Klarna Payment Presentation API from your server to obtain the assets and the display instruction for the current purchase context.

Issue a GET request to /v2/accounts/{partner_account_id}/payment/presentation with query-encoded parameters. Authenticate with your API key using Authorization: Basic <API key>.

Basic checkout context parameters must be provided as query parameters:

You don't send any acquiring or Payment Account configuration on this call — Payment Account selection is owned by Worldpay, not by you.

When a Klarna Conversion Boost experience (Klarna Express Checkout, Sign in with Klarna, a tokenized flow, Klarna Messaging / Prequalification, etc.) has already produced a session token in a previous step, forward it as an HTTP header so Klarna can restore the customer's context and return a richer presentation (for example PRESELECT_KLARNA or SHOW_ONLY_KLARNA):

For the full request schema, consult the API reference.

Sample request

curl -G https://api-global.test.klarna.com/v2/accounts/{partner_account_id}/payment/presentation \
  -H 'Authorization: Basic <API key>' \
  -H 'Content-Type: application/json' \
  -H 'Klarna-Network-Session-Token: krn:network:us1:test:session-token:eyJhbGciOiJIU[...]' \
  --data-urlencode 'locale=en-US' \
  --data-urlencode 'amount=15000' \
  --data-urlencode 'currency=USD' \
  --data-urlencode 'intent=PAY'

Sample response

{
  "instruction": "SHOW_KLARNA",
  "payment_status": "REQUIRES_CUSTOMER_ACTION",
  "payment_option": {
    "payment_option_id": "S0xBUk5BXzE3NzI3MDY2MTI2ODg=",
    "header": {
      "text": "Pay with Klarna"
    },
    "subheader": {
      "text": "Flexible payments, 0% interest"
    },
    "message": {

The response provides the full Klarna branding package and the instruction tailored to the customer's purchase:

The payment_option object structure is as follows:

For the full response schema, consult the API reference.

This section describes how to apply Klarna's payment presentation instructions, which define how Klarna should appear in your checkout. Following these instructions ensures a consistent experience across payment states and is required for features like Klarna Express Checkout and Sign in with Klarna.

The instruction attribute has the following values:

Instruction	Description	Example
SHOW_KLARNA	Show Klarna alongside other payment methods.
PRESELECT_KLARNA	Show Klarna pre-selected but still alongside others. This is returned when the customer's context (for example a customer_token from Sign in with Klarna or a tokenization flow) has been forwarded via the Klarna-Network-Session-Token header.
SHOW_ONLY_KLARNA	Show Klarna as the only payment method. This is returned when the customer has finished the first step of Klarna Express Checkout multistep.

Use the assets and localized strings from payment_option to render Klarna directly in your payment selector. The following diagram displays the visual components and how they are laid out:

1. 1.
   Icon
2. 2.
   Badge
3. 3.
   Header
4. 4.
   Subheader
5. 5.
   Message
6. 6.
   Terms
7. 7.
   Button

Ensure that all components — including those not immediately visible — are present in the DOM, and manage their visibility through your own logic or UI controls.

Sample HTML template

<!-- Server-rendered fragment using values from the Payment Presentation response -->
<div id="klarna-option" class="klarna-option" data-payment-option-id="{{ payment_option.payment_option_id }}">
  <img class="klarna-icon" src="{{ payment_option.icon.badge_image_url }}" alt="{{ payment_option.icon.alt }}" />

  {{#if payment_option.badge}}
    <span class="klarna-badge">{{ payment_option.badge.text }}</span>
  {{/if}}

  <div class="klarna-header">{{ payment_option.header.text }}</div>
  <div class="klarna-subheader">{{ payment_option.subheader.text }}</div>

  {{#if payment_option.message}}

The message and terms objects return a parts array rather than pre-rendered HTML. Render the segments in order, applying any styles flags and turning LINK parts into anchors. Use the rendering approach that fits your stack — the example below shows a minimal string-builder version:

function renderParts(parts) {
  let html = "";
  for (const part of parts) {
    if (part.type === "LINK") {
      html += `<a href="${part.url}" target="_blank" rel="noopener noreferrer">${part.text}</a>`;
    } else {
      const cls = part.styles?.includes("BOLD") ? "bold" : "";
      html += `<span class="${cls}">${part.text}</span>`;
    }
  }
  return html;
}

When the Klarna payment option is selected, reveal the supporting components (message, terms, payment_button); hide them again on deselection. Use whatever UI pattern your checkout already follows for other payment methods — there's nothing Klarna-specific here.

When the customer clicks the Klarna payment button, your server hands the purchase off to Worldpay — Worldpay then calls Klarna's Payment Authorize API on your behalf. The full request/response contract is owned by Worldpay; only the Klarna-specific identifier you must include is documented here.

Refer to Worldpay's API reference for the full request shape (amount, currency, customer, shipping, line items, supplementary purchase data, response codes, etc.).

If Worldpay returns STEP_UP_REQUIRED with a payment_request_url, perform a full-page HTTP 302 redirect to that URL. The customer completes the Klarna Purchase Journey on Klarna's hosted page, and Worldpay takes care of finalizing the authorization and notifying you of the outcome.

You don't need to subscribe to Klarna webhooks, monitor the Klarna payment request lifecycle, or handle the klarna_network_session_token yourself — Worldpay handles these on your behalf.

Once the payment is authorized — either directly or after a successful step-up — Worldpay notifies you that the order is completed. Redirect the customer to your confirmation page based on Worldpay's notification.

In rare cases where there's a discrepancy between the amount and purchase details submitted to Worldpay and the information Klarna sees during step-up, the authorization may be rejected and the customer asked to approve the purchase again through the step-up journey.