Maintenance Work Notice!

We will carry out maintenance work on this documentation on Tuesday, 15.06.2021 between 3 pm and 4 pm CEST. Thank you for your understanding.

Page tree

Search

Skip to end of metadata
Go to start of metadata


About Klarna Payments

General information about Klarna Payments

Klarna offers three different payment methods within the new Klarna KP API via Computop: Invoice and hire purchase (Pay Later & Pay over time) as well as Sofort + secured direct debit (Pay Now). Merchants pass on all the invoice data during the order to the service provider, who then takes over the complete billing and debtor management. That than takes over the complete billing and downstream debtor management. As merchant you get a payment guarantee; no matter what payment method the customer chooses. Thereby your customers get financial flexibility with Klarna, as they can choose themselves between invoice purchase and hire purchase. In the case of purchase by instalment merchants can also specify the instalment amounts and dates of repayment. Merchants can use the billing solution also for their B2B commerce.

Rate payment at the online shop motivates your customers to order high value baskets. This also increases your turnover. Klarna guarantees online consents in seconds for purchases by instalment during the order process. A PostIdent-process is not necessary. Klarna transfers the invoice amount to the merchant and bears the non-payment risk themselves. As merchant you benefit from rapidly available liquidity.

All three payment methods with restrictions of secured direct debit are available in the following countries with their respective domestic currency: Danmark (DKK), Germany (EUR), Finland (EUR), United Kingdom (GBP), Netherlands (EUR), Norway (NOK), Austria (EUR), Sweden (SEK) and USA (USD).


Logo

Info

Paygate can handle purchase on account and financing from Klarna. Merchants benefit from a payment guarantee and short payment due dates.

As third possibility Klarna integrated the payment with Sofort transfer and secured direct debit.

TypeMixed payment methods EN


Further information can be found on Klarna's website (https://www.klarna.de).

Klarna Payments distinguishes between direct connection and the Klarna Hosted Payment Page (HPP).


Process flow chart direct connection


Process flow Klarna Payments direct connection

Process flow chart HPP

Process flow Klarna Payments direct connection


With direct connection a separate JavaScript widget is included for each payment method. With the HPP a complete checkout page will be displayed where all or some selected payment methods are displayed. Widgets as well as the HPP are loaded from a Klarna server.



Paygate interface

Definitions

Data formats

Format

Description

a

alphabetical

as

alphabetical with special characters

n

numeric

an

alphanumeric

ans

alphanumeric with special characters

ns

numeric with special characters

bool

boolean expression (true or false)

3

fixed length with 3 digits/characters

..3

variable length with maximum 3 digits/characters

enum

enumeration of allowed values

dttm

ISODateTime (YYYY-MM-DDThh:mm:ss)


Abbreviations

Abbreviation

Description

Comment

CND

condition


M

mandatory

If a parameter is mandatory, then it must be present

O

optional

If a parameter is optional, then it can be present, but it is not required

C

conditional

If a parameter is conditional, then there is a conditional rule which specifies whether it is mandatory or optional


Notice: Please note that the names of parameters can be returned in upper or lower case.


Create Klarna session for direct connection

Before Klarna widgets can be loaded a Klarna session must be created which returns an AccessToken. This AccessToken has to be used for loading the widgets. In order to start a Klarna session via server-to-server communication, please go to the following URL:


Notice: For security reasons, Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter

Format

CND

Description

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

TransID

ans..64

M

TransactionID which should be unique for each payment

RefNr

ans..30

O

Unique reference number

Amount

n..10

M

Total amount of the order in the smallest currency unit including taxes and all rebates (e.g. EUR Cent). The amount may not be negative.

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

TaxAmount

n..10

M

Gross amount of value added tax in the smallest currency unit (e.g. EUR Cent). The amount may not be negative.

Notice: The VAT included is calculated for 19% with the formula =gross prices / 1.19 * 0.19.

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Currency

a3

M

Currency, three digits DIN / ISO 4217, permitted are: AUD, CHF, DKK, EUR, GBP, NOK, SEK, USD.

bdCountryCode

a2

M

Country code for the invoicing address, 2 characters according to ISO 3166-1. Allowed are Germany <DE>, Austria <AT>, Netherlands <NL>, Denmark <DK>, Sweden <SE>, Norway <NO>, Finland <FI>, Great Britain <GB>, USA <US>, Switzerland (CH), Australia (AU), Belgium <BE>, Spain (ES), Italy <IT> and Poland <PL>

bdFirstNameans..30CFirst name. Optional – if submitted, all parameters bdFirstName, bdLastName, bdEmail, bdStreet, bdZip, bdCity must be submitted.
bdLastNameans..30CLast name. Optional – if submitted, all parameters bdFirstName, bdLastName, bdEmail, bdStreet, bdZip, bdCity must be submitted.
bdEmailans..80CEmail address. Optional – if submitted, all parameters bdFirstName, bdLastName, bdEmail, bdStreet, bdZip, bdCity must be submitted.
bdCompanyans..200OCompany name
bdRegionans..40ORegion
bdTitleans..20OTitle of customer or contact person, e.g. Dr. or Prof.
bdStreeta..32CStreet and street number. Optional – if submitted, all parameters bdFirstName, bdLastName, bdEmail, bdStreet, bdZip, bdCity must be submitted.
bdZipn..5CPostal code. Optional – if submitted, all parameters bdFirstName, bdLastName, bdEmail, bdStreet, bdZip, bdCity must be submitted.
bdCitya..32CTown/city. Optional – if submitted, all parameters bdFirstName, bdLastName, bdEmail, bdStreet, bdZip, bdCity must be submitted.
bdAddressAdditionans..60OAdditional/supplementary address line
sdCountryCodea2OCountry code for the delivery address, 2 characters according to ISO 3166-1. Allowed are Germany <DE>, Austria <AT>, Netherlands <NL>, Denmark <DK>, Sweden <SE>, Norway <NO>, Finland <FI>, Great Britain <GB>, USA <US>, Switzerland (CH), Australia (AU), Belgium <BE>, Spain (ES), Italy <IT> and Poland <PL>
sdFirstNameans..30OFirst name
sdLastNameans..30OLast name
sdEmailans..80OEmail address
sdCompanyans..200OCompany name
sdRegionans..40ORegion
sdTitleans..20OTitle of customer or contact person, e.g. Dr. or Prof.
sdStreeta..32OStreet and street number
sdZipn..5OPostal code
sdCitya..32OTown/city
sdAddressAdditionans..60OAdditional/supplementary address line
Languagea2MLanguage for displaying the widgets: DE - German, DK - Danish, FI - Finnish, SE - Swedish, NO - Norwegian, NL - Dutsch, FR - French, IT - Italian, EN - English, ES - Spanish, CA - Catalan, PL - Polish

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

IPAddr

ans..15

O

IP address of the client in the format IPv4 or IPv6

Account

ans..12

M

With Computop it is possible to store details for several Klarna merchant accounts (username and password). Account allows you to control which account data to use.

The value of this parameter must be agreed with Computop support.

ArticleList

ans..2048

M

Complete article list of the order. This parameter must be created in JSON format.


The individual parameters in JSON format are following:

name = Product name (mandatory)

quantity = item quantity. The value may not be negative. (mandatory)

unit_price = unit price inclusive taxes but without rebates. (mandatory)

total_amount = total amount of iarticles inclusive taxes and rebates. (mandatory)

image_url = URL for an image that can be embedded later in agreement with Klarna. (max. 1024 characters)

merchant_data = "pass-through parameter" (max. 255 characters). Merchant must agree with Klarna what will be transmitted here.

