Last update 20/04/2016

1. Introduction

This guide is to inform you on how to use and integrate the Klarna Instalments and Open invoice payment method.

Integration for new transactions must be done with e-Commerce. Maintenance on existing transactions is supported in the back office and via DirectLink and Batch.

2. Integration with e-commerce

In order to use Klarna Instalments, you need to send some additional parameters to our payment page.

Klarna does not support UTF-8 encoding. Therefore, we discourage you to use the UTF-8 payment page (orderstandard_utf8.asp) and always use the ISO payment page (orderstandard.asp) for Klarna implementation.

2.1 Standard Ingenico ePayments fields

The following information is required for every transaction.

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters

Field

Format

Description

PSPID

AN, 30

Merchant unique identifier on our system

ORDERID

AN, 40

Merchant unique order reference

AMOUNT

N

Amount multiplied by 100

Including delivery and VAT

CURRENCY

AN, 3

Alpha ISO code of the currency

LANGUAGE

AN, 5

Customer's language

OPERATION

AN, 3

Specifies the Operation code to use.

For 'Open Invoice', we request that the merchant always sends the RES value

More information about these fields can be found in your Ingenico ePayments account. Just log in and go to: Support > Integration & user manuals > Technical guides > Parameter Cookbook.

2.2 Invoicing and delivery data

Note: Depending on the customer's country, some fields may or may not be required. See the table below, x=Required, o=Optional. 

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters

Field 

Format

Description

SE FI DK NO DE NL
ECOM_BILLTO_POSTAL_NAME_FIRST AN, 50 First Name

x

x

x

x

x

x

ECOM_BILLTO_POSTAL_NAME_LAST AN, 50 Last name

x

x

x

x

x

x

OWNERADDRESS AN, 35 Street

x

x

x

x

x

x

OWNERZIP AN, 10 Postcode

x

x

x

x

x

x

EMAIL AN, 50 E-mail

x

x

x

x

x

x

OWNERTOWN AN, 25 City

x

x

x

x

x

x

OWNERTELNO AN, 20 Mobile

x

x

x

x

x

x

CUID AN, 50 Social Security Number / Company registration number

 x

x

x

x

o o
ECOM_CONSUMER_GENDER AN, 1 Gender (M/F) o o o o

x

x

ECOM_SHIPTO_DOB AN, 10 Date of birth (format dd/MM/yyyy) o o o o

x

x

ECOM_BILLTO_POSTAL_STREET_NUMBER AN, 10 House number o o o o

x

x

OWNERCTY

AN, 2

Customer's country (BE, DE, NL, FR, etc.)

x

x

x

x

x

x

ORDERSHIPMETH AN, 25 Delivery method

x

x

x

x

x

x

ORDERSHIPCOST (*) N

Delivery cost
Amount multiplied by 100
Excluding VAT

o

o

o

o

o

o

ORDERSHIPTAXCODE (*) % Delivery tax code (e.g. 19%)

o

o

o

o

o

o

* For providing the shipping costs, we recommend to use the "item" fields, described in the next chapter (Order details)

More information about these fields can be found in your Ingenico ePayments account. Just log in and go to: Support > Integration & user manuals > Technical guides > Parameter Cookbook.

2.3 Order details

In addition, the merchant also has to submit the order details.

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters

Field

Format

Description

ITEMIDX

AN, 15

Item identification (replace X with a number to send multiple items: ITEMID1, ITEMID2, etc.)

ITEMNAMEX

AN, 40

Item name (replace X with a number to send multiple items: ITEMNAME1, ITEMNAME2, etc.)
ITEMPRICEX

N

Item price (replace X with a number to send multiple items: ITEMPRICE1, ITEMPRICE2, etc.)
Excluding VAT
"." as separator
ITEMQUANTX

N

Item quantity (replace X with a number to send multiple items: ITEMQUANT1, ITEMQUANT2, etc.)
ITEMVATCODEX

N

Item VAT code (replace X with a number to send multiple items: ITEMVATCODE1, ITEMVATCODE2, etc.)
TAXINCLUDEDX

N
(0 / 1)

  • If this field is equal to 1, the ITEMPRICEX is considered to include VAT, and our system will not calculate the VAT for the item.
  • If this field is equal to 0 (or left blank, or not sent) our system will calculate the VAT for the item based on the ITEMVATCODEX

> This feature is recommended as it avoids any issues when rounding off the order line totals.

