Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.


General Notes

to type of payment

Overview of deviations

Payment Type

Countries

Currency

B2C

B2B

Invoice

  • Danmark
  • Germany
  • Finland
  • The Netherlands
  • Norway
  • Austria
  • Sweden
  • Euro
  • Danish crowns
  • Norwegian crowns
  • Swedish crowns

yes

no

Installment
  • Danmark
  • Germany
  • Finland
  • The

    ("Pay later")

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


    • Euro
    • Danish crowns
    • Norwegian crowns
    • Swedish

    • crowns

    • Swiss Francs

    yesno

    API-Requests - special notes / deviations


    Installments
    ("Slice it")

    Direct Debit
    ("Pay now")


    Klarna requires
    UI Text Box
    typeinfo
    note

    B2B transactions are currently only supported in Finland, Germany, Norway and Sweden.

    API-Requests - Special Notes / Deviations

    Overview of Deviations

    UI Text Box
    typeinfo
    • Klarna requires more specific customer data - depending on country of customer
    • Status "PENDING" has to be processed
      • for API-response "PENDING" implementation of API-version 3.11 or higher is required
      • for TransactionStatus "pending"
      • API version (question)
      • Notify-Version (question)implementation of notify-version 7.6 or higher is required
    • Request "capture" has to use parameter "capturemode"
    • Request "debit" has to use parameter "settleaccount"
    • add_paydata and workorderid have to be used for update of shopping cart

    Clearingtype / Clearingsubtype

    clearingtype

    financingtype
    fncKlarna payment types are handled as a financing payment
    financingtypeKLSKlarna Installment
    financingtypeKLVKlarna Invoice

    Summary

    Klarna Checkout is divided in 3 steps.

    UI Steps UI Step

    Create a new session

    In the first step you need to setup a new checkout session. You can do so by sending a genericpaynent-request to our server api as listed below.

    Please make sure to send the customer data within this request as they're needed to initiate a new session.

    Optional

    If the customer leaves the checkout page and comes back later, you can update the created session and change for example the address data.

    UI Step

    Handle token

    Part of the response is a client token. This token needs to be passed to the Klarna Widget. This Widget sends the client token together with the selected payment method (e.g. "Klarna Pay Later") to Klarna to get a authorization token.

    UI Step

    Finalize the checkout ((pre-)authorization)

    In the last step, you need to send the authorization token received by Klarna widget as part of the (pre-)authorization request to our server api.

    UI Text Box
    typenote

    The response contains a redirect-URL. You need to redirect the customer to this url, so that Klarna is able to securely handle data and optimize purchase flow.

    draw.io DiagrambordertrueviewerToolbartruefitWindowfalsediagramNameklarna_checkoutsimpleViewerfalsewidthdiagramWidth1401revision3

    Creating a new session via our server api

    In the first step you need to setup a new checkout session. You can do so by sending a genericpamynet-request to our server api as listed below.

    Please make sure to send the customer data within this request as they're needed to initiate a new session.

    → Genericpayment start_session

    Optional update session

    If the customer leaves the checkout page and comes back later, you can update the created session and change for example the address data.

    → Genericpayment update_session

    Token-handling via Klarna Widget

    Part of the response is a client token. This token needs to be passed to the Klarna Widget. This Widget sends the client token together with the selected payment method (e.g. "Klarna Pay Later") to Klarna to get a authorization token.

    → Widget

    Finalizing the checkout ((pre-)authorization) via our server api

    In the last step, you need to send the authorization token received by Klarna widget as part of the (pre-)authorization request to our server api.

    → Preauthorization/Authorization

    Anchorstart_sessionstart_session

    Genericpayment start_session

    Request "generic start session"

    API parameter

    RequiredFormatCommentsadd_paydata[action]+Default

    Fixed value "start_session"

    add_paydata[merchant_data]-BASE 64 String"EMD" - Extra Merchant Data - means that integration with any such package depends on (i) merchant’s offering and (ii)
    merchant’s technical possibilities. It is not to be interpreted in such a way that EMD is not required at all.
    firstname+AN..50First namelastname+AN2..50Surnamestreet+AN1..50

    Street number and name

    (required: at least one character)

    zip+AN2..10

    Postcode, format [a-zA-Z0-9_.-/ ]{2,10}

    city+AN2..50Citycountry+DefaultCountry (ISO 3166)addressaddition+AN1..50

    Address line 2 (e.g. "7th floor", "c/o Maier")

    genderoDefaultf=female, m=maleip+AN..39

    Customer's IP-V4-address (123.123.123.123) or IP
    V6-address

    email+AN..254Email addresstelephonenumber+AN..30Telephone numberbirthdayoN8Date of birth (YYYYMMDD)

    shipping_firstname

    -AN..50First nameshipping_lastname-AN..50Surnameshipping_company-AN2..50Companyshipping_street-AN1..50Street number and name (required: at least one character)shipping_zip-AN2..10Postcode, format [a-zA-Z0-9_.-/]{2,10}shipping_city-AN2..50Cityshipping_country-DefaultCountry (ISO 3166)add_paydata[last_four_ssn]-Last four digits for customer social security number.add_paydata[organization_entity_type]-Only relevant for B2B transactions.personalidoAN..32

    Person specific numbers or characters

    it[n]+Default

    For KLV / KLS: Item type

    goods Goods
    shipment Shipping charges
    handling Handling fee
    voucher Voucher / discount
    id[n]+AN..32

    Product number, order number, etc.
    Permitted symbols:
    0-9 a-z A-Z ()[]{} +-_#/:
    [n] starting with [1]; serially numbered; max [400]

    pr[n]+N..10

    Unit gross price in cent, max. 19 999 999 99
    [n] starting with [1]; serially numbered; max [400]

    no[n]+N..6

    Quantity
    [n] starting with [1]; serially numbered; max [400]

    de[n]+AN..50

    Description
    [n] starting with [1]; serially numbered; max [400]

    va[n]+N..4

    VAT rate (% or bp) of gross price
    Mandatory for payment type KLV, KLS
    [n] starting with [1]; serially numbered; max [400]

    add_paydata[klsid]+

    Mandatory for Klarna Installment (KLS): Campaign code

    Response "genericpayment - start_session"

    API parameter

    RequiredComments

    add_paydata[session_id]

    +Identifier for the started session at Klarnaadd_paydata[client_token]+Client token to authorize the session for payment via Klarna Widgetadd_paydata[authorized_payment_method]+Name of payment that got authorized for customer payment. (You will only receive the parameters according to the payment method you selected via clearingtype and financingtype)add_paydata[payment_method_category_name]+Name of Klarna payment category
    add_paydata[payment_method_category_identifier]+Identifier for Klarna payment categoryadd_paydata[payment_method_category_asset_url_descriptive]+URL of Klarna payment category assets for descriptive design (payment method identified by small icon and test on badge)
    add_paydata[payment_method_category_asset_url_standard]+URL of Klarna payment category assets for standard design (payment method only identified by small icon on badge)
    status+APPROVEDworkorderid+ERRORerrorcode+errormessage+customermessage+
    Code Block
    add_paydata[action]=start_session
    aid=111111
    amount=2222
    api_version=1.00
    birthday=1958101
    city=Neuss
    clearingtype=fnc
    country=DE
    currency=EUR
    de[1]=for
    ocean use only
    email=klarna@approved.de
    encoding=UTF-8
    financingtype=KLS
    firstname=Testperson-de
    gender=m
    id[1]=boat66
    it[1]=goods
    key=abcd12345698fffkfk
    language=de
    lastname=Approved
    mid=11111
    mode=test
    no[1]=1
    portalid=2011111
    pr[1]=8540
    request=genericpayment
    salutation=Herr
    street=Hellersbergstraße 14
    telephonenumber=01522113356
    va[1]=1900
    zip=41460
    Code Blockstatus=OK add_paydata[payment_method_category_name_3]=Slice it. add_paydata[payment_method_category_name_2]=Pay later. add_paydata[payment_method_category_name_1]=Direct debit add_paydata[session_id]=123-2227-456-avc11-fefe456 add_paydata[payment_method_category_identifier_3]=pay_over_time add_paydata[client_token]=W9uX2lkIiA6ICI3MGFjNGI3Ny0yMjI3LTdkNDEtY add_paydata[payment_method_category_identifier_2]=pay_later add_paydata[payment_method_category_asset_url_standard_2]=https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/pay_later/standard/pink.svg add_paydata[payment_method_category_asset_url_standard_1]=https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/pay_now/standard/pink.svg add_paydata[payment_method_category_asset_url_standard_3]=https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/slice_it/standard/pink.svg add_paydata[payment_method_category_asset_url_descriptive_3]=https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/slice_it/descriptive/pink.svg
    KISKlarna "Slice It" (Installments)
    fnc
    KIVKlarna "Pay Later" (Invoice)
    fncKDDKlarna "Pay Now" (Direct Debit)
    fncKBTKlarna "Pay Now" (Direct Bank Transfer)

    Summary

    Enabling your customers to pay via Klarna requires you to integrate the Klarna payment method into your checkout process. In order to get an overview of the relationship and interaction on your checkout please see the following diagram. (This diagram is adopted from the official Klarna documentation: Klarna Docs - Offering Klarna payment methods to your customers)

    Image Added


    Establishing Klarna Checkout is a 3 step process.

    UI Steps


    UI Step

    Create a New Session

    The first step is to setup a new checkout session by sending a genericpayment-request to our server API as listed below. This step is a pre-condition for loading the Klarna widget.

    Please make sure to send the customer data within this request as it is needed to initiate a new session. A session will remain valid for 48 hours after the last update.

    → Genericpayment start_session

    Optional - Update the Session

    If the customer leaves the checkout page and returns at a later point in time, you can update the created session and change for example the address data.

    → Genericpayment update_session


    UI Step

    Handle Token

    Part of the response is a client token. This token needs to be passed to the Klarna Widget. This Widget sends the client token together with the selected payment method (e.g. "Klarna Pay Later") to Klarna to get a authorization token.

    → Widget


    UI Step

    Finalize the Checkout ((Pre-)Authorization)

    In the last step, you need to send the authorization token received by Klarna widget as part of the (pre-)authorization request to our server api.

    → Preauthorization/Authorization

    UI Text Box
    typenote

    The response contains a redirect-URL. You need to redirect the customer to this url, so that Klarna is able to securely handle data and optimize purchase flow. The customer doesn't need to take any action and will not notice this step in the background.



    Klarna Checkout Processing Sequence

    draw.io Diagram
    bordertrue
    viewerToolbartrue
    fitWindowfalse
    diagramNameklarna_checkout
    simpleViewerfalse
    width600
    diagramWidth1401
    revision6

    General Integration Information

    There are a few things you need to take care of, when integrating Klarna checkout in your shop.

    • You need to ensure, that the customer only triggers the session start by deliberately choosing Klarna as a payment method. As personal data will be sent to Klarna, the customer has to actively confirm this (for example: "By selecting this payment method we will send personal data to Klarna. Please confirm.").
    • After confirmation of the payment method, you want to start with the first calls to server API as described above and then display the Klarna Widget. This Klarna Widget needs defined parameters to only display the chosen payment method, even if the widget is capable of displaying more than one Klarna payment method. For example after selecting "Klarna Pay Later", the widget should look something like this:Image Added


    Overview Client-Side Implementation

    Anchor
    widget
    widget
    Display Klarna Widget

    The following integration steps are taken from Klarna documentation ( https://developers.klarna.com/documentation/klarna-payments/integration-guide/present-klarna-widget )

    After creating a new session, you want to present the Klarna widget to your customer. This widget allows you to present all 3 payment methods offered by Klarna to the customer or define what payment method should be presented to the customer. The Klarna widget is rendered using JavaScript SDK. 

    UI Steps


    UI Step

    Add SDK to your page (insert in body)

    Code Block
    <script>
      window.klarnaAsyncCallback = function () {
    
        // This is where you start calling Klarna's JS SDK functions
        // 
        // Klarna.Payments.init({....})
    
      };
    </script>
    <script src="https://x.klarnacdn.net/kp/lib/v1/api.js" async></script>



    UI Step

    Initialize SDK and place a container on your page. Please note that the Klarna widget requires a minimum width of 280px.

    Code Block
    Klarna.Payments.init({
      client_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.dtxWM6MIcgoeMgH87tGvsNDY6cH'
    })


    Code Block
    <div id="klarna_container"></div>



    UI Step

    Load Klarna Widget

    When loading the Klarna widget, one needs to peovide the container ID established in the previous step and specify the payment_method_category. The payment_method_category specifies which of Klarna´s customer offerings (e.g. Pay now, Pay later, or Slice it) will be shown in the widget.

    Code Block
    Klarna.Payments.load({
        container: '#klarna-payments-container',
        payment_method_category: 'pay_later'
      }, function (res) {
        console.debug(res);
    })



    UI Step

    Receive Response from load call

    Klarna’s widget uses the show_form:true/false field as a response flag to load and to authorize calls in the Javascript SDK. In addition the object "error" can be retrieved to receive further information about potential problems. The response information enables you to display to your customer Klarna as a payment method only when it can actually be utilised by your customer. In summary, there are three situations deriving from the "Receive Response" call.

    Positive Response

    If show_form: true, and there are no errors in the object returned, Klarna renders the payment options available to the customer in the widget.

    Code Block
    {
    show_form: true
    }

    Adjust and Try Again

    If show_form: true, but an error is returned as well, then something is wrong and the consumer needs to take action before moving forward. Klarna will inform the consumer about the details of the error in the widget. Optionally, you can interpret the invalid fields in the error message and take appropriate actions on your checkout page. See the  JavaScript SDK reference page for further information.

    Code Block
    {
    show_form: true,
    error: {
      invalid_fields: [
        billing_address.street_address
        billing_address.city
        billing_address.given_name
        billing_address.postal_code
        billing_address.family_name
        billing_address.email	]
      }
    }

    Negative Response

    If show_form: false, the payment method chosen by the customer will not be offered for this order based on Klarna’s evaluation. A message is displayed to the consumer in the Widget.

    When Klarna returns a show_form: false, your store cannot offer the selected payment method to this customer. You need to present other payment methods to the customer and hide the option of Klarna payment.

    Code Block
    {
    show_form: false
    }


    Anchor
    widget
    widget
    Klarna Authorize

    UI Step

    Authorise the Purchase

    Once the customer has successfully selected Klarna as payment method in the checkout, the purchase can be authorised by using the Klarna JavaScript SDK. In this step all necessary customer details are transmitted to Klarna for taking a decision about whether or not to offer credit for the purchase. As a result of the authorisation you will receive a token enabling you to place an order towards Klarna. A successful authoirsation guarantees that the order can be generated within 60 minutes.

    Sending the Request

    The Authorisation is initiated by a client-side call which will provide you with a token for the order once successfully completed.

    Here is an example request for an authorisation call. In the call one must provide the billing and optionally the shipping address.

    Code Block
    KKlarna.Payments.authorize({
      payment_method_category: "pay_later"
    }, {
      purchase_country: "GB",
      purchase_currency: "GBP",
      locale: "en-GB",
      billing_address: {
        given_name: "John",
        family_name: "Doe",
        email: "john@doe.com",
        title: "Mr",
        street_address: "13 New Burlington St",
        street_address2: "Apt 214",
        postal_code: "W13 3BG",
        city: "London",
        region: "",
        phone: "01895808221",
        country: "GB"
      },
      shipping_address: {
        given_name: "John",
        family_name: "Doe",
        email: "john@doe.com",
        title: "Mr",
        street_address: "13 New Burlington St",
        street_address2: "Apt 214",
        postal_code: "W13 3BG",
        city: "London",
        phone: "01895808221",
        country: "GB"
      },
      order_amount: 10,
      order_tax_amount: 0,
      order_lines: [{
        type: "physical",
        reference: "19-402",
        name: "Battery Power Pack",
        quantity: 1,
        unit_price: 10,
        tax_rate: 0,
        total_amount: 10,
        total_discount_amount: 0,
        total_tax_amount: 0,
        product_url: "https://www.estore.com/products/f2a8d7e34",
        image_url: "https://www.exampleobjects.com/logo.png"
      }],
      customer: {
        date_of_birth: "1970-01-01",
      },
    }, function(res) {
      console.debug(res);
    })

    According to Klarna documentation (Klarna Docs - Authorize the purchase):

    User interaction during the authorize call

    When authorizing the order, Klarna conducts a full risk assessment. Therefore, from the point where you call authorize until you receive the callback you must:

    1. Avoid sending another authorize call (e.g. disable the buy button from being clicked again)
    2. Show to the consumer that the order is being processed (e.g. by showing a loading spinner)
    3. Prevent consumer from changing order or billing details (e.g. lock the input fields on your page)

    The callback is typically received within seconds, but may take up to a minute or so in case a consumer sign-up is required when the user interacts with the widget.


    UI Step

    Process callback from authorise call

    Once the wigdet has processes the autorisation a callback is performed providing an object with one of the following parameter:

    • approved (true/false) - the authorization result, approved or denied
    • show_form (true/false) - whether the Klarna Widget should be displayed or hidden
    • authorization_token - a token which allows you to place the order via a server side call, only returned if the authorization was approved
    • error - contains details of potential error messages

    Order approved

    If approved carries the value "true", Klarna has approved the authorisation of credit for this order. With the authorisation_token the order can be completed using a server side pace order call. The token is valid for 60 minutes during which the authorisation is guaranteed.

    Code Block
    {
    authorization_token: "b4bd3423-24e3",
    approved: true,
    show_form: true
    }

    Order not approved

    If approved: false, Klarna cannot approve the purchase. There are now two options:

    Option 1 - Fixable error

    In the case of an adjustable error, you will receive show_form: true and a specification about what fields that are invalid, e.g. error: { invalid_fields: ["billing_address.email"] } }. The widget will also display an error message to the consumer, asking them to correct it before you re-authorize the order. This error message will also clarify which specific field that is incorrect.

    Code Block
    {
    approved: false,
    show_form: true,
    error: {
      invalid_fields: [
                  billing_address.street_address
                  
    add_paydata[payment_method_category_asset_url_descriptive_2]=https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/pay_later/descriptive/pink.svg add_paydata[payment_method_category_asset_url_descriptive_1]=https://cdn.klarna.com/1.0/shared/image/generic/badge/en_us/pay_now/descriptive/pink.svg add_paydata[payment_method_category_identifier_1]=direct_debit workorderid=WX123456799
    Anchorupdate_sessionupdate_session

    Genericpayment update_session

    To update an order, you need to send a genericpayment-request with action=update. The call needs to provide the new list of items representing the complete shopping cart.

    UI Text Box
    typenote
    • An update is only possible as long as the preauthorization is not captured completly.
    • Don’t send the difference/changes, instead you need to send the complete new item list
    • The amount can’t be higher as the amount of the preauthorization. A lower amount is allowed.

    Request "genericpayment - update"

    API parameterRequiredCommentsadd_paydata[action]+Fixed value "update"add_paydata[reservation_txid]+Referencing the reservation (received from authorization.response -> add_paydata[reservation_txid])workorderid+Referencing the reservation (received from authorization.response -> add_paydata[workorderid])country+DefaultCountry (ISO 3166)amount+N..10

    Total gross amount (in smallest currency unit! e.g.
    cent, max. 19 999 999 99)

    currency+Default

    Currency (ISO 4217)

    financingtype+Fixed value "KLV/KLS"it[n]+Default

    For KLV / KLS: Item type

    goods Goods
    shipment Shipping charges
    handling Handling fee
    voucher Voucher / discount
    id[n]+AN..32Product number, order number, etc.
    Permitted symbols:
    0-9 a-z A-Z ()[]{} +-_#/:
    [n] starting with [1]; serially numbered; max [400]pr[n]+N..10Unit gross price in cent, max. 19 999 999 99
    [n] starting with [1]; serially numbered; max [400]no[n]+N..6Quantity
    [n] starting with [1]; serially numbered; max [400]de[n]+AN..50Description
    [n] starting with [1]; serially numbered; max [400]va[n]+N..4VAT rate (% or bp) of gross price
    Mandatory for payment type KLV, KLS
    [n] starting with [1]; serially numbered; max [400]

    Response "genericpayment - update"

    API parameter

    RequiredCommentsstatus+APPROVED / ERRORAPPROVEDworkorderid+ERRORerrorcode+errormessage+customermessage+ Anchorwidgetwidget

    Klarna Widget

    the follwing integration steps are taken from Klarna documentation ( https://developers.klarna.com/documentation/klarna-payments/integration-guide/present-klarna-widget )

    After creating a new session, you want to present the klarna widget to your customer. This widget allows you to present all 3 payment methods offered by Klarna to the customer or define what payment method should be presented to the customer. This is 

    UI Steps UI Step

    Add SDK to your page (insert in body)

    Code Block
    <script>
      window.klarnaAsyncCallback = function () {
    
        // This is where you start calling Klarna's JS SDK functions
        // 
        // Klarna.Payments.init({....})
    
      };
    </script>
    <script src="https://x.klarnacdn.net/kp/lib/v1/api.js" async></script>
    UI Step

    Initialize SDK and place a container on your page

    Code Block
    Klarna.Payments.init({
      client_token: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.dtxWM6MIcgoeMgH87tGvsNDY6cH'
    })
    Code Block
    <div id="klarna_container"></div>
    UI Step

    Load Klarna Widget

    Code Block
    Klarna.Payments.load({
        container: '#klarna-payments-container',
        payment_method_category: 'pay_later'
      }, function (res) {
        console.debug(res);
    })
    UI Step

    Receive Response from load call

    Klarna’s widget uses the show_form:true/false field as a response flag to load and to authorize calls in the Javascript SDK.

    Positive Response

    If show_form: true, and there are no errors in the object returned, Klarna renders the payment options available to the customer in the widget.

    Adjust and try again

    If show_form: true, but an error is returned as well, then something is wrong and the consumer needs to take action before moving forward. Klarna will inform the consumer about the details of the error in the widget. Optionally, you can interpret the invalid fields in the error message and take appropriate actions on your checkout page. See the  JavaScript SDK reference page for further information.

    Negative Response

    If show_form: false, the payment method chosen by the customer will not be offered for this order based on Klarna’s evaluation. A message is displayed to the consumer in the Widget.

    When Klarna returns a show_form: false, your store cannot offer the selected payment method to this customer. You need to present other payment methods to the customer.

    Anchorauthorizationauthorization

    Preauthorization/Authorization

    Request "preauthorization / authorization"

    API parameter

    RequiredCommentsfirstname+AN1..50First namelastname+AN2..50Surnamecompany-AN..50If filled, the transaction is marked as B2B.street+AN1..50Street number and namezip+AN2..10Postcode, format [a-zA-Z0-9_.-/]{2,10}city+AN2..50Citycountry+DefaultCountry (ISO 3166)addressaddition+AN1..50

    Address line 2 (e.g. "7th floor", "c/o Maier")

    genderoDefaultf=female, m=maleip+AN..39Customer's IP-V4-address (123.123.123.123) or IP
    V6-addressemail+AN..254Email addresstelephonenumber+AN..30Telephone numberbirthdayoN8

    Date of birth (YYYYMMDD)

    Mandatory for Germany, Netherlands and Austria

    shipping_firstname-AN..50First nameshipping_lastname-AN..50Surnameshipping_company-AN2..50Companyshipping_street-AN1..50Street number and name (required: at least one character)shipping_zip-AN2..10

    Postcode, format [a-zA-Z0-9_.-/]{2,10}

    shipping_city-AN2..50Cityshipping_country-DefaultCountry (ISO 3166)personalidoAN..32Mandatory for Sweden, Finland, Denmark and Norwayit[n]+Default

    For KLV / KLS: Item type

    goods Goods
    shipment Shipping charges
    handling Handling fee
    voucher Voucher / discount
    id[n]+AN..32Product number, order number, etc.
    Permitted symbols:
    0-9 a-z A-Z ()[]{} +-_#/:
    [n] starting with [1]; serially numbered; max [400]pr[n]+N..10Unit gross price in cent, max. 19 999 999 99
    [n] starting with [1]; serially numbered; max [400]no[n]+N..6Quantity
    [n] starting with [1]; serially numbered; max [400]de[n]+AN..255Description
    [n] starting with [1]; serially numbered; max [400]va[n]+N..4VAT rate (% or bp) of gross price
    Mandatory for payment type KLV, KLS
    [n] starting with [1]; serially numbered; max [400]add_paydata[klsid]o

    Mandatory for Klarna Installment (KLS): Campaign code

    Code Block
    add_paydata[authorization_token]=aaa-bbbb-11111-2222-ccc
    aid=12346
    amount=8540
    api_version=3.10
    backurl=https://meine.test.url.de/Checkout/back
    birthday=19600707
    city=Neuss
    clearingtype=fnc
    country=DE
    currency=EUR
    de[1]=for ocean use only
    email=klarna@approved.de
    encoding=UTF-8
    errorurl=https://meine.test.url.de/Checkout/error
    financingtype=KLS
    firstname=Testperson-de
    gender=m
    id[1]=boat66
    it[1]=goods
    key=e123dc456a
    language=de
    lastname=Approved
    mid=12345
    mode=test
    narrative_text=0123456789012345678901234567890123456789
    no[1]=1
    portalid=2000123
    pr[1]=8540
    reference=R15595689952007
    request=authorization
    salutation=Herr
    street=Hellersbergstraße 14
    successurl=https://meine.test.url.de/Checkout/success
    telephonenumber=01522113356
    va[1]=1900
    zip=41460

    Response "preauthorization / authorization"

    API parameter

    RequiredCommentsadd_paydata[workorderid]+

    Klarna Invoice: Workorder ID, used for update calls (cart updates)

    add_paydata[reservation_txid]+

    Klarna Invoice: Reservation ID, used for update calls (cart updates)

    Code Block
    redirecturl=https://klarna-payments-eu.playground.klarna.com/v1/sessions/aaa-bbbb-11111-2222-ccc/redirect
    status=REDIRECT
    txid=30343747
    userid=7890123

    Capture

    Request "capture"

    API parameter

    RequiredCommentscapturemode+Parameter capturemode is mandatory to indicate whether this capture will be the last one. (Default: completed)settleaccount+Parameter settleaccount is mandatory to indicate whether a refund to the customer should be initiated. (Default: yes)

    Response "capture"

    API parameter

    RequiredCommentsclearing_instructionnoteo
    • A URL pointing to a PDF of the invoice. (If invoice by post or by e-mail isn’t activated.)
    • The URL is valid for 30 days.
    • This feature has to be requested.

    Debit / Refund

    Request "debit"

    API parameter

    RequiredCommentssettleaccount+Parameter settleaccount is mandatory to indicate whether a refund to the customer should be initiated. (Default: yes
    billing_address.city
                  billing_address.given_name
                  billing_address.postal_code
                  billing_address.family_name
                  billing_address.email ]
      }
    }

    Option 2 - Order declined

    If show_form: false, the order is declined and the Klanra widget should be hidden requesting the customer to select a different method of payment.

    Code Block
    {
    approved: false,
    show_form: false
    }



    UI Step

    Finalize the authorisaton

    According to Klarna documentation (Klarna Docs - Authorize the purchase) the following steps on client side are optional.

    Finalising an authorisation only applies to your integration if you offer payment methods where funds are drawn from the consumers directly, such as bank transfer or Sofort, in a multi-step checkout. If you integrate a multi-step checkout, you may call authorize() with the auto_finalize: false property set in order to indicate that there is a finalization step. In this case the response may differ.

    In a multi-step checkout scenario the authorize() call can be triggered when the consumer selects the payment method and then presses the “continue” button to go to the next step of the checkout. With Pay Now as payment method category however transferring the funds should only happen once the consumer has pressed the “buy” button to finalize the purchase.

    To cater for such a scenario authorize() can still be called when the consumer has selected the payment method, but with the auto_finalize property set to false. authorize() example:

    Code Block
    Klarna.Payments.authorize(
    { payment_method_category: ‘pay_now’, auto_finalize: false},
    {},
    function(res) {
    // proceed to next checkout page. The finalize_required property in the response indicates
    // if finalize is needed or not.
    //
    // res = {
    //   show_form: true,
    //   approved: false,
    //   finalize_required: true
    // }
    })

    Now when the consumer reached the last page in the checkout and can finalize the purchase finalize() is called. This will then trigger the transfer of funds and return the authorization token in the finalize callback. The flow is transparent to all payment method categories. That means if finalization was not needed in the authorize() call (e.g. for pay later) finalize()can be still be called and will return the authorization_token so that the implementation remains the same for all payment method categories. finalize() example:

    Code Block
    Klarna.Payments.finalize(
    {payment_method_category: ‘pay_now’},
    {},
    function(res) {
    // res = {
    //   show_form: true,
    //   approved: true,
    //   authorization_token: ...
    // }
    })



    Overview Server-Side API Calls

    Anchor
    start_session
    start_session
    Genericpayment start_session

    The first step is to setup a new checkout session by sending a genericpayment-request to our server API as listed below. This step is a pre-condition for loading the Klarna widget.

    Please make sure to send the customer data within this request as it is needed to initiate a new session. A session will remain valid for 48 hours after the last update.

    UI Text Box
    typenote

    Only submit a buyer's personal information within this request if you ensure the buyer has actively chosen Klarna as a payment method - due to GDPR.


    UI Expand
    titleRequest "Genericpayment - start_session"


    Request "Generic Start Session"

    API parameter

    RequiredComments
    request+


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Fixed Value


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    genericpayment



    add_paydata[action]+

    identifies the request as one to start a new session

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Fixed Value


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    start_session



    add_paydata[merchant_data]-

    "EMD" - Extra Merchant Data - means that integration with any such package depends on

    (i) merchant’s offering and

    (ii) merchant’s technical possibilities.

    It is not to be interpreted in such a way that EMD is not required at all.

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Format


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    BASE 64 String



    amount+

    Excerpt Include
    amount - definition
    amount - definition
    nopaneltrue

    currency+

    Excerpt Include
    currency - definition
    currency - definition
    nopaneltrue

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    allowed Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    EUR
    CHF
    DKK
    SEK
    NOK



    country+

    Excerpt Include
    country - definition
    country - definition
    nopaneltrue

    firstname-

    Excerpt Include
    firstname - definition
    firstname - definition
    nopaneltrue

    lastname-

    Excerpt Include
    lastname - definition
    lastname - definition
    nopaneltrue

    company-

    Excerpt Include
    company - definition
    company - definition
    nopaneltrue

    UI Text Box
    typenote

    Submitting this parameter leads to a B2B transaction.

    Availability of B2B transactions is limited to some countries.


    title-

    Excerpt Include
    title - definition
    title - definition
    nopaneltrue

    street-

    Excerpt Include
    street - definition
    street - definition
    nopaneltrue

    zip-

    Excerpt Include
    zip - definition
    zip - definition
    nopaneltrue

    city-

    Excerpt Include
    city - definition
    city - definition
    nopaneltrue

    state-

    Excerpt Include
    state - definition
    state - definition
    nopaneltrue

    addressaddition-

    Excerpt Include
    addressaddition - definition
    addressaddition - definition
    nopaneltrue

    gender-

    Excerpt Include
    gender - definition
    gender - definition
    nopaneltrue

    ip-

    Excerpt Include
    ip - definition
    ip - definition
    nopaneltrue

    email-

    Excerpt Include
    email - definition
    email - definition
    nopaneltrue

    telephonenumber-

    Excerpt Include
    telephonenumber - definition
    telephonenumber - definition
    nopaneltrue

    birthday-

    Excerpt Include
    birthday - definition
    birthday - definition
    nopaneltrue

    mandatory for Austria, Germany, Switzerland and the Netherlands.

    language-

    Excerpt Include
    language - definition
    language - definition
    nopaneltrue

    shipping_firstname

    -

    Excerpt Include
    shipping_firstname - definition
    shipping_firstname - definition
    nopaneltrue

    shipping_lastname-

    Excerpt Include
    shipping_lastname - definition
    shipping_lastname - definition
    nopaneltrue

    add_paydata[shipping_title]-

    Title recipient within the delivery address

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Format


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    CHAR(1..50)



    shipping_company-

    Excerpt Include
    shipping_company - definition
    shipping_company - definition
    nopaneltrue

    shipping_street

    -

    Excerpt Include
    shipping_street - definition
    shipping_street - definition
    nopaneltrue

    shipping_zip-

    Excerpt Include
    shipping_zip - definition
    shipping_zip - definition
    nopaneltrue

    shipping_city-

    Excerpt Include
    shipping_city - definition
    shipping_city - definition
    nopaneltrue

    shipping_country-

    Excerpt Include
    shipping_country - definition
    shipping_country - definition
    nopaneltrue

    shipping_state-

    Excerpt Include
    shipping_state - definition
    shipping_state - definition
    nopaneltrue

    +

    Excerpt Include
    successurl - definition
    successurl - definition

    errorurl+

    Excerpt Include
    errorurl - definition
    errorurl - definition

    backurl+

    Excerpt Include
    backurl - definition
    backurl - definition

    add_paydata[shipping_telephonenumber]


    -

    telephone number of the recipient or a contact at the delivery address

    Section


    Layout box
    cssClasspayoneFormat
    floatingleft

    Format


    Layout box
    cssClasspayoneFormatValue
    floatingleft
    CHAR(1..30)



    add_paydata[shipping_email]-

    email-address of the recipient or a contact at the delivery address

    Section


    Layout box
    cssClasspayoneFormat
    floatingleft

    Format


    Layout box
    cssClasspayoneFormatValue
    floatingleft
    CHAR(5..254)



    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Symbols


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    RFC 5322


    This parameter is required if a shipping adress is given.

    add_paydata[last_four_ssn]-

    Last four digits for customer social security number.

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Format


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    NUMERIC(4)



    add_paydata[organization_entity_type]-

    Only relevant for B2B transactions.

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    LIMITED_COMPANY
    PUBLIC_LIMITED_COMPANY
    ENTREPRENEURIAL_COMPANY
    LIMITED_PARTNERSHIP_LIMITED_COMPANY
    LIMITED_PARTNERSHIP
    GENERAL_PARTNERSHIP
    REGISTERED_SOLE_TRADER
    SOLE_TRADER
    CIVIL_LAW_PARTNERSHIP
    PUBLIC_INSTITUTION
    OTHER



    add_paydata[organization_registry_id]-

    will be given to Klarna as "vat_id"

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Format


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    CHAR(1..50)



    personalid-

    Excerpt Include
    personalid - definition
    personalid - definition
    nopaneltrue

    Mandatory for Denmark, Finland, Norway and Sweden

    it[n]+

    Klarna item type

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    goods      : Goods
    shipment   : Shipping charges
    handling   : Handling fee
    voucher    : Voucher / discount 



    id[n]+

    Excerpt Include
    id[n] - definition
    id[n] - definition
    nopaneltrue

    pr[n]+

    Excerpt Include
    pr[n] - definition
    pr[n] - definition
    nopaneltrue

    no[n]+

    Excerpt Include
    no[n] - definition
    no[n] - definition
    nopaneltrue

    de[n]+

    Excerpt Include
    de[n] - definition
    de[n] - definition
    nopaneltrue

    va[n]

    +


    Excerpt Include
    va[n] - definition
    va[n] - definition
    nopaneltrue



    Code Block
    titleGenericpayment start_session - Example Request
    collapsetrue
    mid=23456 (your mid)
    portalid=12345123 (your portalid)
    key=abcdefghijklmn123456789 (your key)
    api_version=3.10
    mode=test (set to „live“ for live-requests)
    request=genericpayment
    encoding=UTF-8
    aid=12345 (your aid)
    clearingtype=fnc
    financingtype=KIS
    amount=3000
    currency=EUR
    lastname=Approved
    firstname=Testperson-de
    salutation=Herr
    country=DE
    language=de
    gender=m
    add_paydata[action]=start_session
    birthday=19600707
    street=Hellersbergstraße 14
    city=Musterstadt
    zip=12345
    email=youremail@email.com
    telephonenumber=01512345678
    de[1]=for the feet
    id[1]=socks1
    it[1]=goods
    no[1]=1
    pr[1]=2340
    va[1]=1900


    UI Expand
    expandedtrue
    titleResponse "Genericpayment - start_session"


    Response "Genericpayment - start_session"

    API parameter

    RequiredComments

    add_paydata[session_id]

    +

    Identifier for the started session at Klarna


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Sample


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    068df369-13a7-4d47-a564-62f8408bb760



    add_paydata[client_token]+

    Client token to authorize the session for payment via Klarna Widget

    add_paydata[authorized_payment_method]+Name of payment that got authorized for customer payment. (You will only receive the parameters according to the payment method you selected via clearingtype and financingtype)
    add_paydata[payment_method_category_name]+

    Name of Klarna payment category

    Payment Method Category to show on the Payment Page.


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    DIRECT_DEBIT

    DIRECT_BANK_TRANSFER

    PAY_NOW

    PAY_LATER

    PAY_OVER_TIME



    add_paydata[payment_method_category_identifier]+

    Identifier for Klarna payment category

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    Pay_later

    Pay_now

    Pay_over_time

    Direct_bank_transfer

    Direct_debit



    add_paydata[payment_method_category_asset_url_descriptive]+

    URL of Klarna payment category assets for descriptive design (payment method identified by small icon and test on badge)

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Sample


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg



    add_paydata[payment_method_category_asset_url_standard]+

    URL of Klarna payment category assets for standard design (payment method only identified by small icon on badge)

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Sample


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg


    status+


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    APPROVED
    ERROR



    APPROVED

    workorderid+

    Excerpt Include
    workorderid - definition
    workorderid - definition
    nopaneltrue

    ERROR

    errorcode+

    Excerpt Include
    errorcode - definition
    errorcode - definition
    nopaneltrue

    errormessage+

    Excerpt Include
    errormessage - definition
    errormessage - definition
    nopaneltrue

    customermessage+

    Excerpt Include
    customermessage - definition
    customermessage - definition
    nopaneltrue



    Code Block
    titleGenericpayment start_session - Example Response
    collapsetrue
    status=OK
    add_paydata[payment_method_category_asset_url_descriptive]=https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg
    add_paydata[client_token]=eyJhbGciOiJSUzI1NiJ9.ewogICJzZXNzaW9uX2lkIiA6ICI0N2EzNWIwOC1kNWVlLTcxYjUtOTVkMS1lYWU3NTFjNWJlZmIiLAogICJiYXNlX3VybCIgOiAiaHR0cHM6Ly9rbGFybmEtcGF5bWVudHMtZXUucGxheWdyb3VuZC5rbGFybmEuY29tIiwKICAiZGVzaWduIiA6ICJrbGFybmEiLAogICJsYW5ndWFnZSIgOiAiZW4iLAogICJwdXJjaGFzZV9jb3VudHJ5IiA6ICJERSIsCiAgInRyYWNlX2Zsb3ciIDogZmFsc2UsCiAgImVudmlyb25tZW50IiA6ICJwbGF5Z3JvdW5kIiwKICAibWVyY2hhbnRfbmFtZSIgOiAiWW91ciBidXNpbmVzcyBuYW1lIiwKICAic2Vzc2lvbl90eXBlIiA6ICJQQVlNRU5UUyIsCiAgImNsaWVudF9ldmVudF9iYXNlX3VybCIgOiAiaHR0cHM6Ly9ldnQucGxheWdyb3VuZC5rbGFybmEuY29tIiwKICAiZXhwZXJpbWVudHMiIDogWyBdCn0.gD6XVLaZeL541T1QYkGsZ01wbAYuTXyhIXcR8irG461U9w1HLugSji4_jc8LsE7cVWMVqLph_CJzCAiZNKzsC9AW6Mf88X8VdR9gV7owv3EVqEdK2K9-g-26Wu2pGE88Um2z2Iz7uUUzbhn6d4rI4CICOLsdaVXJ7MKhzPgnW-a6DM-K9JP2RLIflJKjn3wCjEtJSc_8gqj3_fv8YHaTWRkBd9pUGCBB0rUS-komFAPBdzZiCAbiw5Lsdk9dWpI2wszKeE_iPd6NuxGr4U37XtIX9Gc-uTfn21o0JUJddbiPtItmetWQSY_mruOO4WiVQxuZvxXk7XYwCCb8rrXYw
    add_paydata[payment_method_category_identifier]=pay_over_time
    add_paydata[session_id]=47a35b08-d5ee-71b5-95d1-eae751c5befb
    add_paydata[payment_method_category_name]=Slice it.
    add_paydata[payment_method_category_asset_url_standard]=https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg
    workorderid=WX1A37YBGD9D11DK

    Anchor
    update_session
    update_session
    Genericpayment update_session

    In order to update the session, e.g. the customer has added a new item tothe cart, you need to send a genericpayment-request with action=update. The call needs to provide the new list of items representing the complete shopping cart.

    UI Text Box
    typenote
    • An update is only possible as long as the preauthorization is not captured completely.
    • Do not send the difference/changes, instead you need to send the complete new item list
    • The amount cannot be higher than the amount of the preauthorization. A lower amount is allowed.


    UI Expand
    titleRequest "Genericpayment - update"


    Request "Genericpayment - update"

    API parameterRequiredComments
    request+


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Fixed Value


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    genericpayment



    add_paydata[action]+


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Fixed value


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    update_session



    add_paydata[reservation_txid]+Referencing the reservation (received from authorization.response -> add_paydata[reservation_txid])
    add_paydata[session_id]+

    Identifier for the started session at Klarna

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Sample


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    068df369-13a7-4d47-a564-62f8408bb760



    workorderid

    +

    Referencing the reservation (received from authorization.response -> add_paydata[workorderid])

    Excerpt Include
    workorderid - definition
    workorderid - definition
    nopaneltrue

    country+

    Excerpt Include
    country - definition
    country - definition
    nopaneltrue

    amount+

    Excerpt Include
    amount - definition
    amount - definition
    nopaneltrue


    currency+

    Excerpt Include
    currency - definition
    currency - definition
    nopaneltrue


    financingtype+


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    KIS
    KIV
    KDD



    it[n]+

    Klarna item type

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    goods      : Goods
    shipment   : Shipping charges
    handling   : Handling fee
    voucher    : Voucher / discount 



    id[n]+

    Excerpt Include
    id[n] - definition
    id[n] - definition
    nopaneltrue

    AN..32

    pr[n]+

    Excerpt Include
    pr[n] - definition
    pr[n] - definition
    nopaneltrue

    no[n]+

    Excerpt Include
    no[n] - definition
    no[n] - definition
    nopaneltrue

    de[n]+

    Excerpt Include
    de[n] - definition
    de[n] - definition
    nopaneltrue

    AN..50

    va[n]+

    Excerpt Include
    va[n] - definition
    va[n] - definition
    nopaneltrue


    narrative_text-

    Excerpt Include
    narrative_text - definition
    narrative_text - definition
    nopaneltrue



    UI Expand
    titleResponse "Genericpayment - update"


    Response "Genericpayment - update"

    API parameter

    RequiredComments
    status+


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    APPROVED
    ERROR



    APPROVED

    workorderid+

    Excerpt Include
    workorderid - definition
    workorderid - definition
    nopaneltrue

    ERROR

    errorcode+

    Excerpt Include
    errorcode - definition
    errorcode - definition
    nopaneltrue

    errormessage+

    Excerpt Include
    errormessage - definition
    errormessage - definition
    nopaneltrue

    customermessage+

    Excerpt Include
    customermessage - definition
    customermessage - definition
    nopaneltrue







    addresponsedata[reservation_txid]

    Excerpt Include
    add_paydata[reservation_txid] - definition
    add_paydata[reservation_txid] - definition
    nopaneltrue

    addresponsedata[workorderid]

    Excerpt Include
    workorderid - definition
    workorderid - definition
    nopaneltrue

    addresponsedata[authorized_payment_method]

    Name of payment that got authorized for customer payment. (You will only receive the parameters according to the payment method you selected via clearingtype and financingtype)


    Anchor
    cancel_authorization
    cancel_authorization
    Genericpayment cancel_authorization

    To update an order, you need to send a genericpayment-request with action=update. The call needs to provide the new list of items representing the complete shopping cart.

    UI Text Box
    typenote
    • An update is only possible as long as the preauthorization is not captured compeletly.
    • Don’t send the difference/changes, instead you need to send the complete new item list
    • The amount can’t be higher as the amount of the preauthorization. A lower amount is allowed.


    UI Expand
    titleRequest "Genericpayment - cancel_authorization"


    Request "Genericpayment - cancel_authorization"

    API parameterRequiredComments
    request+


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Fixed Value


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    genericpayment



    add_paydata[action]+cancel_authorization
    add_paydata[authorization_token]+Token of the authorization, which is to be canceled. Will be provided by Klarna's JS API



    UI Expand
    titleResponse "Genericpayment - cancel_authorization"


    Response "Genericpayment - cancel_authorization"

    API parameter

    RequiredComments
    status+


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values



    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    APPROVED
    ERROR



    APPROVED

    workorderid+

    Excerpt Include
    workorderid - definition
    workorderid - definition
    nopaneltrue

    ERROR

    errorcode+

    Excerpt Include
    errorcode - definition
    errorcode - definition
    nopaneltrue

    errormessage+

    Excerpt Include
    errormessage - definition
    errormessage - definition
    nopaneltrue

    customermessage+

    Excerpt Include
    customermessage - definition
    customermessage - definition
    nopaneltrue


    Anchor
    authorization
    authorization
    Preauthorization / Authorization

    UI Expand
    titleRequest "preauthorization / authorization"


    Request "preauthorization / authorization"

    API parameter

    RequiredComments
    add_paydata[authorization_token]+


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Sample


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    987d6543-f27b-45t5-b378-245465456780



    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Format


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    String



    firstname+

    Excerpt Include
    firstname - definition
    firstname - definition
    nopaneltrue

    full address required and must match the shipping-address

    lastname+

    Excerpt Include
    lastname - definition
    lastname - definition
    nopaneltrue

    full address required and must match the shipping-address

    company-

    If filled, the transaction is marked as B2B.

    Excerpt Include
    company - definition
    company - definition
    nopaneltrue

    street+

    Excerpt Include
    street - definition
    street - definition
    nopaneltrue

    full address required and must match the shipping-address

    zip+

    Excerpt Include
    zip - definition
    zip - definition
    nopaneltrue

    full address required and must match the shipping-address

    city+

    Excerpt Include
    city - definition
    city - definition
    nopaneltrue

    full address required and must match the shipping-address

    country+

    Excerpt Include
    country - definition
    country - definition
    nopaneltrue

    full address required and must match the shipping-address

    addressadditiono

    Excerpt Include
    addressaddition - definition
    addressaddition - definition
    nopaneltrue

    mandatory for NL

    gendero

    Excerpt Include
    gender - definition
    gender - definition
    nopaneltrue

    mandatory for Austria, Germany and the Netherlands

    "d" is currently not supported by Klarna

    ip+

    Excerpt Include
    ip - definition
    ip - definition
    nopaneltrue

    email+

    Excerpt Include
    email - definition
    email - definition
    nopaneltrue

    telephonenumber-

    Excerpt Include
    telephonenumber - definition
    telephonenumber - definition
    nopaneltrue

    birthdayo

    Excerpt Include
    birthday - definition
    birthday - definition
    nopaneltrue

    mandatory for Austria, Germany, Switzerland and the Netherlands.

    shipping_firstname-

    Excerpt Include
    shipping_firstname - definition
    shipping_firstname - definition
    nopaneltrue

    shipping_lastname-

    Excerpt Include
    shipping_lastname - definition
    shipping_lastname - definition
    nopaneltrue

    shipping_company-

    Excerpt Include
    shipping_company - definition
    shipping_company - definition
    nopaneltrue

    shipping_street-

    Excerpt Include
    shipping_street - definition
    shipping_street - definition
    nopaneltrue

    shipping_zip-

    Excerpt Include
    shipping_zip - definition
    shipping_zip - definition
    nopaneltrue

    shipping_city-

    Excerpt Include
    shipping_city - definition
    shipping_city - definition
    nopaneltrue

    shipping_country-

    Excerpt Include
    shipping_country - definition
    shipping_country - definition
    nopaneltrue

    +

    Excerpt Include
    successurl - definition
    successurl - definition

    errorurl+

    Excerpt Include
    errorurl - definition
    errorurl - definition

    backurl+

    Excerpt Include
    backurl - definition
    backurl - definition

    personalido

    Excerpt Include
    personalid - definition
    personalid - definition
    nopaneltrue

    Mandatory for Denmark, Finland, Norway and Sweden

    it[n]+

    Klarna item type

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    goods : Goods
    shipment : Shipping charges
    handling : Handling fee
    voucher : Voucher / discount 



    id[n]+

    Excerpt Include
    id[n] - definition
    id[n] - definition
    nopaneltrue

    pr[n]+

    Excerpt Include
    pr[n] - definition
    pr[n] - definition
    nopaneltrue

    no[n]+

    Excerpt Include
    no[n] - definition
    no[n] - definition
    nopaneltrue

    de[n]+

    Excerpt Include
    de[n] - definition
    de[n] - definition
    nopaneltrue

    va[n]+

    Excerpt Include
    va[n] - definition
    va[n] - definition
    nopaneltrue

    workorderid+

    Excerpt Include
    workorderid - definition
    workorderid - definition
    nopaneltrue



    Code Block
    titleAuthorization - Example Request
    collapsetrue
    add_paydata[authorization_token]=aaa-bbbb-11111-2222-ccc
    aid=12346
    amount=8540
    api_version=3.10
    backurl=https://meine.test.url.de/Checkout/back
    birthday=19600707
    city=Neuss
    clearingtype=fnc
    country=DE
    currency=EUR
    de[1]=for ocean use only
    email=klarna@approved.de
    encoding=UTF-8
    errorurl=https://meine.test.url.de/Checkout/error
    financingtype=KIS
    firstname=Testperson-de
    gender=m
    id[1]=boat66
    it[1]=goods
    key=e123dc456a
    language=de
    lastname=Approved
    mid=12345
    mode=test
    narrative_text=0123456789012345678901234567890123456789
    no[1]=1
    portalid=2000123
    pr[1]=8540
    reference=R15595689952007
    request=authorization
    salutation=Herr
    street=Hellersbergstraße 14
    successurl=https://meine.test.url.de/Checkout/success
    telephonenumber=01522113356
    va[1]=1900
    zip=41460


    UI Expand
    titleResponse "preauthorization / authorization"


    Response "preauthorization / authorization"

    Common Parameter

    RequiredFormatComment

    status

    +



    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    REDIRECT
    ERROR
    PENDING



    add_paydata[workorderid]-
    Klarna Invoice: Workorder ID, used for update calls (cart updates)
    add_paydata[reservation_txid]-
    Klarna Invoice: Reservation ID, used for update calls (cart updates)

    Parameter (APPROVED)

    txid

    +


    Excerpt Include
    txid - definition
    txid - definition
    nopaneltrue

    userid

    +


    Excerpt Include
    userid - definition
    userid - definition
    nopaneltrue

    Parameter (PENDING)

    txid

    +


    Excerpt Include
    txid - definition
    txid - definition
    nopaneltrue

    userid

    +


    Excerpt Include
    userid - definition
    userid - definition
    nopaneltrue

    Parameter (REDIRECT)

    txid

    +


    Excerpt Include
    txid - definition
    txid - definition
    nopaneltrue

    userid

    +


    Excerpt Include
    userid - definition
    userid - definition
    nopaneltrue

    redirecturl

    +


    Excerpt Include
    redirecturl - definition
    redirecturl - definition
    nopaneltrue

    Parameter (ERROR)

    errormessage

    +


    Excerpt Include
    errormessage - definition
    errormessage - definition
    nopaneltrue

    customermessage

    -


    Excerpt Include
    customermessage - definition
    customermessage - definition
    nopaneltrue



    Code Block
    titleAuthorization - Example Response
    collapsetrue
    redirecturl=https://klarna-payments-eu.playground.klarna.com/v1/sessions/aaa-bbbb-11111-2222-ccc/redirect
    status=REDIRECT
    txid=30343747
    userid=7890123


    Capture

    In the capturing step either the full amount or a partial amount can be captured. It is also possible to split the capturing in two steps, capturing an initial amount and subsequently capturing the remaining outstanding amount. Please note that the amount in the capture request must be equal or less than the remaining authorised amount.

    In the capture call one can provide the order lines thar are part of the shipment. By using the exact same order line name and reference as in the order, you will improve the customer's experience in the Klarna App.

    UI Expand
    titleRequest "capture"


    Request "capture"

    API parameter

    RequiredComments
    txid+

    Excerpt Include
    txid - definition
    txid - definition
    nopaneltrue

    sequencenumbero

    Excerpt Include
    sequencenumber - definition
    sequencenumber - definition
    nopaneltrue

    capturemode+

    Parameter capturemode is mandatory to indicate whether this capture will be the last one. (Default: completed)

    Excerpt Include
    capturemode - definition
    capturemode - definition
    nopaneltrue

    settleaccount+

    Parameter settleaccount is mandatory to indicate whether a refund to the customer should be initiated. (Default: yes)

    Excerpt Include
    settleaccount - definition
    settleaccount - definition
    nopaneltrue

    amount+

    Excerpt Include
    amount - definition
    amount - definition
    nopaneltrue

    currency+

    Excerpt Include
    settleaccount - definition
    settleaccount - definition
    nopaneltrue

    narrative_text-

    Excerpt Include
    narrative_text - definition
    narrative_text - definition
    nopaneltrue

    de[n]-

    Excerpt Include
    de[n] - definition
    de[n] - definition
    nopaneltrue

    no[n]-

    Excerpt Include
    no[n] - definition
    no[n] - definition
    nopaneltrue

    id[n]-

    Excerpt Include
    id[n] - definition
    id[n] - definition
    nopaneltrue

    it[n]-

    Excerpt Include
    it[n] - definition
    it[n] - definition
    nopaneltrue

    va[n]-

    Excerpt Include
    va[n] - definition
    va[n] - definition
    nopaneltrue

    pr[n]-

    Excerpt Include
    pr[n] - definition
    pr[n] - definition
    nopaneltrue

    add_paydata[shipping_info_shipping_company_n]-

    Name of the shipping company (as specific as possible).

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Format


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    CHAR(1..100)



    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Samples


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    DHL US

    DHL



    add_paydata[shipping_info_shipping_method_n]-

    Shipping method.

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    PickUpStore

    Home

    BoxReg

    BoxUnreg

    PickUpPoint

    Own



    add_paydata[shipping_info_tracking_number_n]-

    Tracking number for the shipment.

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Format


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    CHAR(1..100)



    add_paydata[shipping_info_tracking_uri_n]-

    URI where the customer can track their shipment.

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Format


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    CHAR(1..1024)



    add_paydata[shipping_info_return_shipping_company_n]-

    Name of the shipping company for the return shipment (as specific as possible).

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Format


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    CHAR(1..100)



    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Samples


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    DHL US

    DHL



    add_paydata[shipping_info_return_tracking_uri_n]-

    URL where the customer can track the return shipment.

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Format


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    CHAR(1..1024)



    add_paydata[shipping_delay]-

    Delay before the order will be shipped. Use for improving the customer experience regarding payments. This field is currently not returned when reading the order. 

    Please note: to be able to submit values larger than 0, this has to be enabled in your merchant account. Please contact Klarna for further information.

    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Format


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    INT(1..50)



    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft

    Permitted values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft

    min: 0





    UI Expand
    titleResponse "Capture"


    Response "Capture"

    Common Parameter

    Required

    Comment

    status

    +


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    APPROVED
    ERROR



    clearing_instructionnoteo
    • A URL pointing to a PDF of the invoice. (If invoice by mail or by e-mail isn’t activated.)
    • The URL is valid for 30 days.
    • This feature has to be requested.

    Parameter (APPROVED)

    txid

    +

    Excerpt Include
    txid - definition
    txid - definition
    nopaneltrue

    settleaccount

    +

    Excerpt Include
    settleaccount response - definition
    settleaccount response - definition
    nopaneltrue

    Parameter (ERROR)

    errorcode

    +

    Excerpt Include
    errorcode - definition
    errorcode - definition
    nopaneltrue

    errormessage

    -

    Excerpt Include
    errormessage - definition
    errormessage - definition
    nopaneltrue

    customermessage

    -

    Excerpt Include
    customermessage - definition
    customermessage - definition
    nopaneltrue



    Debit

    UI Expand
    titleRequest "Debit"


    Request "Debit"

    Common Parameter

    Required

    Short explanation

    txid

    +

    Excerpt Include
    txid - definition
    txid - definition
    nopaneltrue

    sequencenumber

    +

    Excerpt Include
    sequencenumber - definition
    sequencenumber - definition
    nopaneltrue

    amount

    +

    To transfer an amount from the merchant to the customer, the amount has to be negative.

    Excerpt Include
    amount debit - definition
    amount debit - definition
    nopaneltrue

    currency

    +

    Excerpt Include
    currency - definition
    currency - definition
    nopaneltrue

    narrative_text

    -

    Excerpt Include
    narrative_text - definition
    narrative_text - definition
    nopaneltrue

    use_customerdata

    -

    Excerpt Include
    use_customerdata - definition
    use_customerdata - definition
    nopaneltrue

    transaction_param

    -

    Excerpt Include
    transaction_param - definition
    transaction_param - definition
    nopaneltrue


    settleaccount

    +

    Parameter settleaccount is mandatory to indicate whether a refund to the customer should be initiated. (Default: yes)

    Excerpt Include
    settleaccount - definition
    settleaccount - definition
    nopaneltrue

    invoiceid

    -

    Excerpt Include
    invoiceid - definition
    invoiceid - definition
    nopaneltrue

    invoice_deliverymode

    -

    Excerpt Include
    invoice_deliverymode - definition
    invoice_deliverymode - definition
    nopaneltrue

    invoiceappendix

    -

    Excerpt Include
    invoiceappendix - definition
    invoiceappendix - definition
    nopaneltrue

    invoice_deliverydate

    -

    Excerpt Include
    invoice_deliverydate - definition
    invoice_deliverydate - definition
    nopaneltrue

    invoice_deliveryenddate

    -

    Excerpt Include
    invoice_deliveryenddate - definition
    invoice_deliveryenddate - definition
    nopaneltrue

    it[n]

    -

    Excerpt Include
    it[n] - definition
    it[n] - definition
    nopaneltrue

    id[n]

    -

    Excerpt Include
    id[n] - definition
    id[n] - definition
    nopaneltrue

    pr[n]

    -

    Excerpt Include
    pr[n] - definition
    pr[n] - definition
    nopaneltrue

    no[n]

    -

    Excerpt Include
    no[n] - definition
    no[n] - definition
    nopaneltrue

    de[n]

    -

    Excerpt Include
    de[n] - definition
    de[n] - definition
    nopaneltrue

    va[n]

    -

    Excerpt Include
    va[n] - definition
    va[n] - definition
    nopaneltrue

    sd[n]

    -

    Excerpt Include
    sd[n] - definition
    sd[n] - definition
    nopaneltrue

    ed[n]

    -

    Excerpt Include
    ed[n] - definition
    ed[n] - definition
    nopaneltrue



    UI Expand
    titleResponse "Debit"


    Response "Debit"

    Common Parameter

    Required

    Comment

    status

    +


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    APPROVED
    ERROR



    Parameter (APPROVED)

    txid

    +

    Excerpt Include
    txid - definition
    txid - definition
    nopaneltrue

    settleaccount

    +

    Excerpt Include
    settleaccount response - definition
    settleaccount response - definition
    nopaneltrue

    Parameter (ERROR)

    errorcode

    +

    Excerpt Include
    errorcode - definition
    errorcode - definition
    nopaneltrue

    errormessage

    -

    Excerpt Include
    errormessage - definition
    errormessage - definition
    nopaneltrue

    customermessage

    -

    Excerpt Include
    customermessage - definition
    customermessage - definition
    nopaneltrue




    Refund

    For refunding / crediting the amount to the customer a Refund request can be triggered.

    The refunded amount must not be higher than the captured amount. The refunded amount can be accompanied by a descriptive text and order lines. By using the exact same order line name and reference as in the capture, one will improve the customer's experience in the Klarna App as well the payment instructions sent to the customer.

    UI Expand
    titleRequest "Refund"


    Request "Refund"

    API parameter

    RequiredComments

    txid

    +

    Excerpt Include
    txid - definition
    txid - definition
    nopaneltrue

    sequencenumber+

    Excerpt Include
    sequencenumber - definition
    sequencenumber - definition
    nopaneltrue

    amount+

    Excerpt Include
    amount refund - definition
    amount refund - definition
    nopaneltrue

    currency+

    Excerpt Include
    currency - definition
    currency - definition
    nopaneltrue

    narrative_text-

    Excerpt Include
    narrative_text - definition
    narrative_text - definition
    nopaneltrue

    use_customerdata-

    Excerpt Include
    use_customerdata - definition
    use_customerdata - definition
    nopaneltrue

    transaction_param-

    Excerpt Include
    transaction_param - definition
    transaction_param - definition
    nopaneltrue

    invoiceid-

    Excerpt Include
    invoiceid - definition
    invoiceid - definition
    nopaneltrue

    invoice_deliverymode

    -

    Excerpt Include
    invoice_deliverymode - definition
    invoice_deliverymode - definition
    nopaneltrue

    invoiceappendix-

    Excerpt Include
    invoiceappendix - definition
    invoiceappendix - definition
    nopaneltrue

    invoice_deliverydate-

    Excerpt Include
    invoice_deliverydate - definition
    invoice_deliverydate - definition
    nopaneltrue

    invoice_deliveryenddate-

    Excerpt Include
    invoice_deliveryenddate - definition
    invoice_deliveryenddate - definition
    nopaneltrue

    de[n]-

    Excerpt Include
    de[n] - definition
    de[n] - definition
    nopaneltrue

    no[n]-

    Excerpt Include
    no[n] - definition
    no[n] - definition
    nopaneltrue

    id[n]-

    Excerpt Include
    id[n] - definition
    id[n] - definition
    nopaneltrue

    pr[n]-

    Excerpt Include
    pr[n] - definition
    pr[n] - definition
    nopaneltrue

    it[n]-

    Excerpt Include
    it[n] - definition
    it[n] - definition
    nopaneltrue

    va[n]-

    Excerpt Include
    va[n] - definition
    va[n] - definition
    nopaneltrue



    UI Expand
    titleResponse "Refund"


    Response "Refund"

    Common Parameter

    Required

    Comment

    status

    +


    Section


    Layout box
    cssClasspayonePermittedSymbols
    floatingleft
    Permitted Values


    Layout box
    cssClasspayonePermittedSymbolsValue
    floatingleft
    APPROVED
    ERROR



    Parameter (APPROVED)

    txid

    +

    Excerpt Include
    txid - definition
    txid - definition
    nopaneltrue

    settleaccount

    +

    Excerpt Include
    settleaccount response - definition
    settleaccount response - definition
    nopaneltrue

    Parameter (ERROR)

    errorcode

    +

    Excerpt Include
    errorcode - definition
    errorcode - definition
    nopaneltrue

    errormessage

    -

    Excerpt Include
    errormessage - definition
    errormessage - definition
    nopaneltrue

    customermessage

    -

    Excerpt Include
    customermessage - definition
    customermessage - definition
    nopaneltrue



    Voucher Handling

    If you're using vouchers in your checkout, and want to partial refund items, you do have 2 options to do this:

    • send a debit-request with the items using the original amount without any discounts and send a additional item as voucher, with an amount that sums up all discounts
      • example cart with auth
        • item 1; red car;  20 €
        • item 2; green truck; 30 €
        • item 3; voucher -10€ (-5€ discount on both items)
      • example cart with debit/refund
        • item 1; red car;  20 €
        • item 2; voucher -5€  (15€ for one item will be returned)
    • send a debit-request with the items using an reduced amount, so that the whole discount is broken down on every item.
      • example cart with auth
        • item 1; red car;  20 €
        • item 2; green truck; 30 €
        • item 3; voucher -10€ (-5€ discount on both items)
      • example cart with debit/refund
        • item 1; red car;  15 €  (15€ for one item will be returned)



    Table of Contents
    outlinetrue
    indent2em