Skip to content

Klarna Beta

Last updated: 31st August 2022

Start accepting payments using Klarna, a favorite payment method in Europe.

With Klarna, customers can choose to either pay right away, in installments, or after 30 days.

To learn more, reach out to your Customer Success Manager or support@checkout.com.

Model

Gateway

Payment flow

Redirect

Payment method type

Buy Now, Pay Later

One-step payment

Authorization

Capture

Refund

Partial refund

Chargeback

Recurring payment


Supported countries and currencies

Supported countries

  • Austria
  • Denmark
  • Finland
  • Germany
  • Netherlands
  • Norway
  • Sweden
  • Switzerland
  • United Kingdom

Supported processing and settlement currencies

  • EUR
  • DKK
  • NOK
  • SEK
  • CHF
  • GBP

Klarna has a 4-step process:


Request a payment

For the full API specification, see the API reference.

    post

    https://api.checkout.com/payments

    Request example

    If a customer ID or email is not provided in the request, we automatically create a customer profile and return the customer ID in the response.

    You can pass in an optional custom_payment_method_ids array in the processing object to determine which promotional codes and offers should be displayed to the customer. For example, you can offer a longer monthly finance allowance. The option selected by the customer can be retrieved from the response's authorized_payment_method field.

    To enable promotional codes and offers, contact Klarna and ask them to configure these for your account.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    {
    "capture": "false",
    "source": {
    "account_holder": {
    "title": "Mr",
    "first_name": "Louis",
    "last_name": "Smith",
    "billing_address": {
    "address_line1": "10 Cavendish Square",
    "address_line2": "7th floor",
    "city": "London",
    "zip": "W1G 0PW",
    "country": "GB"
    },
    "email": "test@test.com",
    "date_of_birth": "1979-03-05",
    "gender": "male",
    "phone": {
    "country_code": "+44",
    "number": "20 7946 0868"
    }
    },
    "type": "klarna-v2"
    },
    "shipping": {
    "address": {
    "address_line1": "Von-Reiche-Straße 9",
    "address_line2": "6th floor",
    "city": "Furth",
    "zip": "63930",
    "country": "DE"
    },
    "phone": {
    "country_code": "+49",
    "number": "30 041008283"
    }
    },
    "items": [
    {
    "name": "Battery Power Pack 1",
    "quantity": 1,
    "unit_price": 500,
    "tax_rate": 1,
    "total_amount": 500,
    "total_tax_amount": 5
    },
    {
    "name": "Battery Power Pack 2",
    "quantity": 2,
    "unit_price": 250,
    "tax_rate": 1,
    "total_amount": 500,
    "total_tax_amount": 5
    }
    ],
    "processing": {
    "order_created_callback_url": "https://webhook.site/ce7c0f0f-8cc8-4a06-94e1-3c0f3fe04b16",
    "locale": "en-GB",
    "purchase_country": "GB",
    "tax_amount": 10,
    "custom_payment_method_ids": [
    "6m_149APR",
    "6m_0APR",
    "12m_149APR",
    "12m_0APR",
    "24m_149APR",
    "24m_0APR"
    ]
    },
    "reference": 387,
    "currency": "GBP",
    "amount": 1000,
    "processing_channel_id": "pc_nfk3nqms5xaeldmfbgeke7sgau",
    "success_url": "https://example.com/200",
    "failure_url": "https://example.com/422"
    }

    Response example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    {
    "id": "pay_aveot4p2oo7u5axj72rwf6vpfm",
    "status": "Pending",
    "reference": "359",
    "processing": {
    "session_id": "157b7665-93d7-4383-b2e0-2fc7213a1a4a",
    "client_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.dtxWM6MIcgoeMgH87tGvsNDY6cH"
    },
    "_links": {
    "self": {
    "href": "http://gwc.ckotech.co/gateway/payments/pay_aveot4p2oo7u5axj72rwf6vpfm"
    }
    }
    }

    Display the widget

    Load the Klarna widget on your page so the customer can choose on of the Klarna payment methods and complete payment authorization.

    Add the Klarna JavaScript SDK

    Insert the following code to your page to load the Klarna Payments library in your client:

    1
    2
    3
    4
    5
    6
    7
    //<![CDATA[
    window.klarnaAsyncCallback = function () {
    // This is where you start calling Klarna's JS SDK functions
    //
    // Klarna.Payments.init({ ... })
    };
    //]]>

    Initialize the Klarna SDK

    Initialize the payments library by calling the init method and passing the client_token value that you received in the payment request response.

    1
    2
    3
    4
    5
    6
    7
    try {
    Klarna.Payments.init({
    client_token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.dtxWM6MIcgoeMgH87tGvsNDY6cH"
    });
    } catch (e) {
    // Handle error
    }

    Add a container to the page

    Add a container to specify where the widget should be added in the page. The Klarna payment frame requires a minimum width of 280px.

    1
    <div id="klarna_container"></div>

    The payment methods you provided in the payment request's processing object will be displayed in the widget.

    Load the Klarna widget

    Load the widget on the page by calling the load method and passing the ID of the container you defined in a previous step. You must also specify a payment_method_categories value, as defined by Klarna's payment method grouping documentation.

    If the customer details change after the original payment request is made, you can use the load method to pass the updates to the session by adding the relevant information to the data object.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    Klarna.Payments.load({
    container: "#klarna_container",
    payment_method_category: 'pay_later'
    }, { // data object to pass updated order information
    "purchase_country": "GB",
    "purchase_currency": "GBP",
    "locale": "en-GB",
    "order_amount": 20,
    "order_tax_amount": 0,
    "order_lines": [{
    "type": "physical",
    "reference": "19-402",
    "name": "Battery Power Pack",
    "quantity": 2,
    "unit_price": 10,
    "tax_rate": 0,
    "total_amount": 20,
    "total_discount_amount": 0,
    "total_tax_amount": 0
    }]
    }
    , function(res) {
    console.debug(res);
    })

    Place the order

    If the payment authorization was successful, you'll receive a callback request at the URL you provided as the processing.order_created_callback_url field in the payment request.

    When processing a transaction via Klarna, you should only capture the payment once the goods have been shipped to the customer, unless you are selling an online service that the customer can access immediately.

    Request example

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    {
    "location": "https://qaapi.ckotech.co/payments/pay_aveot4p2oo7u5axj72rwf6vpfm",
    "value": {
    "response_code": "Authorized",
    "data": {
    "order_id": "63a2d996-16b3-4f65-a21e-d4a3bb43ca51",
    "redirect_url": null,
    "fraud_status": "ACCEPTED",
    "authorized_payment_method": {
    "type": "invoice",
    "description": null,
    "number_of_installments": null,
    "number_of_days": null
    }
    },
    "links": {
    "redirect": null,
    "void": {
    "name": null,
    "href": "https://qaapi.ckotech.co/orders/pay_aveot4p2oo7u5axj72rwf6vpfm/voids/{voidId}",
    "templated": true
    },
    "refund": null,
    "reconciliation": [
    {
    "name": null,
    "href": "https://qaapi.ckotech.co/payments/pay_aveot4p2oo7u5axj72rwf6vpfm/reconciliation",
    "templated": false
    }
    ],
    "capture": {
    "name": null,
    "href": "https://qaapi.ckotech.co/payments/pay_aveot4p2oo7u5axj72rwf6vpfm/captures/{captureId}",
    "templated": true
    },
    "self": {
    "name": null,
    "href": "https://qaapi.ckotech.co/payments/pay_aveot4p2oo7u5axj72rwf6vpfm",
    "templated": false
    },
    "curies": [
    {
    "name": "gw",
    "href": "https://qaapi.ckotech.co/relations/gw/{rel}",
    "templated": true
    }
    ]
    }
    },
    "formatters": [],
    "content_types": [],
    "declared_type": null,
    "status_code": 202
    }

    Capture a payment

    Full captures and partial captures are both supported.

    For partial captures, you must provide the amount, capture_type, and shipping_info fields.

    Endpoints

    For the full API specification, see the API reference.

      post

      https://api.checkout.com/payments/{id}/captures

      Request example

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      {
      "amount": 500,
      "description": "",
      "capture_type": "NonFinal",
      "reference": "551",
      "processing": {
      "shipping_delay": 0,
      "shipping_info": [
      {
      "return_shipping_company": "DHL",
      "return_tracking_number": "12345",
      "return_tracking_uri": "https://checkout-apm.eu.ngrok.io/success",
      "shipping_company": "DHL",
      "shipping_method": "DHLPackstation",
      "tracking_number": "12345",
      "tracking_uri": "https://checkout-apm.eu.ngrok.io/success"
      }
      ]
      }
      }

      Response example

      1
      2
      3
      4
      5
      6
      7
      8
      9
      {
      "action_id": "act_7d75pe3ewkhexo5a3f3x3hwb7y",
      "reference": "551",
      "_links": {
      "payment": {
      "href": "https://gwc.ckotech.co/gateway/payments/pay_u2y4xl4nkihexhcwnx4wwfqkoy"
      }
      }
      }

      Void a payment

      You can only void payments that are in an Authorized state.

        post

        https://api.checkout.com/payments/{id}/voids

        You do not need to send a request body to void a payment.

        Response example

        1
        2
        3
        4
        5
        6
        7
        8
        {
        "action_id": "act_nfpdpv6vmfeudc5xpnun2lsmzu",
        "_links": {
        "payment": {
        "href": "https://gwc.ckotech.co/gateway/payments/pay_rt6f2d5gqzieho4qt55ohtv4lq"
        }
        }
        }

        Get details about a payment

        You can retrieve details about an existing Klarna payment with the following endpoint.

        Endpoints

        For the full API specification, see the API reference.

          get

          https://api.checkout.com/payments/{id}

          Response example

          1
          2
          3
          4
          5
          6
          7
          8
          9
          10
          11
          12
          13
          14
          15
          16
          17
          18
          19
          20
          21
          22
          23
          24
          25
          26
          27
          28
          29
          30
          31
          32
          33
          34
          35
          36
          37
          38
          39
          40
          41
          42
          43
          44
          45
          46
          47
          48
          49
          50
          51
          52
          53
          54
          55
          56
          57
          58
          59
          60
          61
          62
          63
          64
          65
          66
          67
          68
          69
          70
          71
          72
          73
          74
          75
          76
          77
          78
          79
          80
          81
          82
          83
          84
          85
          86
          87
          88
          89
          90
          91
          92
          93
          94
          95
          96
          97
          98
          99
          {
          "id": "pay_swz22x2hkuyezdfftwdljsrivi",
          "requested_on": "2022-08-22T14:53:55.2129022Z",
          "source": {
          "type": "klarna-v2",
          "account_holder": {
          "title": "Mr",
          "first_name": "Louis",
          "last_name": "Smith",
          "billing_address": {
          "address_line1": "10 Cavendish Square",
          "address_line2": "7th floor",
          "city": "London",
          "zip": "W1G 0PW",
          "country": "GB"
          },
          "email": "test@test.com",
          "date_of_birth": "1979-03-05",
          "gender": "male",
          "phone": {
          "country_code": "+44",
          "number": "20 7946 0868"
          }
          }
          },
          "items": [
          {
          "name": "Battery Power Pack 1",
          "quantity": 1,
          "unit_price": 500,
          "total_amount": 500,
          "tax_rate": 1,
          "total_tax_amount": 5
          },
          {
          "name": "Battery Power Pack 2",
          "quantity": 2,
          "unit_price": 250,
          "total_amount": 500,
          "tax_rate": 1,
          "total_tax_amount": 5
          }
          ],
          "amount": 1000,
          "currency": "GBP",
          "payment_type": "Regular",
          "status": "Captured",
          "approved": true,
          "balances": {
          "total_authorized": 1000,
          "total_voided": 0,
          "available_to_void": 0,
          "total_captured": 1000,
          "available_to_capture": 0,
          "total_refunded": 0,
          "available_to_refund": 1000
          },
          "shipping": {
          "address": {
          "address_line1": "Von-Reiche-Straße 9",
          "address_line2": "6th floor",
          "city": "Furth",
          "zip": "63930",
          "country": "DE"
          },
          "phone": {
          "country_code": "+49",
          "number": "30 041 008 283"
          }
          },
          "processing": {
          "session_id": "4d738930-e058-4d47-939b-0f3e16dac5c9",
          "partner_order_id": "0d94e8bf-c8a3-4a2c-a2fb-2371eef6bc25",
          "fraud_status": "ACCEPTED",
          "provider_authorized_payment_method": {
          "type": "INVOICE",
          "description": "Pay later"
          },
          "custom_payment_method_ids": [
          "6m_149APR",
          "6m_0APR",
          "12m_149APR",
          "12m_0APR",
          "24m_149APR",
          "24m_0APR"
          ]
          },
          "_links": {
          "self": {
          "href": "https://gwc.ckotech.co/gateway/payments/pay_swz22x2hkuyezdfftwdljsrivi"
          },
          "actions": {
          "href": "https://gwc.ckotech.co/gateway/payments/pay_swz22x2hkuyezdfftwdljsrivi/actions"
          },
          "refund": {
          "href": "https://gwc.ckotech.co/gateway/payments/pay_swz22x2hkuyezdfftwdljsrivi/refunds"
          }
          }
          }

          Refund a payment

          Klarna supports both full and partial refunds. You can refund a payment through the Dashboard or by using the refund API.

          Endpoints

          For the full API specification, see the API reference.

            get

            https://api.checkout.com/payments/{id}/refunds

            Request example

            1
            2
            3
            {
            "amount": 1000
            }

            Response example

            1
            2
            3
            4
            5
            6
            7
            8
            {
            "action_id": "act_wzas76mywjze7k5bjkuigd732q",
            "_links": {
            "payment": {
            "href": "https://gwc.ckotech.co/gateway/payments/pay_swz22x2hkuyezdfftwdljsrivi"
            }
            }
            }

            Webhooks

            You may receive the following webhooks when using Klarna.

            WebhookDescription

            payment_pending

            Sent when a merchant initiates the payment request.

            payment_capture_pending

            Sent when a payment request has been successfully initiated and payment is pending for capture.

            payment_captured

            Sent when the payment has been successfully captured.

            payment_canceled

            Sent when the payment request fails, or is canceled.

            payment_refunded

            Sent when the payment has been (fully or partially) refunded.

            payment_voided

            Sent when the payment is voided after authorization.

            View all of our webhook notifications.


            Testing Klarna

            To start testing, contact your Customer Success Manager or Implementation Engineer to activate Klarna payments in the sandbox environment.

            1. Create a Klarna transaction as above.
            2. Display the Klarna widget.
            3. Select the desired payment method and pay.
            4. If asked to verify your details, follow Klarna's testing guide.