product_identifiers.brand = product brand

product_identifiers.category_path = path of product category. As separator '>' has to be used.

product_identifiers.global_trade_item_number = article number (e.g. EAN, ISBN or UPC).

product_identifiers.manufacturer_part_number = manufacturer’s number

product_url = URL to product image

quantity_unit = unit of quantity (e.g. kg)

reference = article number (e.g. SKU)

tax_rate = tax rate as percentage (e.g. 25%). The percent sign must be replaced with two zeros, thus for example 2500. The value may not be negative.

total_discount_amount = total amount of rebate. The value may not be negative.

total_tax_amount = total amount of taxes. The value may be negative, if type is 'discount'.

type = type of item position. Possible entries are <physical>, <discount>, <shipping_fee>, <sales_tax>, <digital>, <gift_card>, <store_credit>, <surcharge>

Example:
{
	"order_lines": [
		{
			"image_url": "https://www.exampleobjects.com/logo.png",
			"merchant_data": "",
			"name": "Battery Power Pack",
			"product_identifiers": {
				"brand": "Intel",
				"category_path": "Electronics Store > Computers & Tablets > Desktops",
				"global_trade_item-number": "735858293167",
				"manufacturer_part_number": "BOXNUC5CPYH"
			},
			"product_url": "https://www.estore.com/products/f2a8d7e34",
			"quantity": 1,
			"quantity_unit": "kg",
			"reference": "19-402-USA",
			"tax_rate": 0,
			"total_amount": 1000,
			"total_discount_amount": 0,
			"total_tax_amount": 0,
			"type": "physical",
			"unit_price": 1000
		}
	]
}

Afterwards the article list created in JSON format must be Base64 encoded.

EnhancedData

ans..2048

O

Additional customer and order information for Klarna risk management. Merchant must agree with Klarna which data will be transmitted here. This parameter must be created in JSON format.

Example:
{
	"marketplace_seller_info": [
		{
			"product_category": "Women's Fashion",
			"product_name": "Women Sweatshirt"
		}
	]
}

Afterwards the additional information created in JSON format must be Base64 encoded.

Layout

ans..2048

O

Layout parameters for Klarna widgets. This parameter must be created in JSON format.

Example:
{
	"options": {
		"color_border": "#FF9900",
		"color_border_selected": "#FF9900",
		"color_button": "#FF9900",
		"color_button_text": "#FF9900",
		"color_checkbox": "#FF9900",
		"color_checkbox_checkmark": "#FF9900",
		"color_details": "#FF9900",
		"color_header": "#FF9900",
		"color_link": "#FF9900",
		"color_text": "#FF9900",
		"color_text_secondary": "#FF9900",
		"radius_border": "5px"
	}
}

Afterwards the layout parameters created in JSON format must be Base64 encoded.

URLConfirm

ans..256

M

Final URL for order confirmation to which Klarna forwards the customer after the order is successfully created within the Klarna system

URLNotify

ans..256

O

Complete URL which Paygate calls up in order to notify the shop about the payment result, if a PENDING transaction was finalized. The URL may be called up only via port 443 It may not contain parameters: Use the UserData parameter instead.

Processing of PENDING transactions must be activated at Computop as well as Klarna. URLNotify can also be stored with Computop.

PayType

as..32

M

Customer selected Klarna payment method. Possible entries are Pay immediately (pay_now, direct_debit or direct_bank_transfer), Pay later (pay_later) or Pay in installments (pay_over_time).

Personal details of customer

DateOfBirth

dttm

O

Date of birth in the format YYYY-MM-DD

Gender

a..15

O

Gender <female> for female, <male> for male

Title

a..12

O

Salutation

SocialSecurityNumber

a..5

O

Private individuals: The last four or five digits of the social security number. Not in DE, AT and NL. Obligatory field in SE, FI, DK with 4-digit value (NNNN). Obligatory field in NO with 5-digit value (NNNNN).

PersonID

ans..15

O

National identity number. Is necessary for example for a visa to entry the USA. For that purpose the serial number on the upper right side of the iodentity card may be used.

LegalForm

ans..50

O

Type of company. Following values are possible:

  • LIMITED_COMPANY
  • PUBLIC_LIMITED_COMPANY
  • ENTREPRENEURIAL_COMPANY
  • LIMITED_PARTNERSHIP_LIMITED_COMPANY
  • LIMITED_PARTNERSHIP
  • GENERAL_PARTNERSHIP
  • REGISTERED_SOLE_TRADER
  • SOLE_TRADER
  • CIVIL_LAW_PARTNERSHIP
  • PUBLIC_INSTITUTION
  • OTHER

CompanyID

ans..15

O

For companies: Register of Companies number

CompanyOrPerson

a2

O

Indication whether it is e company or a person.

<C> for companies, <P> for persons

Please note that Klarna does not allow B2B transactions by default. Please contact Klarna if you also want to use the payment method for B2B transactions.

VatID

ans..15

O

VAT identification number

Parameters for creating a session with Klarna Payments


 The following table describes the result parameters with which the Paygate responds to your system:

Parameter

Format

CND

Description

MID

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files.

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

Merchant’s transaction number

RefNr

ans..30

O

Unique reference number

Status

a..50

M

AUTHORIZE_REQUEST or FAILED

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

n8

M

Error code according to Paygate Response Codes (A4 Error codes)

CodeExt

ans..50

O

Error code from Klarna, if agreed with Computop support

ErrorText

ans..1024

O

Error text from Klarna, if agreed with Computop support

AccessToken

ans..2048

O

Client token from Klarna. In order to be able to subsequently show the Klarna widgets, the Klarna JavaScript-API must be initialized with this token.

PayType

enum

O

Customer selected Klarna payment method. Possible entries are Pay immediately (pay_now, direct_debit and direct_bank_transfer), Pay later (pay_later) and Pay in installments (pay_over_time). The returned value determines which widgets are allowed to be loaded.

Response parameters for creating a session with Klarna Payments



Show Klarna widgets

Klarna uses widgets in order to show customers the possible payment methods. The available payment methods for selecting depend on the previously selected category (see Create Klarna Session, PayType). The widget integration is done with the AccessToken (see Create Klarna Session, AccessToken) and the Klarna JavaScript SDK. How to integrate and initialise the Klarna JavaScript SDK and how to load the widgets is described on Klarna webpage:

After successful authorisation you wil get an authorisation token (TokenExt) which has to be used for creating an order.


Create Klarna session for the HPP

In order to process a payment via Klarna HPP, please use the following URL:


Notice: For security reasons, Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter

Format

CND

Description

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

TransID

ans..64

M

TransactionID which should be unique for each payment

RefNr

ans..30

O

Unique reference number

Amount

n..10

M

Total amount of the order in the smallest currency unit including taxes and all rebates (e.g. EUR Cent). The amount may not be negative.

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

TaxAmount

n..10

M

Gross amount of value added tax in the smallest currency unit (e.g. EUR Cent). The amount may not be negative.

Notice: The VAT included is calculated for 19% with the formula =gross prices / 1.19 * 0.19.

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Currency

a3

M

Currency, three digits DIN / ISO 4217, permitted are: AUD, CHF, DKK, EUR, GBP, NOK, SEK, USD.

bdCountryCode

a2

M

Country code for the invoicing address, 2 characters according to ISO 3166-1. Allowed are Germany <DE>, Austria <AT>, Netherlands <NL>, Denmark <DK>, Sweden <SE>, Norway <NO>, Finland <FI>, Great Britain <GB>, USA <US>, Switzerland (CH), Australia (AU), Belgium <BE>, Spain (ES), Italy <IT> and Poland <PL>

