Page tree
Skip to end of metadata
Go to start of metadata

Notes on This Type of Payment

Payment Type

Countries

Currency

Invoice
("Pay later")

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


  • Euro
  • Danish crowns
  • Norwegian crowns
  • Swedish crowns

  • Swiss Francs


Installments
("Slice it")

Direct Debit
("Pay now")

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

API-Requests - Special Notes / Deviations

Overview of Deviations

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

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.

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.

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.

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.


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:



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 

Add SDK to your page (insert in body)


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

Initialize SDK and place a container on your page


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

Load Klarna Widget

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

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.

Genericpayment start_session

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 "Genericpayment - start_session"


Request "Generic Start Session"

API parameter

RequiredComments
add_paydata[action]+

identifies the request as one to start a new session

Fixed Value

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.

Format

BASE 64 String


amount+

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona.

The amount must be less than or equal to the amount of the corresponding booking.

Format

NUMERIC(1..10)

Permitted values

max. +/- 19 999 999 99

currency+

Specifies currency for this transaction


Format

LIST 

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR
USD
GBP

allowed Values

EUR
CHF
DKK
SEK
NOK
country+

Specifies country of address for the customer

Format

LIST 

Permitted values

ISO 3166 2-letter-codes

Samples

DE
GB
US

Some countries require additional information in parameter "state"

firstname-

First name of customer; optional if company is used, i.e.: you may use

  • "company"
  • or "lastname"
  • or "firstname" plus "lastname"

Format

CHAR(1..50)

lastname-

Last name of customer; optional if company is used, i.e.: you may use

  • "company"
  • or "lastname"
  • or "firstname" plus "lastname"

Format

CHAR(2..50)

company-

Company name of customer; The company name is optional if lastname is used, i.e.: you may use

  • "company"
  • or "lastname"
  • or "firstname" plus "lastname"

Format

CHAR(2..50)

Submitting this parameter leads to a B2B transaction.

Availability of B2B transactions is limited to some countries.

title-

Title of the customer

Format

CHAR(1..20)

Samples

Dr
Prof.
Dr.-Ing.

street-

Street number and name

Format

CHAR(1..50)

zip-

Postcode

Format

CHAR(2..10)
Permitted Symbols
[0-9][A-Z][a-z][_.-/ ]

city-

City of customer

Format

CHAR(2..50)

state-

Specifies state / region of country for the customer.
"state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN and must not be used for all other countries.

Format

LIST

Permitted values


Samples US

AK
AL
AR

Samples CA

AB
BC

addressaddition-

Specifies an additional address line for the invoice address of the customer.

Format

CHAR(1..50)

Samples

7th floor
c/o Maier

gender-

Gender of customer (female / male / diverse* )

Format

LIST 

Permitted values

f    
m
d

* not in use by now

ip-

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

Format

CHAR(1..39)

email-

email-address of customer

Format

CHAR(5..254)
Permitted Symbols
RFC 5322

telephonenumber-

Phone number of customer

Format

CHAR(1..30)

birthday-

Date of birth of customer


Format

DATE(8), YYYYMMDD

Samples

20190101
19991231

mandatory for Austria, Germany, Switzerland and the Netherlands.

language-

Language indicator (ISO 639) to specify the language that should be presented to the customer (e.g. for error messages, frontend display).

If the language is not transferred, the browser language will be used. For a non-supported language English will be used.

Format

LIST 

Permitted values

ISO 639-1 (Language) 2-letter-codes

shipping_firstname

-

First name of delivery address

Format

CHAR(1..50)

shipping_lastname-

Surname of delivery address

Format

CHAR(1..50)

add_paydata[shipping_title]-

Title recipient within the delivery address

Format

CHAR(1..50)
shipping_company-

Company Name of the delivery address

Format

CHAR(2..50)

shipping_street

-

Street number and name of delivery address

Format

CHAR(2..50)

shipping_zip-

Postcode of delivery address

Format

CHAR(2..10)
Permitted Symbols
[0-9][A-Z][a-z][_.-/ ]

shipping_city-

City of delivery address

Format

CHAR(2..50)

shipping_country-

Specifies country of delivery address for the customer

Format

LIST 

Permitted values

ISO 3166 2-letter-codes

Samples

DE
GB
US

Some countries require additional information in parameter shipping_state

shipping_state-

