General Notes

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 "direct_debit" (Direct Debit)
fncKBTKlarna "Pay Now" (Direct Bank Transfer)

Summary

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


Establishing 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. This step is a pre-condition for loading the Klarna widget.

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

→ Genericpayment start_session

Optional - Update the Session

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

→ Genericpayment update_session

Handle Token

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

→ Widget

Finalize the Checkout ((Pre-)Authorization)

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

→ Preauthorization/Authorization

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

Klarna Checkout Processing Sequence

General Integration Information

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

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


Overview Client-Side Implementation

Display Klarna Widget

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

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

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. Please note that the Klarna widget requires a minimum width of 280px.

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

Load Klarna Widget

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

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. In addition the object "error" can be retrieved to receive further information about potential problems. The response information enables you to display to your customer Klarna as a payment method only when it can actually be utilised by your customer. In summary, there are three situations deriving from the "Receive Response" call.

Positive Response

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

{
show_form: true
}

Adjust and Try Again

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

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

Negative Response

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

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

{
show_form: false
}

Klarna Authorize

Authorise the Purchase

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

Sending the Request

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

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

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

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

User interaction during the authorize call

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

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

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

Process callback from authorise call

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

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

Order approved

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

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

Order not approved

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

Option 1 - Fixable error

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

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

Option 2 - Order declined

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

{
approved: false,
show_form: false
}

Finalize the authorisaton

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

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

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

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

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

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

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

Overview Server-Side API Calls

Genericpayment start_session

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

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

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

Fixed Value

genericpayment
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 (required: at least one character)

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

* currently not in use

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

Special Remark email validation:

Max. length for email is 254 characters. Validation is set up in the following way:

  • Username = Max. 63 characters
  • Domain Name = Max. 63 characters
  • Domain Suffixes = Max. 4 suffixes with max. 124 characters 

Example: username[63]@domain_name[63].suffix[60].suffix[60].suffix[4]


"@" and "." is counted as a character as well; in case of a total of three suffixes, this would allow a total of 254 characters.

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

+

successurl - definition

URL for "payment successful"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

errorurl+

errorurl - definition

URL for "faulty payment"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

backurl+

backurl - definition

URL for "Back" or "Cancel"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

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]

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


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

add_paydata[payment_method_category_identifier]+

Identifier for Klarna payment category

Permitted Values

Pay_later

Pay_now

Pay_over_time

Direct_bank_transfer

Direct_debit

add_paydata[payment_method_category_asset_url_descriptive]+

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

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

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

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


Request "Genericpayment - update"


Request "Genericpayment - update"

API parameterRequiredComments
request+

Fixed Value

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

Fixed Value

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


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 (required: at least one character)

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

* currently not in use

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

Special Remark email validation:

Max. length for email is 254 characters. Validation is set up in the following way:

  • Username = Max. 63 characters
  • Domain Name = Max. 63 characters
  • Domain Suffixes = Max. 4 suffixes with max. 124 characters 

Example: username[63]@domain_name[63].suffix[60].suffix[60].suffix[4]


"@" and "." is counted as a character as well; in case of a total of three suffixes, this would allow a total of 254 characters.

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

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.

+

successurl - definition

URL for "payment successful"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

errorurl+

errorurl - definition

URL for "faulty payment"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

backurl+

backurl - definition

URL for "Back" or "Cancel"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

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]

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)


Authorization - Example Request
add_paydata[authorization_token]=aaa-bbbb-11111-2222-ccc
add_paydata[shipping_telephonenumber]=016545521585
add_paydata[shipping_email]=klarna@approved.de
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

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

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

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

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)



Refund

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

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

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