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.

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

1.1 Standard Nexi Payengine 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 Nexi Payengine account. Just log in and go to: Support > Integration & user manuals > Technical guides > Parameter Cookbook.

1.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
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_BILLTO_POSTAL_CITY
AN, 25 Invoicing city o o o o

x

x

ECOM_BILLTO_POSTAL_COUNTRYCODE
AN, 2 Invoicing country code o o o o

x

x

ECOM_BILLTO_POSTAL_COUNTY
AN, 25 Invoicing county o o o o

x

x

ECOM_BILLTO_POSTAL_NAME_FIRST
AN, 35 First name of billed customer
o o o o

x

x

ECOM_BILLTO_POSTAL_NAME_LAST
AN, 35 Last name of billed customer o o o o

x

x

ECOM_BILLTO_POSTAL_POSTALCODE
AN, 10 Invoicing postal code o o o o

x

x

ECOM_BILLTO_POSTAL_STREET_LINE1
AN, 35 Billing address, first line
o o o o

x

x

ECOM_BILLTO_POSTAL_STREET_LINE2
AN, 35 Billing address, second line o
o
o o x
x
ECOM_BILLTO_POSTAL_STREET_NUMBER AN, 10 House number o o o o

x

x

ECOM_SHIPTO_COMPANY
AN, 50 Delivery address: Company 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_SHIPTO_ONLINE_EMAIL
AN, 50
E-mail address o o o o x x
ECOM_SHIPTO_POSTAL_CITY
AN, 40
Shipping city o o o o x x
ECOM_SHIPTO_POSTAL_COUNTRYCODE
AN, 2
Shipping country code o o o o x x
ECOM_SHIPTO_COUNTY
AN, 25
Delivery county o o o o x x
ECOM_SHIPTO_POSTAL_NAME_FIRST
AN, 35 First name of the shipped customer o o o o x x
ECOM_SHIPTO_POSTAL_NAME_LAST
AN, 35
Last name of the shipped customer
o o o o x x
ECOM_SHIPTO_POSTAL_NAME_PREFIX
AN, 10 Prefix of the shipped customer
o o o o x x
ECOM_SHIPTO_POSTAL_POSTALCODE
AN, 10 Shipment postal code o o o o x x
ECOM_SHIPTO_POSTAL_STATE AN, 2 Delivery state, ISO code o o o o x x
ECOM_SHIPTO_POSTAL_STREET_LINE1
AN, 35 Shipping address, first line o o o o x x
ECOM_SHIPTO_POSTAL_STREET_LINE2
AN, 35 Shipping address, second line o o o o x x
ECOM_SHIPTO_POSTAL_STREET_NUMBER
AN, 10 House number of shipping address o o o o x x
ECOM_SHIPTO_TELECOM_FAX_NUMBER
AN, 20 Fax number of shipping address o o o o x x
ECOM_SHIPTO_TELECOM_PHONE_NUMBER
AN, 20 Phone number of shipping address 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 Nexi Payengine account. Just log in and go to: Support > Integration & user manuals > Technical guides > Parameter Cookbook.

1.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 Nexi Payengine 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)

1.4 Example

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

<form id="form1" method="POST" action="https://secure.payengine.de/ncol/test/orderstandard.asp">
<!-- standard Nexi Payengine 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>

2. 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 the Nexi Payengine 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 Nexi Payengine DirectLink option activated in your Nexi Payengine account in order to use this feature. Please contact the Nexi Payengine Sales Team for more information about this product.

2.1.1 Data

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

2.1.2 Example

<form action="https://secure.payengine.de/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://secure.payengine.de/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.

2.2 Batch

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

Note: You must have the Nexi Payengine Batch option activated in your Nexi Payengine account in order to use this feature. Please contact the Nexi Payengine Sales Team for more information about this product.

2.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 /

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

3. 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 the ConCardis Sales Team (payengine-service@concardis.com) to have your Klarna campaigns updated on our system.

Domande frequenti

Il tempo di attivazione di un metodo di pagamento dipende dai seguenti fattori:
  • L’affiliazione richiede all'acquirente o alla banca una settimana circa. Ovviamente, se l'affiliazione è già attiva, l'attivazione richiede solo qualche giorno.
  • Alcuni metodi di pagamento richiedono controlli aggiuntivi prima di poter essere attivati, ad esempio in caso di 3-D Secure, richiesto direttamente a VISA o MasterCard (e non all'acquirente)

A volte capita che un numero di affiliazione venga disattivato da parte dell'acquirente. Consigliamo di contattare l'acquirente.