bdFirstNameans..30MFirst name
bdLastNameans..30MLast name
bdEmailans..80MEmail address
bdCompanyans..200OCompany name
bdRegionans..40ORegion
bdTitleans..20OTitle of customer or contact person, e.g. Dr. or Prof.
bdStreeta..32MStreet and street number
bdZipn..5MPostal code
bdCitya..32MTown/city
bdAddressAdditionans..60OAdditional/supplementary address line

sdCountryCode

a2

O

Country code for the delivery address, 2 characters according to ISO 3166-1. Allowed are Germany <DE>, Austria <AT>, Netherlands <NL>, Denmark <DK>, Sweden <SE>, Norway <NO>, Finland <FI>, Great Britain <GB>, USA <US>, Switzerland (CH), Australia (AU), Belgium <BE>, Spain (ES), Italy <IT> and Poland <PL>

sdFirstName

ans..30

C

First name. Optional – if submitted, all parameters sdFirstName, sdLastName, sdEmail, sdStreet, sdZip, sdCity must be submitted.

sdLastName

ans..30

C

Last name. Optional – if submitted, all parameters sdFirstName, sdLastName, sdEmail, sdStreet, sdZip, sdCity must be submitted.

sdEmail

ans..80

C

E-mail address. Optional – if submitted, all parameters sdFirstName, sdLastName, sdEmail, sdStreet, sdZip, sdCity must be submitted.

sdCompanyans..200OCompany name
sdRegionans..40ORegion
sdTitleans..20OTitle of customer or contact person, e.g. Dr. or Prof.

sdStreet

a..32

C

Street name and street number. Optional – if submitted, all parameters sdFirstName, sdLastName, sdEmail, sdStreet, sdZip, sdCity must be submitted.

sdZip

n..5

C

Postcode. Optional – if submitted, all parameters sdFirstName, sdLastName, sdEmail, sdStreet, sdZip, sdCity must be submitted.

sdCity

a..32

C

City. Optional – if submitted, all parameters sdFirstName, sdLastName, sdEmail, sdStreet, sdZip, sdCity must be submitted.

sdAddressAdditionans..60OAdditional/supplementary address line
Languagea2MLanguage for displaying the HPP: DE - German, DK - Danish, FI - Finnish, SE - Swedish, NO - Norwegian, NL - Dutsch, FR - French, IT - Italian, EN - English, ES - Spanish, CA - Catalan, PL - Polish

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

IPAddr

ans..15

O

IP address of the client in the format IPv4 or IPv6

Account

ans..12

M

With Computop it is possible to store details for several Klarna merchant accounts (username and password). Account allows you to control which account data to use.

The value of this parameter must be agreed with Computop support.

ArticleList

ans..2048

M

Complete article list of the order. This parameter must be created in JSON format.


The individual parameters in JSON format are following:

name = Product name (mandatory)

quantity = item quantity. The value may not be negative. (mandatory)

unit_price = unit price inclusive taxes but without rebates. (mandatory)

total_amount = total amount of iarticles inclusive taxes and rebates. (mandatory)

image_url = URL for an image that can be embedded later in agreement with Klarna. (max. 1024 characters)

merchant_data = "pass-through parameter" (max. 255 characters). Merchant must agree with Klarna what will be transmitted here.

product_identifiers.brand = product brand

product_identifiers.category_path = path of product category. As separator '>' has to be used.

product_identifiers.global_trade_item_number = article number (e.g. EAN, ISBN or UPC).

product_identifiers.manufacturer_part_number = manufacturer’s number

product_url = URL to product image

quantity_unit = unit of quantity (e.g. kg)

reference = article number (e.g. SKU)

tax_rate = tax rate as percentage (e.g. 25%). The percent sign muss be replaced with two zeros, thus for example 2500. The value may not be negative.

total_discount_amount = total amount of rebate. The value may not be negative.

total_tax_amount = total amount of taxes. The value may be negative, if type is 'discount'.

type = type of item position. Possible entries are <physical>, <discount>, <shipping_fee>, <sales_tax>, <digital>, <gift_card>, <store_credit>, <surcharge>

Example:
{
	"order_lines": [
		{
			"image_url": "https://www.exampleobjects.com/logo.png",
			"merchant_data": "",
			"name": "Battery Power Pack",
			"product_identifiers": {
				"brand": "Intel",
				"category_path": "Electronics Store > Computers & Tablets > Desktops",
				"global_trade_item-number": "735858293167",
				"manufacturer_part_number": "BOXNUC5CPYH"
			},
			"product_url": "https://www.estore.com/products/f2a8d7e34",
			"quantity": 1,
			"quantity_unit": "kg",
			"reference": "19-402-USA",
			"tax_rate": 0,
			"total_amount": 1000,
			"total_discount_amount": 0,
			"total_tax_amount": 0,
			"type": "physical",
			"unit_price": 1000
		}
	]
}

Afterwards the article list created in JSON format must be Base64 encoded.

EnhancedData

ans..2048

O

Additional customer and order information for Klarna risk management. Merchant must agree with Klarna which data will be transmitted here. This parameter must be created in JSON format.

Example:
{
	"marketplace_seller_info": [
		{
			"product_category": "Women's Fashion",
			"product_name": "Women Sweatshirt"
		}
	]
}

Afterwards the additional information created in JSON format must be Base64 encoded.

Layout

ans..2048

O

Layout parameters for the HPP. This parameter must be created in JSON format.

  • show_subtotal_detail = HIDE (hides article positions)
  • logo_url (controls the logo to be displayed)
  • page_title (controls the title to be displayed)
  • purchase_type (controls the appearance of PURCHASE button)
Example:
{
	"options": {
		"logo_url": "https://acme.com/assets/logo_small.jpg",
		"show_subtotal_detail": "HIDE",
		"page_title": "Page Title"
	}
}

Afterwards the layout parameters created in JSON format must be Base64 encoded.

URLConfirm

ans..256

M

Final URL for order confirmation to which Klarna forwards the customer after the order is successfully created within the Klarna system

Order

ans..6

O

Activates the automatic order creation. If this parameter is used an explicit order creation is not necessary. If a BillingAgreementID for recurring payments should be created, also the parameter RTF must be submitted. Only possible value: AUTO

URLSuccessans..256MComplete URL which calls up Paygate if payment has been successful. The URL may be called up only via port 443 This URL may not contain parameters: In order to exchange values between Paygate and shop, please use the parameter UserData.
URLFailureans..256MComplete URL which calls up Paygate if payment has been unsuccessful. The URL may be called up only via port 443 This URL may not contain parameters: In order to exchange values between Paygate and shop, please use the parameter UserData.
Responsea7OStatus response sent by Paygate to URLSuccess and URLFailure, should be encrypted. For this purpose, transmit Response=encrypt parameter.

URLNotify

ans..256

O

Complete URL which Paygate calls up in order to notify the shop when a PENDING transaction was finalised. The URL may be called up only via port 443 It may not contain parameters: Use the UserData parameter instead.

Processing of PENDING transactions must be activated at Computop as well as Klarna. URLNotify can also be stored with Computop.

Personal details of customer

DateOfBirth

dttm

O

Date of birth in the format YYYY-MM-DD

Gender

a..15

O

Gender <female> for female, <male> for male

Title

a..12

O

Salutation

SocialSecurityNumber

a..5

O

Private individuals: The last four or five digits of the social security number. Not in DE, AT and NL. Obligatory field in SE, FI, DK with 4-digit value (NNNN). Obligatory field in NO with 5-digit value (NNNNN).

PersonID

ans..15

O

