Klarna Payments

Klarna is a popular Swedish bank offering payers in Europe and the United States (USA) a range of flexible financing options when purchasing goods online. Using Klarna payers have the option to pay immediately, delay the payment until after delivery or spread the cost over a number of installments.

Klarna is a supported browser payment method in the MasterCard Payment Gateway. This page describes integration details specific to Klarna. It's recommended that you read the integration guidelines for browser payments, before building a Klarna integration.

Prerequisites

To offer Klarna as a payment method via the MasterCard Payment Gateway:

  • You must be registered with your browser payments service provider.
  • Your merchant profile on the gateway must be configured using the details of your account with the browser payments service provider.
  • You must have a bank account in one of the supported currencies registered against your merchant account at your browser payments service provider.

Klarna Pay Later

Klarna 'Pay Later' is the delayed payment option supported by the MasterCard Payment Gateway. Payers review the items delivered to them by the merchant and keep only those items that they intend to purchase and pay for, all unwanted items are returned. For approved payments, Klarna assumes all credit and fraud risk, and you are paid by Klarna for the full order amount. Every item returned to you by the payer must be refunded using the Refund operation. Orders can effectively be cancelled by performing a Refund for the full purchase amount. Klarna subsequently invoices the payer and collects the payment, providing e-mail notifications and reminders in advance of the payment due date.

Klarna browser payments are supported for transactions originating from the following countries with their corresponding currencies.

Country Currency
Austria (AUT) EUR
Germany (DEU) EUR
Netherlands (NLD) EUR
Finland (FIN) EUR
Sweden (SWE) SEK
Norway (NOR) NOK
Great Britain (GBR) GBP
Denmark (DNK) DKK

Klarna Financing

Klarna "Financing" is a flexible payment option supported by the MasterCard Payment Gateway. It is a long-term financing agreement wherein the payer can purchase an item and pay in installments. You can choose to repay in six to thirty-six equal monthly installments including interest (if any), pay a minimum amount each month, or pay off the entire amount within a month.

Klarna browser payments are supported for transactions originating from the following countries with their corresponding currencies.

Country Currency
Austria (AUT) EUR
Germany (DEU) EUR
Netherlands (NLD) EUR
Finland (FIN) EUR
Sweden (SWE) SEK
Norway (NOR) NOK
Great Britain (GBR) GBP
Denmark (DNK) DKK

Klarna Integration

Klarna via Hosted Checkout

Hosted Checkout integration allows you to collect payment details from your payer through an interaction hosted and displayed by the MasterCard Payment Gateway.

Klarna Pay Later

With Hosted Checkout integrations version 52 and later, Klarna Pay Later is automatically available to your payers when you are enabled and configured for it by your payment service provider.

For details, see Browser Payments via Hosted Checkout Integration.

Klarna via Direct Payment

Direct Payment integration allows you to offer the Klarna payment method on your own checkout page.

Klarna Pay Later

Klarna Pay Later is supported from the API version 52 onwards.

Make the Initiate Browser Payment request where sourceOfFunds.type = KLARNA_PAY_LATER and browserPayment.operation = PAY (the Authorize operation is not supported by Klarna).

If your API version is lower than 61, use the sourceOfFunds.type = KLARNA when you make the Initiate Browser Payment request.
Sample Code to Initiate Klarna Pay Later Payment

{
  "apiOperation": "INITIATE_BROWSER_PAYMENT",
  "browserPayment": {
    "operation": "PAY",
    "returnUrl": "http://www.mastercard.com/complete.html"
  },
  "customer": {
    "email": "john.smith@example.com",
    "firstName": "John",
    "lastName": "Smith",
    "mobilePhone": "01234567890"
  },
  "billing": {
    "address": {
      "street": "10 Upper Bank Street",
      "postcodeZip": "E14 5NP",
      "city": "London",
      "country": "GBR"
    }
  },
  "order": {
    "amount": 57.2,
    "currency": "GBP",
    "item": [
      {
        "name": "Item A",
        "quantity": "1",
        "unitPrice": 70.83,
        "unitDiscountAmount": 48.16,
        "unitTaxAmount": 4.53,
        "detail": {
          "unitTaxRate": 0.2
        }
      },
      {
        "name": "Item B",
        "quantity": "1",
        "unitPrice": 20.83,
        "unitTaxAmount": 4.17,
        "detail": {
          "unitTaxRate": 0.2
        }
      },
      {
        "name": "Shipping & Handling",
        "quantity": "1",
        "unitPrice": 4.17,
        "unitTaxAmount": 0.83,
        "detail": {
        "unitTaxRate": 0.2
      }
      }
    ]
  },
  "sourceOfFunds": {
    "type": "KLARNA_PAY_LATER"
  }
}
  

Klarna Financing

Klarna Financing is supported from the API version 61 onwards.

Make an Initiate Browser Payment request where sourceOfFunds.type = KLARNA_FINANCING and browserPayment.operation = PAY (the Authorize operation is not supported by Klarna).

