- Created by PAYONE Writer, last modified by PAYONE Admin on 2021-11-05
General Notes
Payment Type | Countries | Currency |
---|---|---|
Invoice |
|
|
Installments | ||
Direct Debit |
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 | |
---|---|---|
fnc | KIS | Klarna "Slice It" (Installments) |
fnc | KIV | Klarna "Pay Later" (Invoice) |
fnc | KDD | Klarna "Pay Now" (Direct Debit) |
fnc | KBT | Klarna "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.
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.
→ 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:
- Avoid sending another authorize call (e.g. disable the buy button from being clicked again)
- Show to the consumer that the order is being processed (e.g. by showing a loading spinner)
- 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 "Generic Start Session" | ||
API parameter | Required | Comments |
---|---|---|
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 | + | |
firstname | - |
First name of customer; optional if company is used, i.e.: you may use
Format CHAR(1..50)
|
lastname | - |
Last name of customer; optional if company is used, i.e.: you may use
Format CHAR(2..50)
|
company | - |
Company name of customer; The company name is optional if lastname is used, i.e.: you may use
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 ISO 3166-2 States (regions) 2-letter-codes 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-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:
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
|
- |
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 ISO 3166-2 States (regions) 2-letter-codes 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 |
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 Expand source
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]
|
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" | ||
API parameter | Required | Comments |
---|---|---|
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)
|
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" | ||
API parameter | Required | Comments |
---|---|---|
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 |
+ | 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 | + | |
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 |
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 Expand source
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" | ||
API parameter | Required | Comments |
---|---|---|
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" | ||
API parameter | Required | Comments |
---|---|---|
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" | ||
API parameter | Required | Comments |
---|---|---|
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" | ||
API parameter | Required | Comments |
---|---|---|
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
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
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
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 | + | |
addressaddition | o |
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 |
gender | o |
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-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:
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 | o |
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
|
+ |
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}
|
personalid | o |
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 Expand source
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)
|
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" | |||
Common Parameter | Required | Format | Comment |
---|---|---|---|
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) | |||
+ |
The txid specifies the payment process within the PAYONE platform Format NUMERIC(9..12)
| ||
+ |
PAYONE User ID, defined by PAYONE Format NUMERIC(6..12)
| ||
Parameter (PENDING) | |||
+ | The txid specifies the payment process within the PAYONE platform Format NUMERIC(9..12) | ||
+ |
PAYONE User ID, defined by PAYONE Format NUMERIC(6..12)
| ||
Parameter (REDIRECT) | |||
+ |
The txid specifies the payment process within the PAYONE platform Format NUMERIC(9..12)
| ||
+ |
PAYONE User ID, defined by PAYONE Format NUMERIC(6..12)
| ||
+ |
Redirect URL → zMerchant system has to redirect customer to this URL to complete payment Format CHAR(2..2000)
| ||
Parameter (ERROR) | |||
+ |
In case of error the PAYONE Platform returns an error message for your internal usage. Format CHAR(1..1024)
| ||
- |
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)
|
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" | |||||||||||||||||
API parameter | Required | Comments | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
txid | + |
The txid specifies the payment process within the PAYONE platform Format NUMERIC(9..12)
| |||||||||||||||
sequencenumber | o |
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
Payment specific:
| |||||||||||||||
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
| |||||||||||||||
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
| |||||||||||||||
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 Expand source
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]
| |||||||||||||||
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" | ||||||||
---|---|---|---|---|---|---|---|---|
Common Parameter | Required | Comment | ||||||
status | + | Permitted Values
APPROVED ERROR | ||||||
clearing_instructionnote | o |
| ||||||
Parameter (APPROVED) | ||||||||
+ |
The txid specifies the payment process within the PAYONE platform Format NUMERIC(9..12)
| |||||||
+ |
Provides information about whether a settlement of balances has been carried out. Format LIST
| |||||||
Parameter (ERROR) | ||||||||
+ |
In case of error the PAYONE Platform returns an error code for your internal usage. Format NUMERIC(1..6)
| |||||||
- |
In case of error the PAYONE Platform returns an error message for your internal usage. Format CHAR(1..1024)
| |||||||
- |
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" | |||||||||||||||||||
Common Parameter | Required | Short explanation | |||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+ |
The txid specifies the payment process within the PAYONE platform Format NUMERIC(9..12)
| ||||||||||||||||||
+ |
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
| ||||||||||||||||||
+ | 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
| ||||||||||||||||||
+ |
Specifies currency for this transaction Format LIST Permitted values ISO 4217 (currencies) 3-letter-codes Samples EUR USD GBP
| ||||||||||||||||||
- |
Dynamic text element on account statements Format CHAR(1..81) (3 lines with 27 characters each) and credit card statements.
| ||||||||||||||||||
- |
Use account details from debtor's master data Format LIST
| ||||||||||||||||||
- |
Optional parameter for merchant information (per payment request) Format CHAR(1..50) Permitted Symbols
[0-9][A-Z][a-z][.-_/]
| ||||||||||||||||||
+ | 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
| ||||||||||||||||||
- |
Merchant's invoice number Format CHAR(1..20)
| ||||||||||||||||||
- |
Parameter defines how documents like invoice, credit notes and reminders should be sent to the customer. Format LIST
| ||||||||||||||||||
- |
Dynamic text on the invoice Format CHAR(1..255)
| ||||||||||||||||||
- |
Delivery date (YYYYMMDD) Format DATE(8), YYYYMMDD
| ||||||||||||||||||
- |
Delivery end date (YYYYMMDD) Format DATE(8), YYYYMMDD
| ||||||||||||||||||
- |
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]
| ||||||||||||||||||
- |
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][()[]{} +-_#/:]
| ||||||||||||||||||
- |
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]
| ||||||||||||||||||
- |
Quantity of this item Format NUMERIC(6) Array Array elements [n] starting with [1]; serially numbered; max [400]
| ||||||||||||||||||
- |
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 Expand source
de[1]=Product 1 de[2]=Product 2 de[3]=Product 3 ... de[400]=Product 400
| ||||||||||||||||||
- |
VAT rate (% or bp) Format NUMERIC(4) Array Array elements [n] starting with [1]; serially numbered; max [400]
| ||||||||||||||||||
- |
Delivery date (YYYYMMDD) Format DATE(8), YYYYMMDD Array Array elements [n] starting with [1]; serially numbered; max [400]
| ||||||||||||||||||
- |
Delivery period end date (YYYYMMDD) Format DATE(8), YYYYMMDD Array Array elements [n] starting with [1]; serially numbered; max [400]
|
Response "Debit" | ||||||||
---|---|---|---|---|---|---|---|---|
Common Parameter | Required | Comment | ||||||
status | + | Permitted Values
APPROVED ERROR | ||||||
Parameter (APPROVED) | ||||||||
+ |
The txid specifies the payment process within the PAYONE platform Format NUMERIC(9..12)
| |||||||
+ |
Provides information about whether a settlement of balances has been carried out. Format LIST
| |||||||
Parameter (ERROR) | ||||||||
+ |
In case of error the PAYONE Platform returns an error code for your internal usage. Format NUMERIC(1..6)
| |||||||
- |
In case of error the PAYONE Platform returns an error message for your internal usage. Format CHAR(1..1024)
| |||||||
- |
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" | |||||||||||||||||
API parameter | Required | Comments | |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+ |
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
| |||||||||||||||
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)
| |||||||||||||||
- |
Parameter defines how documents like invoice, credit notes and reminders should be sent to the customer. Format LIST
| ||||||||||||||||
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 Expand source
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]
| |||||||||||||||
va[n] | - |
VAT rate (% or bp) Format NUMERIC(4) Array Array elements [n] starting with [1]; serially numbered; max [400]
|
Response "Refund" | ||||||||
---|---|---|---|---|---|---|---|---|
Common Parameter | Required | Comment | ||||||
status | + | Permitted Values
APPROVED ERROR | ||||||
Parameter (APPROVED) | ||||||||
+ |
The txid specifies the payment process within the PAYONE platform Format NUMERIC(9..12)
| |||||||
+ |
Provides information about whether a settlement of balances has been carried out. Format LIST
| |||||||
Parameter (ERROR) | ||||||||
+ |
In case of error the PAYONE Platform returns an error code for your internal usage. Format NUMERIC(1..6)
| |||||||
- |
In case of error the PAYONE Platform returns an error message for your internal usage. Format CHAR(1..1024)
| |||||||
- |
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)
- example cart with auth
- 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)
- example cart with auth
- No labels