Specifies state of country of delivery address for the customer
"shipping_state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN (if shipping_country is given) and must not be used in all other countries.

Format

LIST

Permitted values


Samples US

AK
AL
AR

Samples CA

AB
BC

add_paydata[shipping_telephonenumber]


-

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

Format

CHAR(1..30)
add_paydata[shipping_email]-

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

Format

CHAR(5..254)
Permitted Symbols
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.

Format

NUMERIC(4)
add_paydata[organization_entity_type]-

Only relevant for B2B transactions.

Permitted Values

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"

Format

CHAR(1..50)

personalid-

Person specific numbers or characters, e.g. number of passport / ID card

Format

CHAR(1..32)
Permitted Symbols
[0-9][A-Z][a-z][+-./()]

Mandatory for Denmark, Finland, Norway and Sweden

it[n]+

Klarna item type

Permitted Values
goods      : Goods
shipment   : Shipping charges
handling   : Handling fee
voucher    : Voucher / discount 
id[n]+

Product number, SKU, etc. of this item

Format

CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Permitted Symbols
[0-9][A-Z][a-z][()[]{} +-_#/:]

pr[n]+

Unit gross price of the item in smallest unit! e.g. cent

Format

NUMERIC(10) max. 19 999 999 99

Array

Array elements [n] starting with [1]; serially numbered; max [400]

no[n]+

Quantity of this item

Format

NUMERIC(6)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

de[n]+

Description of this item. Will be printed on documents to customer.

Format

CHAR(1..255)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Example
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[400]=Product 400

va[n]

+


VAT rate (% or bp)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [400]


Response "Genericpayment - start_session"


Response "Genericpayment - start_session"

API parameter

RequiredComments

add_paydata[session_id]

+

Identifier for the started session at Klarna

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


Permitted Values

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

Permitted Values

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)

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

Sample
https://x.klarnacdn.net/payment-method/assets/badges/generic/klarna.svg

status+
Permitted Values
APPROVED
ERROR
APPROVED

workorderid+

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Format

CHAR(1..50)

ERROR

errorcode+

In case of error the PAYONE Platform returns an error code for your internal usage.

Format

NUMERIC(1..6)

errormessage+

In case of error the PAYONE Platform returns an error message for your internal usage.

Format

CHAR(1..1024)

customermessage+

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Format

CHAR(1..1024)


Genericpayment 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


Genericpayment 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

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.

  • 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 than the amount of the preauthorization. A lower amount is allowed.


Request "Genericpayment - update"


Request "Genericpayment - update"

API parameterRequiredComments
add_paydata[action]+
Fixed value
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

Sample
068df369-13a7-4d47-a564-62f8408bb760

workorderid

+

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

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Format

CHAR(1..50)

country+

Specifies country of address for the customer

Format

LIST 

Permitted values

ISO 3166 2-letter-codes

Samples

DE
GB
US

Some countries require additional information in parameter "state"

amount+

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona.

The amount must be less than or equal to the amount of the corresponding booking.

Format

NUMERIC(1..10)

Permitted values

max. +/- 19 999 999 99


currency+

Specifies currency for this transaction


Format

LIST 

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR
USD
GBP


financingtype+
Permitted Values
KIS
KIV
KDD

it[n]+

Klarna item type

Permitted Values
goods      : Goods
shipment   : Shipping charges
handling   : Handling fee
voucher    : Voucher / discount 
id[n]+

Product number, SKU, etc. of this item

Format

CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Permitted Symbols
[0-9][A-Z][a-z][()[]{} +-_#/:]

AN..32

pr[n]+

Unit gross price of the item in smallest unit! e.g. cent

Format

NUMERIC(10) max. 19 999 999 99

Array

Array elements [n] starting with [1]; serially numbered; max [400]

no[n]+

Quantity of this item

Format

NUMERIC(6)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

de[n]+

Description of this item. Will be printed on documents to customer.

Format

CHAR(1..255)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Example
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[400]=Product 400

AN..50

va[n]+

VAT rate (% or bp)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [400]


narrative_text-

Dynamic text element on account statements

Format

CHAR(1..81)

(3 lines with 27 characters each) and credit card statements.


Response "Genericpayment - update"


Response "Genericpayment - update"

API parameter

RequiredComments
status+
Permitted Values
APPROVED
ERROR
APPROVED

workorderid+

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Format

CHAR(1..50)

ERROR

errorcode+

In case of error the PAYONE Platform returns an error code for your internal usage.

Format

NUMERIC(1..6)

errormessage+

In case of error the PAYONE Platform returns an error message for your internal usage.

Format

CHAR(1..1024)

customermessage+

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Format

CHAR(1..1024)







addresponsedata[reservation_txid]

The reservation_txid is a technical id returned from the PAYONE platform to identify a reservation. A reservation is a part of a payment process (identified by a txid). The reservation is used for "genericrequest".

Format

CHAR(12..50)
Permitted Symbols
[0-9,A-Z]

addresponsedata[workorderid]

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Format

CHAR(1..50)

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)

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.

  • 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"


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"