(replace X with a number to send multiple items: TAXINCLUDED1, TAXINCLUDED2, etc.)

More information about these fields can be found in your Ingenico ePayments account. Just log in and go to: Support > Integration & user manuals > Technical guides > Parameter Cookbook.

Important: ascending order of line item details for SHA calculation

Please take into account that as from 10 line item details the order of the parameters for the SHA calculation may differ from what is expected on your system's side.

Where for the calculation of the SHA we normally stress that all parameters should be sorted alphabetically, a "logical" ascending order is put in place for the line item details:

- Ascending order: 1, 2, 3, 4, 5, 6, 7, etc.

- Alphabetical order: 1, 10, 11, 2, 3, 4, etc. (NOT applied) 

2.4 Example

The following form simulates a Klarna payment with all required fields.

<form id="form1" method="POST" action="https://ogone.test.v-psp.com/ncol/test/orderstandard.asp">
   <!-- standard Ingenico ePayments fields -->
   <input type="text" name="PSPID" value="[yourPSPID]"/><br/>
   <input type="text" name="ORDERID" value="order123"/><br/>
   <input type="text" name="AMOUNT" value="2261"/><br/>
   <input type="text" name="LANGUAGE" value="de_DE"/><br/>
   <input type="text" name="CURRENCY" value="EUR"/><br/>

   <!-- klarna required fields -->
   <input type="text" name="ECOM_BILLTO_POSTAL_NAME_FIRST" value="John"/><br/>
   <input type="text" name="ECOM_BILLTO_POSTAL_NAME_LAST" value="Doe"/><br/>
   <input type="text" name="OWNERADDRESS" value="test street"/><br/>
   <input type="text" name="OWNERZIP" value="10000"/><br/>
   <input type="text" name="OWNERTOWN" value="Berlin"/><br/>
   <input type="text" name="EMAIL" value="john@doe.com"/><br/>
   <input type="text" name="OWNERTELNO" value="+49 111 222 333 44"/><br/>
   <input type="text" name="ECOM_CONSUMER_GENDER" value="M"/><br/>
   <input type="text" name="ECOM_SHIPTO_DOB" value="08/10/1940"/><br/>
   <input type="text" name="ECOM_BILLTO_POSTAL_STREET_NUMBER" value="24"/><br/>
   <input type="text" name="OWNERCTY" value="DE"/><br/>
   <input type="text" name="ORDERSHIPMETH" value="Post"/><br/>
   <input type="text" name="ORDERSHIPCOST" value="100"/><br/>
   <input type="text" name="ORDERSHIPTAXCODE" value="6%"/><br/>

   <!-- order details, item 1 -->
   <input type="text" name="ITEMID1" value="item1"/><br/>
   <input type="text" name="ITEMNAME1" value="coffee"/><br/>
   <input type="text" name="ITEMPRICE1" value="3.00"/><br/>
   <input type="text" name="ITEMQUANT1" value="1"/><br/>
   <input type="text" name="ITEMVATCODE1" value="19%"/><br/>

   <!-- order details, item 2 -->
   <input type="text" name="ITEMID2" value="item2"/><br/>
   <input type="text" name="ITEMNAME2" value="tea"/><br/>
   <input type="text" name="ITEMPRICE2" value="5.00"/><br/>
   <input type="text" name="ITEMQUANT2" value="3"/><br/>
   <input type="text" name="ITEMVATCODE2" value="19%"/><br/>

   <!-- don't forget your SHA signature! -->
   <input type="text" name="SHASIGN" value="[your SHA signature]"/><br/>

   <!-- submit -->
   <input type="submit" value="submit"/>
</form>

3. Maintenance operations

In order to be able to perform refund operations, please ensure you have the "Refund" option available for your account. If in doubt, please contact our Sales team.

In the transaction overview, click on the "Advanced" button at the bottom of the screen to see the Refunding options.

When clicking on "Refund", our system will show a detail screen in which you can specify which items are to be refunded.

Klarna Refund order

By default, the Quantity column will contain the order quantities, which means that if you don't change the values, the whole order will be refunded. In order to partially refund a transaction, adapt the quantities (or use the "delete" button for each item) in order to prevent certain articles from being refunded.

Click "Submit" to confirm the refund.

Important note on partial captures/refunds

If within a transaction multiple captures are done on similar (same priced) items, a partial refund on those items can only be done if a partial capture on the same items (=belonging to the same invoice) preceded. Also, no partial refunds can have preceded on the same partially captured items.

