Page tree

Versions Compared

Key

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

Notes on This Type of Payment

Payment Type

Countries

Currency

Invoice ("Pay later")

  • Austria
  • Danmark
  • Finland
  • Germany
  • The Netherlands
  • Norway
  • Sweden
  • Switzerland


  • Euro
  • Danish crowns
  • Norwegian crowns
  • Swedish crowns

  • Swiss Francs


Installments ("Slice it")

Direct Debit ("Pay now")


UI Text Box
typenote

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" 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
fncKISKlarna "Slice It" (Installments)
fnc
KIVKlarna "Pay Later" (Invoice)
fncKDDKlarna "Pay Now" (Direct Debit)

Summary

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.

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. Klarna will automatically redirect the customer back again. The customer doesn't need to take any action and will not notice this step in the background.




Drawio
bordertrue
viewerToolbartrue
fitWindowfalse
diagramNameklarna_checkout
simpleViewerfalse
width
diagramWidth1401
revision3

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 genericpayment-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

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 "start_session" call by choosing Klarna as a payment method intentionally. As personal data will be sent to Klarna within said, he 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:



Anchor
widget
widget
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. 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.



Anchor
start_session
start_session
Genericpayment start_session


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.


Request "Generic Start Session"

API parameter

RequiredComments
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

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

add_paydata[klsid]+

Mandatory for Klarna Instalments (KIS): Campaign code

          


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


currently only pay_later and pay_over_time are supported

add_paydata[payment_method_category_identifier]+

Identifier for Klarna payment category

Section


Layout box
cssClasspayonePermittedSymbols
floatingleft
Permitted Values


Layout box
cssClasspayonePermittedSymbolsValue
floatingleft

pay_later

direct_debit

pay_over_time


direct_debit is currently not supported

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 Request
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


Code Block
titleGenericpayment start_session - Example Response
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

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 completely.
  • 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 parameterRequiredComments
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


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.


Request "Genericpayment - cancel_authorization"

API parameterRequiredComments
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


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

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

addressaddition+

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

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

add_paydata[klsid]o

Mandatory for Klarna Installments (KIS): Campaign code


Code Block
titleAuthorization - Example Request
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


Response "preauthorization / authorization"

API parameter

RequiredComments
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)


Code Block
titleAuthorization - Example Response
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

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




Response "Capture"

API parameter

RequiredComments
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.

Debit / Refund

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


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


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


Response "Refund"

Common Parameter

Required

Comments

status

+


Section


Layout box
cssClasspayonePermittedSymbols
floatingleft
Permitted Values


Layout box
cssClasspayonePermittedSymbolsValue
floatingleft
APPROVED
PENDING
ERROR



Parameter (APPROVED)

txid

+

Excerpt Include
txid - definition
txid - definition
nopaneltrue

Parameter (PENDING)

txid

+

Excerpt Include
txid - definition
txid - definition
nopaneltrue

Parameter (ERROR)

errorcode

+

Excerpt Include
errorcode - definition
errorcode - definition
nopaneltrue

errormessage

+

Excerpt Include
errormessage - definition
errormessage - 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