National identity number. Is necessary for example for a visa to entry the USA. For that purpose the serial number on the upper right side of the iodentity card may be used.

LegalForm

ans..50

O

Type of company. Following values are possible:

  • LIMITED_COMPANY
  • PUBLIC_LIMITED_COMPANY
  • ENTREPRENEURIAL_COMPANY
  • LIMITED_PARTNERSHIP_LIMITED_COMPANY
  • LIMITED_PARTNERSHIP
  • GENERAL_PARTNERSHIP
  • REGISTERED_SOLE_TRADER
  • SOLE_TRADER
  • CIVIL_LAW_PARTNERSHIP
  • PUBLIC_INSTITUTION
  • OTHER

CompanyID

ans..15

O

For companies: Register of Companies number

CompanyOrPerson

a2

O

Indication whether it is e company or a person.

<C> for companies, <P> for persons

Please note that Klarna does not allow B2B transactions by default. Please contact Klarna if you also want to use the payment method for B2B transactions.

VatID

ans..15

O

VAT identification number

Parameters for calling the Klarna HPP

The following table describes the result parameters that the Paygate transmits to your URLSuccess, URLFailure or URLNotify. If you have specified the Response=encrypt parameter, the following parameters are forwarded Blowfish encrypted to your system:

Parameter

Format

CND

Description

MID

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

Merchant’s transaction number

RefNr

ans..30

O

Unique reference number

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

Status

a..50

M

OK or FAILED

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

n8

M

Error code according to Paygate Response Codes (A4 Error codes)

CodeExt

ans..50

O

Error code from Klarna, if agreed with Computop support

ErrorText

ans..1024

O

Error text from Klarna, if agreed with Computop support

TokenExt

ans..36

M

Authorisation token which is needed for creating an order

Result parameters for URLNotify, URLSuccess and URLFailure


Create order with Klarna

In order to create the order within Klarna system via a server-to-server connection, please use the following URL:

If this is an initial order if a recurring order (RTF=I), then only the billing address can be submitted, not the delivery adress.

If the address data differs from the address data transferred from the JavaScript widget during authorization, the order will be rejected.

Notice: For security reasons, Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter

Format

CND

Description

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

PayID

an32

M

ID assigned by Paygate for the payment as reference for the previous initiation

TransID

ans..64

M

TransactionID which should be unique for each payment

RefNr

ans..30

O

Unique reference number

Amount

n..10

M

Total amount of the order in the smallest currency unit including taxes and all rebates (e.g. EUR Cent). The amount may not be negative.

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

TaxAmountn..10M

Gross amount of value added tax in the smallest currency unit (e.g. EUR Cent). The amount may not be negative.

Notice: The VAT included is calculated for 19% with the formula =gross prices / 1.19 * 0.19.

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Currency

a3

M

Currency, three digits DIN / ISO 4217, permitted are: AUD, CHF, DKK, EUR, GBP, NOK, SEK, USD.

TokenExt

ans..36

M

Authorisation token which is returned from Klarna within JavaScript Authorize-Call. Please note, the authorization token from the previous step is valid for 60 minutes. If you attempt to place an order with this after that time has passed, it will be rejected by Klarna.

EventToken

enum

M

Defines which Klarna API-Call request will be initiated.

For creating a Klarna order the value CNO must be transferred.

RTF

a1

O

For repeat payments (subscriptions): I = Initial payment of a new subscription, R = Routine payment (Recurring).

If this is an initial payment of a subscription the value I must be transferred.

RequestReason

a..20

O

Intended usage of „Consumer Token“.

Possible value is SUBSCRIPTION.

Note

ans..50

O

Description for the purpose of token (e.g. Abo)

ArticleListans..2048M

Complete article list of the order. This parameter must be created in JSON format.


The individual parameters in JSON format are following:

name = Product name (mandatory)

quantity = item quantity. The value may not be negative. (mandatory)

unit_price = unit price inclusive taxes but without rebates. (mandatory)

total_amount = total amount of iarticles inclusive taxes and rebates. (mandatory)

image_url = URL for an image that can be embedded later in agreement with Klarna. (max. 1024 characters)

merchant_data = "pass-through parameter" (max. 255 characters). Merchant must agree with Klarna what will be transmitted here.

product_identifiers.brand = product brand

product_identifiers.category_path = path of product category. As separator '>' has to be used.

product_identifiers.global_trade_item_number = article number (e.g. EAN, ISBN or UPC).

product_identifiers.manufacturer_part_number = manufacturer’s number

product_url = URL to product image

quantity_unit = unit of quantity (e.g. kg)

reference = article number (e.g. SKU)

tax_rate = tax rate as percentage (e.g. 25%). The percent sign muss be replaced with two zeros, thus for example 2500. The value may not be negative.

total_discount_amount = total amount of rebate. The value may not be negative.

total_tax_amount = total amount of taxes. The value may be negative, if type is 'discount'.

type = type of item position. Possible entries are <physical>, <discount>, <shipping_fee>, <sales_tax>, <digital>, <gift_card>, <store_credit>, <surcharge>

Example:
{
	"order_lines": [
		{
			"image_url": "https://www.exampleobjects.com/logo.png",
			"merchant_data": "",
			"name": "Battery Power Pack",
			"product_identifiers": {
				"brand": "Intel",
				"category_path": "Electronics Store > Computers & Tablets > Desktops",
				"global_trade_item-number": "735858293167",
				"manufacturer_part_number": "BOXNUC5CPYH"
			},
			"product_url": "https://www.estore.com/products/f2a8d7e34",
			"quantity": 1,
			"quantity_unit": "kg",
			"reference": "19-402-USA",
			"tax_rate": 0,
			"total_amount": 1000,
			"total_discount_amount": 0,
			"total_tax_amount": 0,
			"type": "physical",
			"unit_price": 1000
		}
	]
}

Afterwards the article list created in JSON format must be Base64 encoded.

bdCountryCodea2MCountry code for the invoicing address, 2 characters according to ISO 3166-1. Allowed are Germany <DE>, Austria <AT>, Netherlands <NL>, Denmark <DK>, Sweden <SE>, Norway <NO>, Finland <FI>, Great Britain <GB>, USA <US>, Switzerland (CH), Australia (AU), Belgium <BE>, Spain (ES), Italy <IT> and Poland <PL>
bdFirstNameans..30CFirst name. Optional – if submitted, all parameters bdFirstName, bdLastName, bdEmail, bdStreet, bdZip, bdCity must be submitted.
bdLastNameans..30CLast name. Optional – if submitted, all parameters bdFirstName, bdLastName, bdEmail, bdStreet, bdZip, bdCity must be submitted.
bdEmailans..80CEmail address. Optional – if submitted, all parameters bdFirstName, bdLastName, bdEmail, bdStreet, bdZip, bdCity must be submitted.
bdCompanyans..200OCompany name
bdRegionans..40ORegion
bdTitleans..20OTitle of customer or contact person, e.g. Dr. or Prof.
bdStreeta..32CStreet name and street number. Optional – if submitted, all parameters bdFirstName, bdLastName, bdEmail, bdStreet, bdZip, bdCity must be submitted.
bdZipn..5CPostcode. Optional – if submitted, all parameters bdFirstName, bdLastName, bdEmail, bdStreet, bdZip, bdCity must be submitted.
bdCitya..32CCity. Optional – if submitted, all parameters bdFirstName, bdLastName, bdEmail, bdStreet, bdZip, bdCity must be submitted.
bdAddressAdditionans..60OAdditional/supplementary address line
sdCountryCodea2OCountry code for the delivery address, 2 characters according to ISO 3166-1. Allowed are Germany <DE>, Austria <AT>, Netherlands <NL>, Denmark <DK>, Sweden <SE>, Norway <NO>, Finland <FI>, Great Britain <GB>, USA <US>, Switzerland (CH), Australia (AU), Belgium <BE>, Spain (ES), Italy <IT> and Poland <PL>
sdFirstNameans..30CFirst name. Optional – if submitted, all parameters sdFirstName, sdLastName, sdEmail, sdStreet, sdZip, sdCity must be submitted.
sdLastNameans..30CLast name. Optional – if submitted, all parameters sdFirstName, sdLastName, sdEmail, sdStreet, sdZip, sdCity must be submitted.
sdEmailans..80CEmail address. Optional – if submitted, all parameters sdFirstName, sdLastName, sdEmail, sdStreet, sdZip, sdCity must be submitted.
sdCompanyans..200OCompany name
sdRegionans..40ORegion
sdTitleans..20OTitle of customer or contact person, e.g. Dr. or Prof.
sdStreeta..32CStreet name and street number. Optional – if submitted, all parameters sdFirstName, sdLastName, sdEmail, sdStreet, sdZip, sdCity must be submitted.
sdZipn..5CPostcode. Optional – if submitted, all parameters sdFirstName, sdLastName, sdEmail, sdStreet, sdZip, sdCity must be submitted.
sdCitya..32CCity. Optional – if submitted, all parameters sdFirstName, sdLastName, sdEmail, sdStreet, sdZip, sdCity must be submitted.
sdAddressAdditionans..60OAdditional/supplementary address line

