Versions Compared

Key

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




Notes to type of payment

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 Netherlands
  • Norway
  • Austria
  • Sweden
  • Euro
  • Danish crowns
  • Norwegian crowns
  • Swedish crowns
yesno

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"
    • for TransactionStatus "pending"
    • API version (question)
    • Notify-Version (question)
  • 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

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.


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=e10adc3949ba59abbe56e057f20f883e
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



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




Anchor
start_session
start_session

Genericpayment start_session

Request "generic start session"

API parameter

RequiredFormatComments
add_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 name
lastname+AN2..50Surname
street+AN1..50

Street number and name

(required: at least one character)

zip+AN2..10

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

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

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

genderoDefaultf=female, m=male
ip+AN..39

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

email+AN..254Email address
telephonenumber+AN..30Telephone number
birthdayoN8Date of birth (YYYYMMDD)

shipping_firstname

-AN..50First name
shipping_lastname-AN..50Surname
shipping_company-AN2..50Company
shipping_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..50City
shipping_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): Campaigsn code


Response "genericpayment - update"

API parameter

RequiredComments

add_paydata[session_id]

+Identifier for the started session at Klarna
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.
add_paydata[payment_method_category_name_n]+"n" starts at 1 and is then incremented if necessary.
add_paydata[payment_method_category_identifier_n]+"n" starts at 1 and is then incremented if necessary.
add_paydata[payment_method_category_asset_url_descriptive_n]+"n" starts at 1 and is then incremented if necessary.
add_paydata[payment_method_category_asset_url_standard_n]+"n" starts at 1 and is then incremented if necessary.
status+

APPROVED


workorderid+

ERROR


errorcode+

errormessage+

customermessage+

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 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 parameterRequired
Comments
add_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

RequiredComments
status+APPROVED / ERROR
APPROVED

workorderid+
ERROR

errorcode+
errormessage+
customermessage+

Anchor
widget
widget

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.



Anchor
authorization
authorization

Preauthorization/Authorization

Request "preauthorization / authorization"

API parameter

Required
Comments
firstname+AN1..50First name
lastname+AN2..50Surname
company-AN..50If filled, the transaction is marked as B2B.
street+AN1..50Street number and name
zip+AN2..10Postcode, format [a-zA-Z0-9_.-/]{2,10}
city+AN2..50City
country+DefaultCountry (ISO 3166)
addressaddition+AN1..50

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

genderoDefaultf=female, m=male
ip+AN..39Customer's IP-V4-address (123.123.123.123) or IP
V6-address
email+AN..254Email address
telephonenumber+AN..30Telephone number
birthdayoN8

Date of birth (YYYYMMDD)

Mandatory for Germany, Netherlands and Austria

shipping_firstname-AN..50First name
shipping_lastname-AN..50Surname
shipping_company-AN2..50Company
shipping_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..50City
shipping_country-DefaultCountry (ISO 3166)
personalidoAN..32Mandatory for Sweden, Finland, Denmark and Norway
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..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


Response "preauthorization / authorization"

API parameter

RequiredComments
add_paydata[workorderid]+

Klarna Invoice: Workorder ID, used for update calls (warning) Achtung: Hier ist das Warenkorb-Update gemeint. Das muss ebenfalls dokumentiert werden und hat nichts mit dem session update zu tun, das oben beschrieben ist (cart updates)

add_paydata[reservation_txid]+

Klarna Invoice: Reservation ID, used for update calls (warning) Achtung: Hier ist das Warenkorb-Update gemeint. Das muss ebenfalls dokumentiert werden und hat nichts mit dem session update zu tun, das oben beschrieben ist(cart updates)

Capture

Request "capture"

API parameter

RequiredComments
capturemode+Parameter capturemode is mandatory to indicate whether this capture will be the last one. (question) wenn ich das nicht mitgebe, bekomme ich keinen Fehler. Anscheinend wird also ein Wert als default genommen? Welcher?(Default: completed)
settleaccount+Parameter settleaccount is mandatory to indicate whether a refund to the customer should be initiated. (question) wenn ich das nicht mitgebe, bekomme ich keinen Fehler. Anscheinend wird also ein Wert als default genommen? Welcher?the customer should be initiated. (Default: yes)


Response "capture"

API parameter

RequiredComments
clearing_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. (question) by whom, where, what?

Debit / Refund

Request "debit"

API parameter

RequiredComments
settleaccount+Parameter settleaccount is mandatory to indicate whether a refund to the customer should be initiated. (question) wenn ich das nicht mitgebe, bekomme ich keinen Fehler. Anscheinend wird also ein Wert als default genommen? Welcher?(Default: yes)


Table of Contents