-> If these conditions aren't met, the partial refund will be refused

If a partial refund can be linked to different partial captures; as a rule we'll take the last partial capture that was performed in time.

When multiple partial captures were done, a full refund is still possible.

Maintenance operations (refunds and captures) can be performed via DirectLink. 

Note: You must have the Ingenico ePayments DirectLink option activated in your Ingenico ePayments account in order to use this feature. Please contact our Sales team for more information about this product.

The following fields can or must be submitted with each maintenance operation request:

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters
Field Description Format Mandatory
AMOUNT

Total amount to be refunded, including VAT.

N Y
CURRENCY Transaction currency (EUR, CHF, USD, GBP, etc.) AN, 3 Y
OPERATION

Operation to be performed.

  • RFD = Partial refund
  • RFS = (Last) Partial or Full refund
For a full list of possible operations, please refer to the Parameter Cookbook in your Ingenico ePayments account.
AN, 3 N
ORDERID Your unique order reference AN, 30 Y
PAYID Our payment reference, which was sent to you after the initial transaction N Y
PSPID Your unique identifier on our system AN, 30 Y
PSWD

The user's password

AN, 20 Y
USERID User performing the maintenance. This is needed for security reasons. The user needs to have API privileges (cf. the User Manager documentation for more details) AN, 20 Y

 

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters
Field Description Format Mandatory
ITEMIDX

Item identification (replace X with a number to send multiple items: ITEMID1, ITEMID2, etc.)

AN, 15

Y

ITEMNAMEX Item name (replace X with a number to send multiple items: ITEMNAME1, ITEMNAME2, etc.)

AN, 30

Y

ITEMPRICEX

Item price (replace X with a number to send multiple items: ITEMPRICE1, ITEMPRICE2, etc.)Multiplied by 100 (unlike the original submission)

N

Y

ITEMQUANTX Item quantity (replace X with a number to send multiple items: ITEMQUANT1, ITEMQUANT2, etc.)

N

Y

ITEMVATCODEX Item VAT code (replace X with a number to send multiple items: ITEMVATCODE1, ITEMVATCODE2, etc.)

Percentage

Y

TAXINCLUDEDX
  • If this field equals 1, then the ITEMPRICEX is considered to include VAT, and our system will not calculate the VAT for the item.
  • If this field is equal to 0 (or left blank, or not sent) our system will calculate the VAT for the item based on the ITEMVATCODEX

This feature is intended to avoid any issues when rounding off the order line totals.(replace X with a number to send multiple items: TAXINCLUDED1, TAXINCLUDED2, etc.)

(replace X with a number to send multiple items: TAXINCLUDED1, TAXINCLUDED2, etc.)

0 or 1

N

<form action="https://ogone.test.v-psp.com/ncol/test/maintenancedirect.asp" method="post">
<input type="text" name="PSPID" value="[your pspid]"/><br/>
<input type="text" name="USERID" value="[username]"/><br/>
<input type="text" name="PSWD" value="[password]"/><br/>
<input type="text" name="PAYID" value="[payid] "/><br/>
<input type="text" name="ORDERID" value="[order id]"/><br/>
<input type="text" name="AMOUNT" value="119"/><br/>
<input type="text" name="OPERATION" value="RFD"/><br/>
<input type="text" name="CURRENCY" value="EUR"/><br/>

<input type="text" name="ITEMID1" value="1"/><br/>
<input type="text" name="ITEMNAME1" value="first item"/><br/>
<input type="text" name="ITEMPRICE1" value="119"/><br/>
<input type="text" name="ITEMQUANT1" value="1"/><br/>
<input type="text" name="ITEMVATCODE1" value="19%"/><br/>
<input type="text" name="TAXINCLUDED1" value="1"/><br/>
<input type="submit" name="submit" value="submit"/>
</form>

Note: The SHA Signature is not required for maintenance operations.

A test page for DirectLink is available here: https://ogone.test.v-psp.com/ncol/test/testdm.asp?details=1

OHL;[your pspid];[your password];;[your username];
OHF;[file name];MTR;RFD;1;
MTR;EUR;;;;;;;[PAYID];RFD;;;;[your pspid];;1;;;;;;;;;;;;;;;;;;119;
DET;1;2;first item;119;1;19%;;;;;;;;
OTF;