Parameters for creating an order with Klarna

 

The following table describes the result parameters with which the Paygate responds to your system:

Parameter

Format

CND

Description

MID

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files.

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

Merchant’s transaction number

RefNr

ns..30

M

Unique reference number

Status

a..50

M

OK or FAILED

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

n8

M

Error code according to Paygate Response Codes (A4 Error codes)

TransactionID

an12

O

Reference number from Klarna system

BillingAgreementID

ans..50

O

Token-ID (Consumer Token) from Klarna which must be additionally transferred for recurring payments. The value is returned only if request was made with RTF=I.

RedirectURL

ans..256

O

The customer must be forwarded to this URL so that Klarna can place a Cookie. The customer remains unaware of this process.

CodeExt

ans..50

O

Error code from Klarna, if agreed with Computop support

ErrorText

ans..1024

O

Error text from Klarna, if agreed with Computop support

Response parameters for creating an order with Klarna



Create recurring order (Abo) with Klarna

In order to create a recurring order (e.g. Abo) with Klarna, please use the following URL:


Notice: For security reasons, Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter

Format

CND

Description

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

TransID

ans..64

M

TransactionID which should be unique for each payment

RefNr

ans..30

O

Unique reference number

Amount

n..10

M

Total amount of the order in the smallest currency unit including taxes and all rebates (e.g. EUR Cent). The amount may not be negative.

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

TaxAmount

n..10

M

Gross amount of value added tax in the smallest currency unit (e.g. EUR Cent). The amount may not be negative.

Notice: The VAT included is calculated for 19% with the formula =gross prices / 1.19 * 0.19.

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Currency

a3

M

Currency, three characters DIN / ISO 4217, permitted are: AUD, CHF, DKK, EUR, GBP, NOK, SEK, USD.

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

EventToken

enum

M

Defines which Klarna API-Call request will be initiated.

For creating a Klarna order the value CNO must be transferred.

BillingAgreementID

ans..50

M

Token-ID (Consumer Token) from Klarna which must be additionally transferred for recurring payments.

RTF

a1

M

For repeat payments (subscriptions): I = Initial payment of a new subscription, R = Routine payment (Recurring).

For this request the value R must be transferred.

Account

ans..12

M

With Computop it is possible to store details for several Klarna accounts (username and password). Account allows you to control which account data to use.

The value of this parameter must be agreed with Computop support.

ArticleList

ans..2048

M

Complete article list of the order. This parameter must be created in JSON format.


The individual parameters in JSON format are following:

name = Product name (mandatory)

quantity = item quantity. The value may not be negative. (mandatory)

unit_price = unit price inclusive taxes but without rebates. (mandatory)

total_amount = total amount of iarticles inclusive taxes and rebates. (mandatory)

image_url = URL for an image that can be embedded later in agreement with Klarna. (max. 1024 characters)

merchant_data = "pass-through parameter" (max. 255 characters). Merchant must agree with Klarna what will be transmitted here.

product_identifiers.brand = product brand

product_identifiers.category_path = path of product category. As separator '>' has to be used.

product_identifiers.global_trade_item_number = article number (e.g. EAN, ISBN or UPC).

product_identifiers.manufacturer_part_number = manufacturer’s number

product_url = URL to product image

quantity_unit = unit of quantity (e.g. kg)

reference = article number (e.g. SKU)

tax_rate = tax rate as percentage (e.g. 25%). The percent sign muss be replaced with two zeros, thus for example 2500. The value may not be negative.

total_discount_amount = total amount of rebate. The value may not be negative.

total_tax_amount = total amount of taxes. The value may be negative, if type is 'discount'.

type = type of item position. Possible entries are <physical>, <discount>, <shipping_fee>, <sales_tax>, <digital>, <gift_card>, <store_credit>, <surcharge>

Example:
{
	"order_lines": [
		{
			"image_url": "https://www.exampleobjects.com/logo.png",
			"merchant_data": "",
			"name": "Battery Power Pack",
			"product_identifiers": {
				"brand": "Intel",
				"category_path": "Electronics Store > Computers & Tablets > Desktops",
				"global_trade_item-number": "735858293167",
				"manufacturer_part_number": "BOXNUC5CPYH"
			},
			"product_url": "https://www.estore.com/products/f2a8d7e34",
			"quantity": 1,
			"quantity_unit": "kg",
			"reference": "19-402-USA",
			"tax_rate": 0,
			"total_amount": 1000,
			"total_discount_amount": 0,
			"total_tax_amount": 0,
			"type": "physical",
			"unit_price": 1000
		}
	]
}

Afterwards the article list created in JSON format must be Base64 encoded.

Parameters for a recurring order (Abo) with Klarna Payments


The following table describes the result parameters with which the Paygate responds to your system:

Parameter

Format

CND

Description

MID

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files.

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

Merchant’s transaction number

RefNr

ans..30

O

Unique reference number

Status

a..50

M

OK or FAILED

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

n8

M

Error code according to Paygate Response Codes (A4 Error codes)

TransactionID

an12

O

Reference number from Klarna system

CodeExt

ans..50

O

Error code from Klarna, if agreed with Computop support

ErrorText

ans..1024

O

Error text from Klarna, if agreed with Computop support

Response parameters for a recurring order (Abo) with Klarna Payments



Modify invoice and delivery address

Invoice and delivery information was transferred within Klarna widget. As long as no capture is made invoice and/or delivery address can be modified subsequently. For this purpose please use the following URL:


Notice: For security reasons, Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter

Format

CND

Description

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files.

EventToken

enum

M

Defines which Klarna API-Call request will be initiated.

For updating invoice and/or delivery address the value UCA must be transferred.

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

Invoicing address

bdTitle

a..12

O

Salutation

bdFirstName

ans..30

O

First name

bdLastName

ans..30

O

Last name

bdCompany

ans..50

O

Company

bdStreet

a..32

O

Street name and street number

bdAddressAddition

ans..50

O

Address line 2

bdZip

n..5

O

Postcode

bdCity

a..32

O

City

bdRegion

a..32

O

Region