Response "Genericpayment - cancel_authorization"

API parameter

RequiredComments
status+
Permitted Values
APPROVED
ERROR
APPROVED

workorderid+

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Format

CHAR(1..50)

ERROR

errorcode+

In case of error the PAYONE Platform returns an error code for your internal usage.

Format

NUMERIC(1..6)

errormessage+

In case of error the PAYONE Platform returns an error message for your internal usage.

Format

CHAR(1..1024)

customermessage+

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Format

CHAR(1..1024)

Preauthorization / Authorization

Request "preauthorization / authorization"


Request "preauthorization / authorization"

API parameter

RequiredComments
add_paydata[authorization_token]+
Sample
987d6543-f27b-45t5-b378-245465456780
Format
String
firstname+

First name of customer; optional if company is used, i.e.: you may use

  • "company"
  • or "lastname"
  • or "firstname" plus "lastname"

Format

CHAR(1..50)

full address required and must match the shipping-address

lastname+

Last name of customer; optional if company is used, i.e.: you may use

  • "company"
  • or "lastname"
  • or "firstname" plus "lastname"

Format

CHAR(2..50)

full address required and must match the shipping-address

company-

If filled, the transaction is marked as B2B.

Company name of customer; The company name is optional if lastname is used, i.e.: you may use

  • "company"
  • or "lastname"
  • or "firstname" plus "lastname"

Format

CHAR(2..50)

street+

Street number and name

Format

CHAR(1..50)

full address required and must match the shipping-address

zip+

Postcode

Format

CHAR(2..10)
Permitted Symbols
[0-9][A-Z][a-z][_.-/ ]

full address required and must match the shipping-address

city+

City of customer

Format

CHAR(2..50)

full address required and must match the shipping-address

country+

Specifies country of address for the customer

Format

LIST 

Permitted values

ISO 3166 2-letter-codes

Samples

DE
GB
US

Some countries require additional information in parameter "state"

full address required and must match the shipping-address

addressadditiono

Specifies an additional address line for the invoice address of the customer.

Format

CHAR(1..50)

Samples

7th floor
c/o Maier

mandatory for NL

gendero

Gender of customer (female / male / diverse* )

Format

LIST 

Permitted values

f    
m
d

* not in use by now

mandatory for Austria, Germany and the Netherlands

"d" is currently not supported by Klarna

ip+

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

Format

CHAR(1..39)

email+

email-address of customer

Format

CHAR(5..254)
Permitted Symbols
RFC 5322

telephonenumber-

Phone number of customer

Format

CHAR(1..30)

birthdayo

Date of birth of customer


Format

DATE(8), YYYYMMDD

Samples

20190101
19991231

mandatory for Austria, Germany, Switzerland and the Netherlands.

shipping_firstname-

First name of delivery address

Format

CHAR(1..50)

shipping_lastname-

Surname of delivery address

Format

CHAR(1..50)

shipping_company-

Company Name of the delivery address

Format

CHAR(2..50)

shipping_street-

Street number and name of delivery address

Format

CHAR(2..50)

shipping_zip-

Postcode of delivery address

Format

CHAR(2..10)
Permitted Symbols
[0-9][A-Z][a-z][_.-/ ]

shipping_city-

City of delivery address

Format

CHAR(2..50)

shipping_country-

Specifies country of delivery address for the customer

Format

LIST 

Permitted values

ISO 3166 2-letter-codes

Samples

DE
GB
US

Some countries require additional information in parameter shipping_state

personalido

Person specific numbers or characters, e.g. number of passport / ID card

Format

CHAR(1..32)
Permitted Symbols
[0-9][A-Z][a-z][+-./()]

