Klarna payments

This article will provide the details you need to implement Klarna Payments using Storefront API.

API References

• Klarna Payments API
• Klarna Payments SDK
• Centra Storefront API

Plugin Configuration

In order to use Klarna Payments, a plugin needs to be setup and configured for the store where it’s intended to be used.

Require Fields

Required fields in the configuration

• Status set to active
• Secret
• E-Store ID
• Klarna Endpoint

Plugin name is internal, while "Name in Frontend", will be the name of the payment plugin in the response from Storefront API.

Initialization Flow

Call the paymentInstructions mutation:

1. Centra will create a Klarna Payments session and return a client_token in the response from Storefront API
2. Storefront app calls SDK.init() with client_token, obtained from the paymentInstruction response
3. Storefront app calls SDK.load() and displays the Klarna Payments widget on the checkout page

mutation paymentInstructions($input: PaymentInstructionsInput) {
  paymentInstructions(input: $input) {
    userErrors {
      path
      message
    }
    action {
      action
      ... on FormPaymentAction {
        html
        formFields
        formType
      }
      ... on JavascriptPaymentAction {
        formFields
        formType
        script
      }
      ... on RedirectPaymentAction {
        url
      }
      ... on SuccessPaymentAction {
        order {
          number
        }
      }
    }
    selection {
      ...SelectionFields
      checkout {
        widgets {
          kind
          ... on KlarnaPaymentWidget {
            authorizePayload
            client_token
          }
        }
        ...AdditionalCheckoutFields
      }
    }
  }
}

Response

{
  "data": {
    "paymentInstructions": {
      "action": {
        "action": "FORM",
        "formFields": {
          "authorizePayload": {
            /* ... */
          },
          "client_token": "..."
        }
      },
      "selection": {
        "id": "...",
        "checkout": {
          "widgets": [
            {
              "kind": "PAYMENT",
              "client_token": "...",
              "authorizePayload": {
                /* ... */
              },
              "replace_snippet": false
            }
          ]
          /* ...otherFields */
        }
      },
      "userErrors": []
    }
  }
}

Authorization and Order Placement

Authorization begins when the customer chooses Klarna Payments by clicking "Pay with Klarna".

The storefront app calls the authorize() function from the Klarna Payments SDK using the authorizePayload under the selection.checkout.widgets array obtained from paymentInstructions mutation response.

If the selection state changes after the initial call to paymentInstructions call, the updated authorizePayload is included in every selection response while Klarna Payments is the active payment method. Ensure the authorizePayload used for authorize() is always up-to-date for the payment to succeed.

1. Shopper proceeds to initiate payment with Klarna Payments.
2. Storefront app calls SDK.authorize(authorizePayload).

window.Klarna?.Payments.authorize(
  { payment_method_category: 'klarna' },
  klarnaWidget?.authorizePayload ?? authorizePayload,
  result => {
    if (result.approved) {
      router.push(
        `/success?authorization_token=${encodeURIComponent(result.authorization_token)}&centraPaymentMethod=${paymentMethod?.id ?? ''}`
      );
    } else {
      console.error(result.error);
      setError(t('checkout:payment-failed'));
    }
  }
);

3. Klarna Payments pop-up window is opened.
4. Shopper provide payment details and confirms payment.
5. Callback function is fired with result as a parameter.
6. Shopper is redirected according to the callback function’s logic.
7. Storefront app calls paymentResult with the paymentMethodFields collected from query and post parameters.
8. Centra creates the order in Klarna using the authorization_token received from the storefront. At this moment the shopper will be charged.
9. Centra responds to the storefront app, with order response and parameters from Klarna including redirect_url.
10. The storefront app redirects the shopper to the payment success page with response.order.paymentMethodData.redirect_url.

Error handling

Refer to the following Klarna guides for proper frontend widget interaction and error handling:

• User interaction during the call
• Responses

Handling Updates in the Checkout

This section refers to how to handle any updates that happens in the checkout, after a session has been initiated with Klarna Payments via the paymentInstructions mutation.

This includes:

• Item quantity updates
• Selection line updates
• Address updates
• Applying/removing a voucher
• Selection country update

After selecting Klarna Payments and initializing payment, a Klarna Payments session is created. Each selection response includes an object under selection.checkout.widgets (there would be multiple widgets, ensure to look for the Klarna one) , eliminating the need for extra API calls during checkout updates.

The object includes all fields needed to display/reload the payment widget and start authorization:

• client_token - Required to call SDK.init(client_token) that initiates the SDK.
• replaceSnippet - Indicates whether the SDK needs to be reinitialized by calling SDK.init(client_token)
• authorizePayload - Payload required for the authorization call SDK.authorize(authorizePayload).

Re-initialization of the payment widget

After displaying a Klarna Payments widget, check the replace_snippet field on every selection update to determine if the SDK needs reinitialization. The following snippet shows how to handle this flag.

function handleKlarnaReplaceSnippet(response) {
  const { replaceSnippet, client_token } =
    response.selection.pluginFields.klarnaPayments;

  if (replaceSnippet === true) {
    document.getElementById('payment-container').innerHTML = ''; //clear old one entirely
    Klarna.Payments.init({ client_token });
  }

  Klarna.Payments.load(
    {
      container: '#payment-container',
      payment_method_category: 'klarna',
    },
    () => {
      const message =
        replaceSnippet === false
          ? 'Klarna Payments widget loaded without re-initialization'
          : 'Klarna Payments widget loaded with re-initialization after client_token update';

      console.log(message);
    }
  );
}

Best practices

Locking the payment widget during selection updates in the checkout

Once the Klarna session is initialized, Centra updates Klarna whenever the selection changes. Prevent shoppers from finalizing payment while updates are processed by Centra and Klarna. For Klarna Payments, lock the widget on the frontend to ensure it’s non-interactive during updates, avoiding inconsistencies between the payment and the Centra order.

Collecting customer address data

Klarna Payments uses customer address data for fraud prevention and payment options, included in the SDK.authorize() call. The authorizePayload, from selection.checkout.widgets, must match the checkout state. Ensure all data is sent to Centra before payment.

Implementation scenarios:

• Multistep checkout: Customers enter address data before viewing payment methods.
• Single-step checkout: Payment methods load immediately, but the Klarna widget stays locked until address data is complete.

Handling of multiple tabs

If a shopper opens a second tab, modifies their selection, and proceeds to checkout, a new payment session with a different client_token and authorizePayload is created. Returning to the first tab and proceeding with payment can cause errors due to outdated session data.

Steps:

1. Shopper opens checkout in the first tab and proceeds to payment.
2. Shopper opens a second tab, modifies selection, and proceeds to checkout.
3. A new session is created with a new client_token and authorizePayload.
4. Customer returns to the first tab and proceeds to payment.

Solution: Synchronize the Klarna Payments session state across tabs. When reopening a previously initialized checkout, fetch the latest selection and widgetsdata. If the client_token has changed, reinitialize the SDK and reload the widget using the new client_token as described in "Re-initialization of the payment widget."

On-site messaging

On-site messaging informs customers about Klarna payment options before checkout. Its integration is outside Centra's scope but can be implemented client-side.

This guide offers step-by-step integration instructions.