bdCountryCode

a2

O

Country code for the invoicing address, 2 characters according to ISO 3166-1. Allowed are Germany <DE>, Austria <AT>, Netherlands <NL>, Denmark <DK>, Sweden <SE>, Norway <NO>, Finland <FI>, Great Britain <GB>, USA <US>, Switzerland (CH), Australia (AU), Belgium <BE>, Spain (ES), Italy <IT> and Poland <PL>

bdEmail

ans..80

O

E-mail address

bdPhone

n..20

O

Phone number or mobile phone number

Delivery address

sdTitle

a..12

O

Salutation

sdFirstName

ans..30

O

First name

sdLastName

ans..30

O

Last name

sdCompany

ans..50

O

Company

sdStreet

a..32

O

Street name and street number

sdAddressAddition

ans..50

O

Address line 2

sdZip

n..5

O

Postcode

sdCity

a..32

O

City

sdRegion

a..32

O

Region

sdCountryCode

a2

O

Country code for the delivery address, 2 characters according to ISO 3166-1. Allowed are Germany <DE>, Austria <AT>, Netherlands <NL>, Denmark <DK>, Sweden <SE>, Norway <NO>, Finland <FI>, Great Britain <GB>, USA <US>, Switzerland (CH), Australia (AU), Belgium <BE>, Spain (ES), Italy <IT> and Poland <PL>

sdEmail

ans..80

O

E-mail address

sdPhone

n..20

O

Phone number or mobile phone number

Parameters for address modification with Klarna Payments


The following table describes the result parameters with which the Paygate responds to your system:

Parameter

Format

CND

Description

MID

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files.

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

Merchant’s transaction number

RefNr

ans..30

O

Unique reference number

Status

a..50

M

OK or FAILED

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

n8

M

Error code according to Paygate Response Codes (A4 Error codes)

CodeExt

ans..50

O

Error code from Klarna, if agreed with Computop support

ErrorText

ans..1024

O

Error text from Klarna, if agreed with Computop support

Response parameters for address modification with Klarna Payments



Modify unique reference number

As long as no capture is made the unique reference number which already was sent along within parameter RefNr for creating the Klarna session can be modified subsequently. For this purpose please use the following URL:


Notice: For security reasons, Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter

Format

CND

Description

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files.

EventToken

enum

M

Defines which Klarna API-Call request will be initiated.

For updating the unique reference number the value UMR must be transferred.

RefNr

ans..30

M

New unique reference number

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

Parameters for modification of reference number with Klarna Payments


The following table describes the result parameters with which the Paygate responds to your system:

Parameter

Format

CND

Description

MID

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files.

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

Merchant’s transaction number

RefNr

ans..30

O

Unique reference number

Status

a..50

M

OK or FAILED

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

n8

M

Error code according to Paygate Response Codes (A4 Error codes)

CodeExt

ans..50

O

Error code from Klarna, if agreed with Computop support

ErrorText

ans..1024

O

Error text from Klarna, if agreed with Computop support

Response parameters for modification of reference number with Klarna Payments



Modify order amount and article list

As long as no capture is made the order amount as well as the whole article list can be modified subsequently. For this purpose please use the following URL:


Notice: For security reasons, Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter

Format

CND

Description

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files.

TransID

ans..64

M

TransactionID which should be unique for each payment

RefNr

ans..30

O

Unique reference number

Amount

n..10

M

New total amount in the smallest currency unit (e.g. EUR Cent) The amount may not be negative.

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Notice: The new amount may not be higher than the amount transferred within the initial request.

Currency

a3

M

Currency, three characters DIN / ISO 4217, permitted are: AUD, CHF, DKK, EUR, GBP, NOK, SEK, USD.

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

EventToken

enum

M

Defines which Klarna API-Call request will be initiated.

For modifying of order amount and article list the value UEO must be transferred.

ArticleList

ans..2048

M

New article list of the order. This parameter must be created in JSON format.


The individual parameters in JSON format are following:

name = Product name (mandatory)

quantity = item quantity. The value may not be negative. (mandatory)

unit_price = unit price inclusive taxes but without rebates. (mandatory)

total_amount = total amount of iarticles inclusive taxes and rebates. (mandatory)

image_url = URL for an image that can be embedded later in agreement with Klarna. (max. 1024 characters)

merchant_data = "pass-through parameter" (max. 255 characters). Merchant must agree with Klarna what will be transmitted here.

product_identifiers.brand = product brand

product_identifiers.category_path = path of product category. As separator '>' has to be used.

product_identifiers.global_trade_item_number = article number (e.g. EAN, ISBN or UPC).

product_identifiers.manufacturer_part_number = manufacturer’s number

product_url = URL to product image

quantity_unit = unit of quantity (e.g. kg)

reference = article number (e.g. SKU)

tax_rate = tax rate as percentage (e.g. 25%). The percent sign muss be replaced with two zeros, thus for example 2500. The value may not be negative.

total_discount_amount = total amount of rebate. The value may not be negative.

total_tax_amount = total amount of taxes. The value may be negative, if type is 'discount'.

type = type of item position. Possible entries are <physical>, <discount>, <shipping_fee>, <sales_tax>, <digital>, <gift_card>, <store_credit>, <surcharge>

Example:
{
	"order_lines": [
		{
			"image_url": "https://www.exampleobjects.com/logo.png",
			"merchant_data": "",
			"name": "Battery Power Pack",
			"product_identifiers": {
				"brand": "Intel",
				"category_path": "Electronics Store > Computers & Tablets > Desktops",
				"global_trade_item-number": "735858293167",
				"manufacturer_part_number": "BOXNUC5CPYH"
			},
			"product_url": "https://www.estore.com/products/f2a8d7e34",
			"quantity": 1,
			"quantity_unit": "kg",
			"reference": "19-402-USA",
			"tax_rate": 0,
			"total_amount": 1000,
			"total_discount_amount": 0,
			"total_tax_amount": 0,
			"type": "physical",
			"unit_price": 1000
		}
	]
}

Afterwards the article list created in JSON format must be Base64 encoded.

Parameters for modifying order amount and article list with Klarna Payments


The following table describes the result parameters with which the Paygate responds to your system:

Parameter

Format

CND

Description

MID

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files.

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

Merchant’s transaction number

RefNr

ans..30

O

Unique reference number

Status

a..50

M

OK or FAILED

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

n8

M

Error code according to Paygate Response Codes (A4 Error codes)

CodeExt

ans..50

O

Error code from Klarna, if agreed with Computop support

ErrorText

ans..1024

O

Error text from Klarna, if agreed with Computop support

Response parameters for modification of order amount and article list with Klarna Payments



Capture

Captures are possible via a Server-to-Server connection. To carry out a complete or partial capture for Klarna Payments via a Server-to-Server connection please use the following URL:


Notice: For security reasons, Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter

Format

CND

Description

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

PayID

an32

M

ID assigned by Paygate for the payment to be captured

TransID

ans..64

M

ID assigned by Merchant for the payment process to be captured

Amount

n..10

M

Amount to be captured in the smallest currency unit including taxes and rebates (e.g. EUR Cent).

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Notice: It depends on the amount whether a full or partial capture is made.

Currency

a..3

M

Currency, three characters DIN / ISO 4217, permitted are: AUD, CHF, DKK, EUR, GBP, NOK, SEK, USD.

RefNr

ns..30

O

Unique reference number

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

ReqIDans..32OTo avoid double payments, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction is submitted again with the same ReqID, Paygate will not carry out the payment, but will just return the status of the original transaction. Please note that the Paygate must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly.

ShippingData

ans..2048

O

