1. Home
2. Modalità di pagamento
3. Modalità di pagamento alternativi
4. Klarna

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.

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.

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.

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.

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.

2.1 DirectLink

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:

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

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

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

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

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

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

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.