Mandatory for Denmark, Finland, Norway and Sweden

it[n]+

Klarna item type

Permitted Values
goods : Goods
shipment : Shipping charges
handling : Handling fee
voucher : Voucher / discount 
id[n]+

Product number, SKU, etc. of this item

Format

CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Permitted Symbols
[0-9][A-Z][a-z][()[]{} +-_#/:]

pr[n]+

Unit gross price of the item in smallest unit! e.g. cent

Format

NUMERIC(10) max. 19 999 999 99

Array

Array elements [n] starting with [1]; serially numbered; max [400]

no[n]+

Quantity of this item

Format

NUMERIC(6)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

de[n]+

Description of this item. Will be printed on documents to customer.

Format

CHAR(1..255)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Example
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[400]=Product 400

va[n]+

VAT rate (% or bp)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [400]


Authorization - 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"


Response "preauthorization / authorization"

Common Parameter

RequiredFormatComment

status

+


Permitted Values
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

+


The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

userid

+


PAYONE User ID, defined by PAYONE

Format

NUMERIC(6..12)

Parameter (PENDING)

txid

+


The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

userid

+


PAYONE User ID, defined by PAYONE

Format

NUMERIC(6..12)

Parameter (REDIRECT)

txid

+


The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

userid

+


PAYONE User ID, defined by PAYONE

Format

NUMERIC(6..12)

redirecturl

+


Redirect URL → zMerchant system has to redirect customer to this URL to complete payment

Format

CHAR(2..2000)

Parameter (ERROR)

errormessage

+


In case of error the PAYONE Platform returns an error message for your internal usage.

Format

CHAR(1..1024)

customermessage

-


The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Format

CHAR(1..1024)


Authorization - 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"


Request "capture"

API parameter

RequiredComments
txid+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

sequencenumbero

Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2

Required for multi partial capture (starting with the 2nd capture)

Format

NUMERIC(1..3)

Permitted values

0..127

capturemode+

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

Specifies whether this capture is the last one or whether there will be another one in future.

Format

LIST 
ValueComment
completed
  • Set with last capture; i.e.: Delivery completed.
  • No further capture is allowed.
notcompleted
  • Set with partial deliveries (last delivery with "completed")
  • Another capture is expected to complete the transaction.

Payment specific:

Payment typeComment

PDT

Parameter "capturemode" is mandatory.
KLS, KLVParameter "capturemode" is mandatory.

settleaccount+

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

Carry out settlement of outstanding balances. The request is booked and the resulting balance is settled by means of a collection, e.g. a refund.

Format

LIST 
ValueComment
yesSettlement of outstanding balances is carried out.
noDo not carry out settlement of outstanding balances, book request only.
autoThe system decides - depending on type of payment and balance - if a settlement of balances can be carried out or not. (default)

amount+

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona.

The amount must be less than or equal to the amount of the corresponding booking.

Format

NUMERIC(1..10)

Permitted values

max. +/- 19 999 999 99

currency+

Carry out settlement of outstanding balances. The request is booked and the resulting balance is settled by means of a collection, e.g. a refund.

Format

LIST 
ValueComment
yesSettlement of outstanding balances is carried out.
noDo not carry out settlement of outstanding balances, book request only.
autoThe system decides - depending on type of payment and balance - if a settlement of balances can be carried out or not. (default)

narrative_text-

Dynamic text element on account statements

Format

CHAR(1..81)

(3 lines with 27 characters each) and credit card statements.

de[n]-

Description of this item. Will be printed on documents to customer.

Format

CHAR(1..255)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Example
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[400]=Product 400

no[n]-

Quantity of this item

Format

NUMERIC(6)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

id[n]-

Product number, SKU, etc. of this item

Format

CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Permitted Symbols
[0-9][A-Z][a-z][()[]{} +-_#/:]

it[n]-

Parameter it[n] specifies the item type of a shopping cart item.

Format

LIST 

Array

Array elements [n] starting with [1]; serially numbered; max [400]


it[n]

Comments


goodsGoods
shipment

Shipping charges


handling

Handling fee

  • Not to be used with PDT
voucherVoucher / discount
  • Not to be used with PDT

va[n]-

VAT rate (% or bp)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

pr[n]-

Unit gross price of the item in smallest unit! e.g. cent

Format

NUMERIC(10) max. 19 999 999 99

Array

Array elements [n] starting with [1]; serially numbered; max [400]

add_paydata[shipping_info_shipping_company_n]-

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

Format

CHAR(1..100)

Samples

DHL US

DHL

add_paydata[shipping_info_shipping_method_n]-

Shipping method.

Permitted Values

PickUpStore

Home

BoxReg

BoxUnreg

PickUpPoint

Own

add_paydata[shipping_info_tracking_number_n]-

Tracking number for the shipment.

Format

CHAR(1..100)

add_paydata[shipping_info_tracking_uri_n]-

URI where the customer can track their shipment.

Format

CHAR(1..1024)

add_paydata[shipping_info_return_shipping_company_n]-

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

Format

CHAR(1..100)

Samples

DHL US

DHL

add_paydata[shipping_info_return_tracking_uri_n]-

URL where the customer can track the return shipment.

Format

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.

Format

INT(1..50)

Permitted values

min: 0


Response "Capture"


Response "Capture"

Common Parameter

Required

Comment

status

+

Permitted Values
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

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

settleaccount

+

Provides information about whether a settlement of balances has been carried out.

Format

LIST 
ValueComment
yesSettlement of outstanding balances has been carried out.
noSettlement of outstanding balances has not been carried out.

Parameter (ERROR)

errorcode

+

In case of error the PAYONE Platform returns an error code for your internal usage.

Format

NUMERIC(1..6)

errormessage

-

In case of error the PAYONE Platform returns an error message for your internal usage.

Format

CHAR(1..1024)

customermessage

-

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Format

CHAR(1..1024)


Debit / Refund

Request "Debit"


Request "Debit"

Common Parameter

Required

Short explanation

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

sequencenumber

+

Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2

Required for multi partial capture (starting with the 2nd capture)

Format

NUMERIC(1..3)

Permitted values

0..127

amount

+

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

Gross amount of debit (in smallest currency unit! e.g. cent, max. 19 999 999 99)

Credit: amount < 0

Payment request: amount > 0

The amount must be less than or equal to the amount of the outstanding payment request of the corresponding booking.

Format

NUMERIC(1..10), max. value +/- 19 999 999 99

currency

+

Specifies currency for this transaction


Format

LIST 

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR
USD
GBP

narrative_text

-

Dynamic text element on account statements

Format

CHAR(1..81)

(3 lines with 27 characters each) and credit card statements.

use_customerdata

-

Use account details from debtor's master data

Format

LIST 
ValueComment

yes

Uses current account details from debtor's master data (default)

no

Uses the last known account details in the payment process

transaction_param

-

Optional parameter for merchant information (per payment request)

Format

CHAR(1..50)
Permitted Symbols
[0-9][A-Z][a-z][.-_/]


settleaccount

+

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

Carry out settlement of outstanding balances. The request is booked and the resulting balance is settled by means of a collection, e.g. a refund.

Format

LIST 
ValueComment
yesSettlement of outstanding balances is carried out.
noDo not carry out settlement of outstanding balances, book request only.
autoThe system decides - depending on type of payment and balance - if a settlement of balances can be carried out or not. (default)

invoiceid

-

Merchant's invoice number

Format

CHAR(1..20)

invoice_deliverymode

-

Parameter defines how documents like invoice, credit notes and reminders should be sent to the customer.

Format

LIST 
ValueComments

M

Postal Mail

P

PDF (via email)

N

no delivery


invoiceappendix

-

Dynamic text on the invoice

Format

CHAR(1..255)

invoice_deliverydate

-

Delivery date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

invoice_deliveryenddate

-

Delivery end date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

it[n]

-

Parameter it[n] specifies the item type of a shopping cart item.

Format

LIST 

Array

Array elements [n] starting with [1]; serially numbered; max [400]


it[n]

Comments


goodsGoods
shipment

Shipping charges


handling

Handling fee

  • Not to be used with PDT
voucherVoucher / discount
  • Not to be used with PDT

id[n]

-

Product number, SKU, etc. of this item

Format

CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Permitted Symbols
[0-9][A-Z][a-z][()[]{} +-_#/:]

pr[n]

-

Unit gross price of the item in smallest unit! e.g. cent

Format

NUMERIC(10) max. 19 999 999 99

Array

Array elements [n] starting with [1]; serially numbered; max [400]

no[n]

-

Quantity of this item

Format

NUMERIC(6)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

de[n]

-

Description of this item. Will be printed on documents to customer.

Format

CHAR(1..255)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Example
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[400]=Product 400

va[n]

-

VAT rate (% or bp)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

sd[n]

-

Delivery date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

Array

Array elements [n] starting with [1]; serially numbered; max [400]

ed[n]

-

Delivery period end date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

Array

Array elements [n] starting with [1]; serially numbered; max [400]


Response "Debit"


Response "Debit"

Common Parameter

Required

Comment

status

+

Permitted Values
APPROVED
ERROR

Parameter (APPROVED)

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

settleaccount

+

Provides information about whether a settlement of balances has been carried out.

Format

LIST 
ValueComment
yesSettlement of outstanding balances has been carried out.
noSettlement of outstanding balances has not been carried out.

Parameter (ERROR)

errorcode

+

In case of error the PAYONE Platform returns an error code for your internal usage.

Format

NUMERIC(1..6)

errormessage

-

In case of error the PAYONE Platform returns an error message for your internal usage.

Format

CHAR(1..1024)

customermessage

-

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Format

CHAR(1..1024)


Request "Refund"


Request "Refund"

API parameter

RequiredComments

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

sequencenumber+

Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2

Required for multi partial capture (starting with the 2nd capture)

Format

NUMERIC(1..3)

Permitted values

0..127

amount+

Amount of refund (in smallest currency unit! e.g. cent, max. 19 999 999 99). The amount must be less than or equal to the amount of the corresponding booking.

Always provide a negative amount

Format

NUMERIC(1..10), max. value +/- 19 999 999 99

currency+

Specifies currency for this transaction


Format

LIST 

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR
USD
GBP

narrative_text-

Dynamic text element on account statements

Format

CHAR(1..81)

(3 lines with 27 characters each) and credit card statements.

use_customerdata-

Use account details from debtor's master data

Format

LIST 
ValueComment

yes

Uses current account details from debtor's master data (default)

no

Uses the last known account details in the payment process

transaction_param-

Optional parameter for merchant information (per payment request)

Format

CHAR(1..50)
Permitted Symbols
[0-9][A-Z][a-z][.-_/]

invoiceid-

Merchant's invoice number

Format

CHAR(1..20)

invoice_deliverymode

-

Parameter defines how documents like invoice, credit notes and reminders should be sent to the customer.

Format

LIST 
ValueComments

M

Postal Mail

P

PDF (via email)

N

no delivery


invoiceappendix-

Dynamic text on the invoice

Format

CHAR(1..255)

invoice_deliverydate-

Delivery date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

invoice_deliveryenddate-

Delivery end date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

de[n]-

Description of this item. Will be printed on documents to customer.

Format

CHAR(1..255)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Example
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[400]=Product 400

no[n]-

Quantity of this item

Format

NUMERIC(6)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

id[n]-

Product number, SKU, etc. of this item

Format

CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Permitted Symbols
[0-9][A-Z][a-z][()[]{} +-_#/:]

pr[n]-

Unit gross price of the item in smallest unit! e.g. cent

Format

NUMERIC(10) max. 19 999 999 99

Array

Array elements [n] starting with [1]; serially numbered; max [400]

it[n]-

Parameter it[n] specifies the item type of a shopping cart item.

Format

LIST 

Array

Array elements [n] starting with [1]; serially numbered; max [400]


it[n]

Comments


goodsGoods
shipment

Shipping charges


handling

Handling fee

  • Not to be used with PDT
voucherVoucher / discount
  • Not to be used with PDT

va[n]-

VAT rate (% or bp)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [400]


Response "Refund"


Response "Refund"

Common Parameter

Required

Comment

status

+

Permitted Values
APPROVED
ERROR

Parameter (APPROVED)

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

settleaccount

+

Provides information about whether a settlement of balances has been carried out.

Format

LIST 
ValueComment
yesSettlement of outstanding balances has been carried out.
noSettlement of outstanding balances has not been carried out.

Parameter (ERROR)

errorcode

+

In case of error the PAYONE Platform returns an error code for your internal usage.

Format

NUMERIC(1..6)

errormessage

-

In case of error the PAYONE Platform returns an error message for your internal usage.

Format

CHAR(1..1024)

customermessage

-

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Format

CHAR(1..1024)


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)


  • No labels