Delivery information (e.g. tracking data). This parameter must be created in JSON format.

Example:
{
	"shipping_info": [
		{
			"shipping_company": "DHL US",
			"shipping_method": "Home",
			"tracking_number": "63456415674545679074",
			"tracking_url": "http://shipping.example/findmypackage?63456415674545679074",
			"return_shipping_company": "DHL US",
			"return_tracking_number": "93456415674545679000",
			"return_tracking_url": "http://shipping.example/findmypackage?93456415674545679000"
		}
	]
}

Afterwards the delivery information created in JSON format must be Base64 encoded.

ArticleList

ans..2048

O

Complete article list of the order. This parameter must be created in JSON format.


The individual parameters in JSON format are following:

name = Product name (mandatory)

quantity = item quantity. The value may not be negative. (mandatory)

unit_price = unit price inclusive taxes but without rebates. (mandatory)

total_amount = total amount of iarticles inclusive taxes and rebates. (mandatory)

image_url = URL for an image that can be embedded later in agreement with Klarna. (max. 1024 characters)

merchant_data = "pass-through parameter" (max. 255 characters). Merchant must agree with Klarna what will be transmitted here.

product_identifiers.brand = product brand

product_identifiers.category_path = path of product category. As separator '>' has to be used.

product_identifiers.global_trade_item_number = article number (e.g. EAN, ISBN or UPC).

product_identifiers.manufacturer_part_number = manufacturer’s number

product_url = URL to product image

quantity_unit = unit of quantity (e.g. kg)

reference = article number (e.g. SKU)

tax_rate = tax rate as percentage (e.g. 25%). The percent sign muss be replaced with two zeros, thus for example 2500. The value may not be negative.

total_discount_amount = total amount of rebate. The value may not be negative.

total_tax_amount = total amount of taxes. The value may be negative, if type is 'discount'.

type = type of item position. Possible entries are <physical>, <discount>, <shipping_fee>, <sales_tax>, <digital>, <gift_card>, <store_credit>, <surcharge>

Example:
{
	"order_lines": [
		{
			"image_url": "https://www.exampleobjects.com/logo.png",
			"merchant_data": "",
			"name": "Battery Power Pack",
			"product_identifiers": {
				"brand": "Intel",
				"category_path": "Electronics Store > Computers & Tablets > Desktops",
				"global_trade_item-number": "735858293167",
				"manufacturer_part_number": "BOXNUC5CPYH"
			},
			"product_url": "https://www.estore.com/products/f2a8d7e34",
			"quantity": 1,
			"quantity_unit": "kg",
			"reference": "19-402-USA",
			"tax_rate": 0,
			"total_amount": 1000,
			"total_discount_amount": 0,
			"total_tax_amount": 0,
			"type": "physical",
			"unit_price": 1000
		}
	]
}

Afterwards the article list created in JSON format must be Base64 encoded.

CompleteType

a3

O

With this parameter during a partial capture it is possible to reverse the remaining amount simultaneously. Possible value <YES>. If the order was processed completely this parameter will cause an error, because a remaining amount of 0 cannot be reversed.

Parameters for captures with Klarna Payments


The following table describes the Paygate response parameters:

Parameter

Format

CND

Description

MID

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

Merchant’s transaction number

RefNr

ns..30

O

Unique reference number

Status

a..50

M

OK or FAILED

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

n8

M

Error code according to Paygate Response Codes (A4 Error codes)

InvoiceNr

ans..30

M

Invoice/booking number from Klarna. This number is needed for example for resending the E-Mail with payment and order information.

CodeExt

ans..50

O

Error code from Klarna, if agreed with Computop support

ErrorText

ans..1024

O

Error text from Klarna, if agreed with Computop support

Response parameters for captures with Klarna Payments



Resending an activated invoice

It may happen that a customer hasn’t received the E-Mail with payment and order information. This request is possible only if a capture was already made. For resending this E-Mail, please use the following URL:


Notice: For security reasons, Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter

Format

CND

Description

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

EventToken

enum

M

Defines which Klarna API-Call request will be initiated.

For resending the E-Mail the value RCC must be transferred.

InvoiceNr

ans..30

M

Invoice/booking number from Klarna which is returned for all captures within response parameter InvoiceNr

Parameters for resending an activated invoice with Klarna Payments


The following table describes the result parameters with which the Paygate responds to your system:

Parameter

Format

CND

Description

MID

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

Merchant’s transaction number

RefNr

ans..30

O

Unique reference number

Status

a..50

M

OK or FAILED

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

n8

M

Error code according to Paygate Response Codes (A4 Error codes)

CodeExt

ans..50

O

Error code from Klarna, if agreed with Computop support

ErrorText

ans..1024

O

Error text from Klarna, if agreed with Computop support

Response parameters for resending an activated invoice with Klarna Payments



Credit with reference and partial credit

Credits (refunds) are possible via a Server-to-Server connection. To carry out a partal or full credit with a reference transaction, please use the following URL:


Notice: For security reasons, Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter

Format

CND

Description

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

PayID

an32

M

ID assigned by Paygate for the payment to be credited

TransID

ans..64

M

ID assigned by Merchant for the payment process to be credited

Amount

n..10

M

Total amount to be credited in the smallest currency unit including taxes and rebates (e.g. EUR Cent).

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Notice: It depends on the amount whether a full or partial credit is made.

Currency

a..3

M

Currency, three characters DIN / ISO 4217, permitted are: AUD, CHF, DKK, EUR, GBP, NOK, SEK, USD.

RefNr

ns..30

O

Unique reference number

ReqIDans..32OTo avoid double payments, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction is submitted again with the same ReqID, Paygate will not carry out the payment, but will just return the status of the original transaction. Please note that the Paygate must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly.
ArticleListans..2048O

Complete article list of returned articles. This parameter must be created in JSON format.


The individual parameters in JSON format are following:

name = Product name (mandatory)

quantity = item quantity. The value may not be negative. (mandatory)

unit_price = unit price inclusive taxes but without rebates. (mandatory)

total_amount = total amount of iarticles inclusive taxes and rebates. (mandatory)

image_url = URL for an image that can be embedded later in agreement with Klarna. (max. 1024 characters)

merchant_data = "pass-through parameter" (max. 255 characters). Merchant must agree with Klarna what will be transmitted here.

product_identifiers.brand = product brand

product_identifiers.category_path = path of product category. As separator '>' has to be used.

product_identifiers.global_trade_item_number = article number (e.g. EAN, ISBN or UPC).

product_identifiers.manufacturer_part_number = manufacturer’s number

product_url = URL to product image

quantity_unit = unit of quantity (e.g. kg)

reference = article number (e.g. SKU)

tax_rate = tax rate as percentage (e.g. 25%). The percent sign muss be replaced with two zeros, thus for example 2500. The value may not be negative.

total_discount_amount = total amount of rebate. The value may not be negative.

total_tax_amount = total amount of taxes. The value may be negative, if type is 'discount'.

type = type of item position. Possible entries are <physical>, <discount>, <shipping_fee>, <sales_tax>, <digital>, <gift_card>, <store_credit>, <surcharge>

Example:
{
	"order_lines": [
		{
			"image_url": "https://www.exampleobjects.com/logo.png",
			"merchant_data": "",
			"name": "Battery Power Pack",
			"product_identifiers": {
				"brand": "Intel",
				"category_path": "Electronics Store > Computers & Tablets > Desktops",
				"global_trade_item-number": "735858293167",
				"manufacturer_part_number": "BOXNUC5CPYH"
			},
			"product_url": "https://www.estore.com/products/f2a8d7e34",
			"quantity": 1,
			"quantity_unit": "kg",
			"reference": "19-402-USA",
			"tax_rate": 0,
			"total_amount": 1000,
			"total_discount_amount": 0,
			"total_tax_amount": 0,
			"type": "physical",
			"unit_price": 1000
		}
	]
}