Sample Code to Initiate Klarna Financing Payment
{
   "apiOperation":"INITIATE_BROWSER_PAYMENT",
   "browserPayment":{
      "operation":"PAY",
      "returnUrl":"http://www.mastercard.com/complete.html"
   },
   "customer":{
      "email":"john.smith@example.com",
      "firstName":"John",
      "lastName":"Smith",
      "mobilePhone":"01234567890"
   },
   "billing":{
      "address":{
         "street":"10 Upper Bank Street",
         "postcodeZip":"E14 5NP",
         "city":"London",
         "country":"GBR"
      }
   },
   "order":{
      "amount":99.2,
      "currency":"GBP",
      "item":[
         {
           "name":"Blue Jeans",
           "quantity":"1",
           "unitPrice":70.83,
           "unitDiscountAmount":48.16,
           "unitTaxAmount":4.53,
           "detail":{
             "unitTaxRate":0.2
            }
         },
         {
            "name":"Red Shirt",
            "quantity":"1",
            "unitPrice":20.83,
            "unitTaxAmount":4.17,
            "detail":{
              "unitTaxRate":0.2
            }
         },
         {
            "name":"Leather Belt",
            "quantity":"1",
            "unitPrice":25,
            "unitTaxAmount":5,
            "detail":{
              "unitTaxRate":0.2
            }
         },
         {
            "name":"Baseball Cap",
            "quantity":"1",
            "unitPrice":10,
            "unitTaxAmount":2,
            "detail":{
              "unitTaxRate":0.2
            }
         },
         {
            "name":"Shipping and Handling",
            "quantity":"1",
            "unitPrice":4.17,
            "unitTaxAmount":0.83,
            "detail":{
               "unitTaxRate":0.2
            }
         }
      ]
   },
   "sourceOfFunds":{
      "type":"KLARNA_FINANCING"
   }
}

Klarna Payment Processing Details

In addition to the standard fields required in a browser payment request, you need to provide the following required information for the processing of Klarna payments.

Billing Address and Contact Details

These fields are mandatory unless otherwise stated and are required to support the Klarna risk assessment and credit checking processes. The payer's contact information is used to communicate with the payer and to provide electronic invoices and payment notifications.

  • billing.address.city
  • billing.address.country
  • billing.address.postcodeZip
  • billing.address.street
  • customer.email
  • customer.firstName
  • customer.lastName
  • customer.mobilePhone: This field is required when customer.phone is not provided.
  • customer.phone: This field is required when customer.mobilePhone is not provided.

Shipping Address and Contact Details

These fields are mandatory when a value for any shipping.address.* or shipping.contact.* field is provided.

  • shipping.address.city
  • shipping.address.country
  • shipping.address.postcodeZip
  • shipping.address.street
  • shipping.contact.email
  • shipping.contact.firstName
  • shipping.contact.lastName

Order Item Details

Provide full details about each order item purchased so that Klarna can correctly validate and display this information to the payer and to support Klarna's risk and credit checking processes.

  • order.item[n].name
  • order.item[n].quantity: The value of this field must be an integer.
  • order.item[n].unitPrice
  • order.item[n].unitDiscountAmount: This field is required when the item has been discounted and must be provided if a value is provided in the order.discount.amount field.
  • order.item[n].unitTaxAmount: This field is required when the payer is required to pay tax on the item.
  • order.item[n].detail.unitTaxRate: This field is required when a value for unit tax amount has been provided.

Shipping and Handling

The total tax amount payable for the order is displayed to the payer during the payment flow. If the amount payable for shipping and handling includes tax then you must create an order line to represent shipping and handling so that the discrete tax amount can be provided. If tax does not apply then the shipping and handling amount can be provided in the order.shippingAndHandlingAmount field.

Preferred Language

You can set the language that you prefer Klarna to use for pages displayed to the payer by providing the browserPayment.preferredLanguage field in the Initiate Browser Payment request. However, for Klarna only the primary national language of the billing.address.country or English will be supported.

Chargebacks

Klarna payments are at risk of chargebacks. If a payer successfully disputes a payment with Klarna then a chargeback transaction will be created on the order. For more information, see chargeback transaction.

Note that in the case of a Klarna chargeback reversal, this event is not reflected in the gateway.

How to Interpret the Transaction Result

The table below shows the transaction response codes for the possible scenarios you may encounter after initiating a Klarna payment.

Initiate Browser Payment Response
What This Means...
response.gatewayCode=SUBMITTED
result=SUCCESS
Redirect the payer using the URL provided in the response.
Retrieve Transaction/Retrieve Order Response
What This Means...
response.gatewayCode=APPROVED
result=SUCCESS
The payment is successful.
response.gatewayCode=PENDING
result=PENDING
The MasterCard Payment Gateway is waiting for a notification from the acquirer about the payment result. Try RETRIEVE_TRANSACTION again later or listen to notifications from the MasterCard Payment Gateway.
response.gatewayCode=CANCELLED
result=FAILURE
The payer has cancelled the interaction for this payment. Offer the payer the option to try another payment method.
response.gatewayCode=DECLINED or ACQUIRER_SYSTEM_ERROR
result=FAILURE
The payment was declined. Offer the payer the option to try another payment method.
In the case of an ACQUIRER_SYSTEM_ERROR you may want to inquire with the acquirer the reason for payment failure, or you can try RETRIEVE_TRANSACTION again.
response.gatewayCode=TIMED_OUT
result=FAILURE
Treat this as a declined payment. The gateway will make an attempt to ensure the transaction is not successful or will revert the transaction.

Klarna Order ID

For approved payments, the gateway will provide you with the ID that Klarna has assigned to this order in the field transaction.acquirer.additionalResponseData. This may be useful information for communications you may have directly with Klarna.

Web Hook Notifications

If you have subscribed to gateway web hook notifications, you may receive additional notifications for funding status updates and chargebacks.

Testing Your Integration

The MasterCard Payment Gateway provides a browser payments emulator that allows you to test your Klarna integration.

Copyright © 2021 MasterCard