Klarna Drop-in integration

This page explains how to add Klarna to your existing iOS Drop-in integration.

Requirements

Select the server-side flow that your integration uses:

API reference

Select which endpoint you are using:

See examples of other Klarna-specific payment scenarios at Invoice lines and discounts.

Drop-in configuration

Capture the payment

If the capture delay is set to immediate and you comply with Klarna's Scheme Rules of shipping within 24 hours, then you can configure automatic capture when adding Klarna in your live Customer Area. Otherwise, you must manually capture Klarna payments within 90 days after authorization, even if you enable automatic capture on your merchant account. If the manual capture is not performed within 90 days, the authorization will expire.

Capture manually

To manually capture a Klarna payment, make a POST request to the /payments/{paymentPspReference}/captures endpoint.

1. When you are ready to capture the payment, make a POST /payments/{paymentPspReference}/captures request, where {paymentPspReference} is the PSP reference from the original payment (pre-authorization) response. Specify:

   Parameter	Required	Description
   merchantAccount		The name of your merchant account that is used to process the payment.
   amount.currency		The three-character ISO currency code.
   amount.value		The amount of the transaction, in minor units. This is the sum of the original, pre-authorized amount and all later adjustments.
   lineItems		Price and product information about the purchased items, to be included on the invoice sent to the shopper. For an authorization adjustment, always specify every line item, including all captured or refunded items. See examples of Klarna-specific payment scenarios at Invoice lines and discounts.
   reference		A reference that you specify for this payment modification, for use in your reconciliation process. The pspReference you received in the initial authorization response remains the primary merchant reference, and this reference does not overwrite it.

2. When you receive the /payments/{paymentPspReference}/captures response, note the following:

   • pspReference: The PSP reference associated with this /captures request. This is different from the PSP reference associated with the original payment (pre-authorization) request.
   • status: received
   • reference: Your reference to this payment modification, for use in your reconciliation process.

3. Wait for the webhook event. This informs you whether the final amount has been captured.
   If the capture is successful, this event contains:

   • eventCode: CAPTURE
   • originalReference: The pspReference of the pre-authorization.
   • pspReference: The PSP reference associated with this /payments/{paymentPspReference}/captures request.
   • success: true

   If the capture fails, this event contains success: false. Review the reason you received in the webhook event, fix the issue, and submit the capture request again.

See examples of other Klarna-specific payment scenarios at Invoice lines and discounts.

Shipping and tracking information (optional)

You can optionally use additionalData.openinvoicedata to include shipping and tracking information. This adds information about how the products are shipped to the deliveryAddress that you specified in the /payments request. The shipping and tracking information maps to Klarna's shipping info object.

If you have the shipping and tracking information at the time of the capture, we recommend that you send it to improve the overall shopper experience. Klarna includes this information in their app, where the info is updated based on the tracking details.

• If all items are shipped with the same provider, specify the shipping and tracking information once, as shown in the capture example below.
• If one or more items in the order are shipped with different a different provider or tracking details, specify the shipping and tracking information as an array.
• You cannot specify different delivery addresses for a single order with multiple items.

You will receive a /capture response containing a pspReference associated with this request. Once we have processed your request, you will also receive a CAPTURE webhook. For more information, refer to Capture.

Partial captures

To partially capture a Klarna payment, specify in your call to the /capture endpoint:

• modificationAmount: The amount that the shopper should pay. This should be less than the authorised amount.
• additionalData.openinvoicedata: Price, product and optionally shipping and tracking information for the items that the shopper should pay for, to be included on the invoice. For the partial capture to be successful, the amounts stated in openinvoicedata need to be correct. You can use the same fields as listed in the manual captures section.

For more information and an example, refer to Invoice lines.

Recurring payments

To make recurring Klarna payments you need to:

1. Create a shopper token.
2. Use the token to make future payments for the shopper.

Create a token

To create a token, include in your /payments request:

• storePaymentMethod: true
• shopperReference: Your unique identifier for the shopper.

When the payment has been settled, you receive a webhook containing:

• eventCode: RECURRING_CONTRACT
• originalReference: The pspReference of the initial payment.
• pspReference: This is the token that you need to make recurring payments for this shopper.

Make a payment with a token

To make a payment with the token, include in your /payments request:

• shopperReference: The unique shopper identifier that you specified when creating the token.
• paymentMethod.storedPaymentMethodId: The pspReference from the RECURRING_CONTRACT webhook.
  You can also get this value by using the /listRecurringDetails endpoint.
• shopperInteraction: ContAuth

• recurringProcessingModel: The type of recurring payment that you want to make.
  Possible recurringProcessingModel values:

  recurringProcessingModel	Description
  CardOnFile	Online purchase where shopper is actively making a purchase using their previously stored payment details.
  Subscription	A series of transactions with fixed or variable amounts, following a fixed time interval. This is the default value for payment requests where shopperInteraction: ContAuth
  UnscheduledCardOnFile	Contracts that occur on a non-fixed schedule using stored payment details. For example, automatic top-ups when cardholder's balance drops below certain amount.

The following is a sample request for Klarna Pay Now, when the shopper is actively making a purchase using previously stored payment details:

Test and go live

Before accepting live payments, test your integration using the test environment and sample data provided by Klarna.

You can then check the status of Klarna test payments in your Customer Area > Transactions > Payments.

Before you go live

Make sure that:

• You have added Klarna in your live Customer Area.
• You have considered Klarna's legal and privacy information.
• You follow the Klarna guidelines on how to present Klarna in your checkout.
• The invoice lines and VAT are shown correctly on Klarna's pages.
• If a shopper gets rejected by Klarna, you offer them another payment method.
• You pass the shopper's name and address in your payment request. This is optional, but providing these parameters improves the shopper experience and increases conversion rates.

Testing in live environment

When testing Klarna payments in the live environment, make sure that you:

• Provide real shopper data. For example, your real name, personal email, personal mobile, and home and billing address. Do not provide a company address as billing address.
• Choose an item with a reasonable amount that meets Klarna's minimum requirements. For example, for Pay over time, Klarna requires a minimum amount of GBP 35. Klarna can reject a request if the product is too expensive and they do not have enough transaction history for the shopper.
• Do not do multiple tests in a short period from the same device or IP address. Otherwise, velocity rule checks are triggered, which will lead to the transaction being rejected.

If the conditions above are not met, you can receive a resultCode of Refused. The shopper sees a page with an "Option Not Available" message instead of the Klarna Payments widget. Note that these checks are bypassed in test and are only applied in the live environment.

See Klarna raw acquirer responses for the most common responses for successful, refused, failed, or cancelled transactions.

See also