Afterwards the article list created in JSON format must be Base64 encoded.

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

Parameters for credits of payments with Klarna Payments

 

The following table describes the Paygate response parameters:

Parameter

Format

CND

Description

MID

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

Merchant’s transaction number

RefNr

ns..30

O

Unique reference number

Status

a..50

M

OK or FAILED

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

n8

M

Error code according to Paygate Response Codes (A4 Error codes)

InvoiceNr

ans..30

M

Number of invoice/credit note from Klarna Payments

CodeExt

ans..50

O

Error code from Klarna, if agreed with Computop support

ErrorText

ans..1024

O

Error text from Klarna, if agreed with Computop support

Response parameters for credits of payments with Klarna Payments



Reversal

Reversals are possible via a Server-to-Server connection. With this request merchants can reverse the total authorisation amount in case of no capture was made or can reverse the remaining authorisation amount if a partial capture was already made. For this purpose please use the following URL:


Notice: For security reasons, Paygate rejects all payment requests with formatting errors. Therefore, please use the correct data type for each parameter.

The following table describes the encrypted payment request parameters:

Parameter

Format

CND

Description

MerchantID

ans..30

M

MerchantID, assigned by Computop. Additionally this parameter has to be passed in plain language too.

PayID

an32

M

ID assigned by Paygate for the payment to be reversed

TransID

ans..64

M

Merchant ID for the identification of the payment process to be reversed

Amount

n..10

M

Amount to be credited in the smallest currency unit including taxes and rebates (e.g. EUR Cent).

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Notice: If no capture was made the amount must equals the previously authorised amount. If a partial capture already was made the amount must equals the remaining authorised amount. A reversal for an already completely captured order will be refused with an error also if an amount 0 is used.

Currency

a..3

M

Currency, three characters DIN / ISO 4217, permitted are: AUD, CHF, DKK, EUR, GBP, NOK, SEK, USD.

RefNr

ans..30

O

Unique reference number

MAC

an64

M

Hash Message Authentication Code (HMAC) with SHA-256 algorithm

ReqIDans..32OTo avoid double payments, enter an alphanumeric value which identifies your transaction and may be assigned only once. If the transaction is submitted again with the same ReqID, Paygate will not carry out the payment, but will just return the status of the original transaction. Please note that the Paygate must have a finalized transaction status for the first initial action. Submissions with identical ReqID for an open status will be processed regularly.

Parameters for reversal of payments with Klarna Payments

 

The following table describes the Paygate response parameters:

Parameter

Format

CND

Description

MID

ans..30

M

MerchantID, assigned by Computop

PayID

an32

M

ID assigned by Paygate for the payment, e.g. for referencing in batch files

XID

an32

M

ID for all single transactions (authorisation, capture, credit note) for one payment assigned by Paygate

TransID

ans..64

M

Merchant’s transaction number

RefNr

ns..30

O

Unique reference number

Status

a..50

M

OK or FAILED

Description

ans..1024

M

Further details in the event that payment is rejected. Please do not use the Description but the Code parameter for the transaction status analysis!

Code

n8

M

Error code according to Paygate Response Codes (A4 Error codes)

CodeExt

ans..50

O

Error code from Klarna, if agreed with Computop support

ErrorText

ans..1024

O

Error text from Klarna, if agreed with Computop support

Response parameters for reversal of payments with Klarna Payments



Batch processing via the interface

Basic information about using Batch files and about their structure can be found in the Batch Manager manual. Within batch processing not alle functions are available which are usually available for the online interface.

This section describes the parameters which must be transferred within the data set (Record) for executing a payment with Klarna Payments and which information can be found within the response file about the payment status.

When capturing there is a need to differentiate between complete and partial activation requests. In the case of part capturing you need also to transfer the article list with <ArticleList>. The <ArticleList> parameter is also required if a partial credit is made on a full activation. The two parameters <ArticleList> and <InvNo> are also required in the case of a partial credit on a partial activation. All additional parameters are also returned in the response file.

Following table gives an overview of all batch versions that are possible for a specific action and their specialities:

Action

Version

Description

Capture

1.0 / 2.0

Standard version without return of parameter Code

 

1.x / 2.x

with RefNr (valid for all versions other than 1.0)

Credit

1.0 / 2.0

Standard version without return of parameter Code

 

1.x / 2.x

with RefNr (valid for all versions other than 1.0)

Reverse

1.0 / 2.0

Standard version without return of parameter Code

 

1.x / 2x.

with RefNr (valid for all versions other than 1.0)

Description of the possible batch versions


The structure for a payment with Klarna Payments within a Batch file to be submitted is the following:

HEAD,<MerchantID>,<Date>,<Version>

KLARNAPM,CAPTURE,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<InvNo>

KLARNAPM,CAPTURE,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<ArticleList>

KLARNAPM,CREDIT,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>

KLARNAPM,CREDIT,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<ArticleList>

KLARNAPM,REVERSE,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>

FOOT,<CountRecords>,<SumAmount>


Example for Master MID Funktion:

HEAD,[Master]MerchantID,Date,2.x
Type,Action,[Slave]MID,Amount,Currency,TransID,Data (depends on Action)
FOOT,CountRecords,SumAmount


The following table describes the individual fields and values used within the data set (record) in the batch file:

Parameter

Format

CND

Description

Type

a..11

M

HEAD for Header, FOOT for Footer, KLARNAPM for Klarna Payments

Action

a..20

M

The parameter Action defines the type of transaction:

Capture

Credit

Reverse (cancellation)

Amount

n..10

M

Amount in the smallest currency unit (e.g. EUR Cent)

Please contact the helpdesk, if you want to capture amounts < 100 (smallest currency unit).

Currency

a3

M

Currency, three characters DIN / ISO 4217, permitted are: AUD, CHF, DKK, EUR, GBP, NOK, SEK, USD.

TransID

ans..64

M

TransactionID which should be unique for each payment

RefNr

ns..30

O

Unique reference number

PayID

an32

M

ID for this transaction given by Paygate

InvNo

ans..30

O

Invoice number for a part activation or part credit. Longest InvNo so far had 17 digits.

Description of fields within the record for Batch files

 

 

The record area within the response file for Batch transactions looks as follows:

HEAD,<MerchantID>,<Date>,<Version>

KLARNAPM,CAPTURE,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<InvNo>,<Status>,<Code>

KLARNAPM,CAPTURE,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<ArticleList>,<Status>,<Code>

KLARNAPM,CREDIT,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<Status>,<Code>

KLARNAPM,CREDIT,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<ArticleList>,<Status>,<Code>

KLARNAPM,REVERSE,<Amount>,<Currency>,<TransID>,(<RefNr>,)<PayID>,<Status>,<Code>

FOOT,<CountRecords>,<SumAmount>

 

The following table describes the response parameters which the Batch Manager saves in the Record area for each transaction (standard parameters not explained here, such as <TransID> or <RefNR> and request parameters are returned unchanged and correspond to the call as specified before):

Parameter

Format

CND

Description

Action

a..20

M

The parameter Action defines the type of transaction:

Capture

Credit

Reverse (cancellation)

PayID

an32

M

ID for this transaction given by Paygate

Status

a..50

M

OK or FAILED

Code

n8

M

Error code according to Paygate Response Codes (A4 Error codes)

Description of result parameters within the record for Batch files