Partial maintenance: Please note that the given example applies in exactly the same way to partial/multiple maintenance operations. This means that also the line item details are mandatory in e.g. partial refund requests.

For more information, go to DirectLink

3.2 Batch

Maintenance operations (refunds, captures) can be done via Batch. 

Note: You must have the Ingenico ePayments Batch option activated in your Ingenico ePayments account in order to use this feature. Please contact our Sales team for more information about this product.

3.2.1 Data

The following information should be sent along with each batch file:

Login information: OHL

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters
Position Field Format
1 Fixed value: 'OHL'. This indicates that the line contains login information /
2 PSPID, the merchant's unique identifier on our platform AN, 30
3 The API user's password AN, 20
4 (leave empty)
5 The API username AN, 20

 

File information: OHF

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters
Position Field Format
1 Fixed value: 'OHF'. This indicates that the line contains file information /
2 Name of the submitted file AN, 50
3 Fixed value: 'MTR'. This indicates that a maintenance operation is being performed on an existing transaction /
4

Operation Code:

  • RFD = Partial refund
  • RFS = (Last) Partial or Full refund
AN, 3
5 Number of Transactions affected by the current file N

 

Transaction information: MTR

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters
Position Field Format
1
Fixed value: 'MTR'. This indicates that the line contains transaction information
/
2
Currency
AN, 3
3-8
(leave empty)

9
PAYID, the unique reference generated and provided by our system in the initial transaction feedback
N
10
Operation Code:
  • RFD = Partial refund
  • RFS = (Last) Partial or Full refund
AN, 3
11-13
(leave empty)

14
PSPID, the merchant's unique identifier on our platform

15
(leave empty)

16
Number of detail lines for the current transaction N
17-33
(leave empty)
34
Amount of the Operation, multiplied by 100 N

 

Line Details: DET

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters
Position Field Format
1 Fixed value: 'DET'. This indicates that the line contains a detail line /
2 Quantity N
3 Item ID AN, 15
4 Item name AN, 30
5 Item unit price, Multiplied by 100 to avoid rounding off issues N
6 Indicates whether the price is:
1 includes VAT or
0 excludes VAT
AN, 1
7 VAT rate, in the form of a percentage (including the % symbol) This is required, even if the amount includes VAT N%
8-15 (leave empty)

 

End of File: OTF

Format: AN= Alphanumeric / N=Numeric, maximum allowed amount of characters
Position Field Format
1 Fixed value: 'OTF'. This indicates that it is the last line of the file /

3.2.2 Example

OHL;[your pspid];[your password];;[your username];
OHF;[file name];MTR;RFD;1;
MTR;EUR;;;;;;;[PAYID];RFD;;;;[your pspid];;1;;;;;;;;;;;;;;;;;;119;
DET;1;2;first item;119;1;19%;;;;;;;;
OTF;

Partial maintenance: Please note that the given example applies in exactly the same way to partial/multiple maintenance operations. This means that also the line item details are mandatory in e.g. partial refund requests.

For more information, go to Batch.

4. Update campaigns (Instalments)

Important

When changes occur in the merchant's campaigns on the Klarna platform, these changes are NOT automatically replicated to our platform. This requires a manual action, which has to be performed by one of our employees.

Please contact our Customer Care team (support.ecom@ingenico.com) to have your Klarna campaigns updated on our system.

This website uses cookies to be able to give you the best user experience. If you don't want to accept these cookies, we allow you to change the cookie settings. Click 'Accept' to allow all cookies from this website.

Cookie settings

Introduction

Functional

Functional cookies are required for the website to operate correctly. These cookies cannot be disabled.

Optimized

Optimization cookies allow us to analyze site usage so we can measure and improve our website.
This is the default level.

Personalized

Personalization cookies are used for social media and advanced personalization. They allow us to show you information related to your company.


Example functionality allowed

  • Store country preference
  • Store language preference

Example functionality not allowed

  • Saving personal data
  • Anonymous tracking via Google Analytics
  • Tracking for remarketing purposes

Example functionality allowed

  • Store country preference
  • Store language preference
  • Anonymous tracking via Google Analytics

Example functionality not allowed

  • Saving personal data
  • Tracking for remarketing purposes

Example functionality allowed

  • Store country preference
  • Store language preference
  • Anonymous tracking via Google Analytics
  • Serve content relevant to your interests
  • Serve ads relevant to your interests
  • Tracking for remarketing purposes

Example functionality not allowed

  • Saving personal data