Klarna

An article about the payment method which allows to process payments by using bank transfers in different currencies in select European countries and supports purchases and refunds.

Overview

An article about the payment method which allows to process payments by using bank transfers in different currencies in select European countries and supports purchases and refunds.

Introduction

Klarna is a payment method which allows to process payments by using e-wallets in different currencies in different countries. This method supports one-step and two-step purchases as well as refunds.

Klarna is an omnichannel payment solution. Depending on the customer's market and eligibility, the following payment options can be offered to the customer to choose from (including options of the Buy Now Pay Later category):

Pay in full—customer pays the amount in full immediately.
Pay in 3—purchase is split into three interest-free payments charged automatically to the customer’s card on scheduled dates.
Pay in 4—customer pays the first installment at purchase and the remaining three automatically every two weeks.
Pay in 30 days—customer receives the goods or services immediately and makes a single payment within 30 days.
Financing / Pay over time—longer-term installment financing, payments are made over several months.

Refer to your Ecommpay account manager for more details regarding these payment options.

This article provides information about working with the Klarna method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

General information


Payment method type	digital wallet payments
Payment instruments	digital wallets
Countries and regions	AT, AU, BE, CA, CH, CZ, DE, DK, ES, FI, FR, GB, GR, HU, IE, IT,MX, MX, NL, NO, NZ, PL, PT, RO, SE, SK, US
Payment currencies	EUR, AUD , CAD, CHF, CZK, DKK, GBP, HUF, MXN, NOK, PLN, NZD, RON, SEK, USD
Currency conversion	–
One-time purchases	+
Credential-on-file purchases	–
Full refunds	+
Partial refunds	+
Payouts	–
Chargebacks	+ (via the Klarna merchant portal, details)
Notes	Klarna method allows customers to use the following payment options Pay in full, Pay in 3, Pay in 4, Pay in 30 days, Financing / Pay over time. When working via Gate, as well as when merchants use their own custom payment interfaces in general, the design of elements associated with the Klarna brand must comply with the documentation Klarna in your checkout. (When working with the Ecommpay platform via methods that do not require the use of custom payment interfaces on the web service side, such as the Payment Page payment form and the Dashboard interface, these requirements are fulfilled on the Ecommpay side.) To improve customer convenience and conversion when working with the Klarna method, it is recommended to use the solutions described in the Perfect Customer Journey Reference documentation, including the following functionality: Side-wide banners and FAQ—embedding graphics and informational materials about the Klarna service into the web service. Sign in with Klarna—embedding into the web service the capability of authenticating customers through the Klarna service. On-Site Messaging—displaying dynamically generated messages about the availability of instalment payments via the Klarna method on product pages and in the shopping cart of the web service. Express Checkout—displaying the branded Pay with Klarna and Continue with Klarna buttons on product pages and in the shopping cart of the web service. These buttons provide accelerated interaction with the method for customers who have previously used the Klarna service by automatically filling in shipping and payment option details. Given the special aspects of the Klarna method, synchronisation of accounts between the Dashboard interface by Ecommpay and the Klarna merchant portal is supported. To configure such synchronisation, refer to your Ecommpay account manager. To work with chargebacks on payments processed via the Klarna method, use the capabilities of the Klarna service: its merchant portal and API allow you to view chargeback information, submit supporting materials and responses, and track the statuses and outcomes of chargeback reviews (for more details, see the Klarna Dispute Management documentation). Note that such chargebacks are not processed within the Ecommpay platform.
Onboarding and access fee	refer to your Ecommpay account manager

Interaction diagram

Payment processing by using the Klarna method involves the merchant's web service, one of Ecommpay interfaces, the Ecommpay payment platform, and technical facilities of the provider service.

Operations support

Various platform interfaces can be used to process payments and perform operations using the Klarna method. Purchases can be processed by using Payment Page, Gate and Dashboard (using payment links), refunds—by using Gate and Dashboard. At the same time, regardless of the interfaces used, the following properties and limitations are applicable.

When working with the Klarna the following amount limits are applicable.


	Amounts (in suppored currencies) ¹		Times ²
	minimum	maximum	base	threshold
Purchases	*	*	–	–
Refunds	–	–	–	–

Note:

The maximum amounts depend on banks.
The base and threshold times are defined as follows:
- The base time is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the web service. The base time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour (if any input from the customer is required). Use the base time to estimate when to react to the absence of payment result callbacks or when to check payment status (details).
- The threshold time is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the web service receives the callback with the payment result. A payment is automatically assigned the decline status if it wasn't processed within the threshold time. For individual customisation of the threshold time limit, contact Ecommpay technical support.

Processing scenarios

To perform a purchase by using the Klarna method, you need to redirect customer to the Klarna service, while to initiate a refund, you need to receive a request from the customer and notification from the web service side.

Figure 1. Purchase by using Payment Page

Scenarios for performing operations via the main interfaces of the payment platform correspond to those presented in the diagrams. Similarly, when additional features (such as payment links) are used, scenarios for performing operations also correspond to the specifics of those features.

Purchases by using Payment Page

General information

To process a purchase through Payment Page by using the Klarna method, the merchant web service is required to send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result. Klarna method allows customers to use the following payment options Pay in full, Pay in 3, Pay in 4, Pay in 30 days, Financing / Pay over time. The full sequence and special aspects of purchase processing are provided below.

Figure 4. Purchase processing by using Payment Page: step-by-step description

A customer initiates a purchase in the web service.
The web service sends the request for opening Payment Page to the specified Ecommpay URL.
The request for opening Payment Page is sent to the payment platform.
The payment platform receives the request and validates the required parameters and signature.
Payment Page is generated based on the project settings and parameters specified in the request.
Payment Page is displayed to the customer.
The customer selects the Klarna method.
The request for processing the payment by using the Klarna method is received by the payment platform.
The payment platform processes the request and sends it to the Klarna service.
The request is processed on the side of the provider service.
The data for redirecting the customer to the provider service is sent from the provider service to the payment platform.
The data for redirecting the customer is sent from the payment platform to Payment Page.
The customer is redirected to the provider service.
The customer completes all required payment steps.
The purchase is processed on the side of the provider service.
The result information is displayed to the customer in the provider service.
The customer is redirected to Payment Page.
The provider service sends a notification about the result to the payment platform.
The payment platform sends the payment result callback to the web service.
The payment platform sends the result information to Payment Page.
The result information is displayed to the customer on Payment Page.

Information about the formats of requests and callbacks used for processing payments by using the Klarna method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in Interaction concepts.

Request format

There are several things you need to consider when sending purchase requests by using the Klarna method:

The following parameters required for any payment must be specified:
- project_id—project identifier obtained from Ecommpay during integration
- payment_id—payment identifier unique within the project
- payment_currency—payment currency code in the ISO-4217 alpha-3 format
- payment_amount—payment amount in the smallest currency unit
- customer_id—customer identifier unique within the project
To specify the type of purchase that is different from the default one set for the specific project, pass sale (for immediate withdrawal of funds during one-step purchase processing) or auth (to place an authorisation hold during two-step purchase processing) in the operation_type parameter.
The following parameters required for any payment must be specified: project_id, payment_id, payment_currency, payment_amount, customer_id.
Customer information must be specified using the following parameters:
- identify_doc_number—identifier of the document serving as a proof of identity for the customer, the format depends on the customer's country of registration:
  - Sweden—Personal Identity Number of the form YYYYMMDD-SSSS
  - Norway—National Identity Number of the form DDMMYYIIIKK
  - Italy—Fiscal Code of the form LLLLLLYYMMDDSSSC
  - Finland—Personal Identity Code of the form DDMMYYCZZZQ
  - Spain—National Identity Document of the form SSSSSSSSA
  - Denmark—Personal Identification Number of the form DDMMYY-SSSS
  - USA—Social Security Number, consists of 9 digits
- identify_doc_issue_country—code of the country where the document serving as a proof of the customer's identity was issued. Specified in the ISO 3166-1 alpha-2 format
- customer_account_info—information about the customer's account and contact details obtained by the web service. Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme. This object must include the following objects and parameters:
  - account—object with the customer's account information kept on file by the merchant:
    - date—account creation date in the DD-MM-YYYY format
    - loyalty_level—indicator of the customer's level in the merchant's web service loyalty program, converted to one of the following values (the parameter can be omitted if the purchase_history object is included in the account object):
      - 01—high
      - 02—medium
      - 03—low
    - purchase_history—array of objects containing information about the customer's previous purchases (the parameter can be omitted if the purchase_history object is included in the account object):
      - number_of_purchases—number of purchases made in the last 12 months
      - number_of_paid_purchases—number of paid purchases in the last 12 months
      - total_amount—total amount of purchases made in the last 12 months, in the smallest units of currency specified in the currency parameter the same object
      - currency—currency code for the specified amount in the ISO-4217 alpha-3 format
      - payment_method—indicator of the type of payment instrument used, can have one of the following values: 01—payment card of the payment system via which the payment is initiated, 02—account with support of direct debiting of funds, 03—mobile wallet, 04—payment card of another payment system, 999—other instrument
      - first_purchase_at—date and time of the customer's first purchase in the web service in the DD-MM-YYYYhh:mm format
      - last_purchase_at—date and time of the customer's first purchase in the web service in the DD-MM-YYYYhh:mm format
- purchase_data—information about line items in an order, consists of a string obtained by encoding a JSON object using the Base64 encoding scheme, and includes the positions array and can include various combinations of elements from the list of supported data:
  - positions—array, that contains information about line items, relevant to the purchase, must contain at least one object that includes the following parameters (for each item of goods or services):
    - type—indicator that specifies the type of a line item, that can have one of the following values, defining the composition of the required parameters to be specified in the positions object: discount—discount or promo code (for any goods or services), flight—air travel, car—car rental, bus—bus ride, ferry—ferry crossing, train—train ride, hotel—hotel accommodation, voucher—voucher or gift certificate, insurance—insurance, event—attending an event (for example a concert or exhibition), subscription—product or service provided as part of a subscription plan with regular debiting (for example, access to watching movies in an online cinema for a month), ondemand—product or service provided as part of an on-demand subscription plan (for example, watching a movie in an online cinema), marketplace—product or service provided via a marketplace, product—a product of a different category, service—a service of a different category, other—another type of service provided to the customer
    - name—name of the item
    - quantity—number of goods or services per item
    - amount_total—total cost of goods or services per item, in smallest currency units or as a hyphen (-) for items with the discount type
      The product, service, discount and other types require only the parameters type, name, quantity and amount_total.
  - Whether the following parameters are required to be specified in the positions array depends on the position type.
    Figure 5. flight
    - departure—object that contains departure information:
      
      airport—three-letter code assigned to the departure airport by the International Air Transport Association (IATA)
      
      date—departure date in the DD-MM-YYYY format
      
      country—country code in the departure address in the ISO 3166-1 alpha-2 format
    - arrival—object that contains arrival information:
      
      airport—three-letter code assigned to the arrival airport by the International Air Transport Association (IATA)
      
      country—country code in the arrival address in the ISO 3166-1 alpha-2 format
    - passengers—array of objects containing passenger information:
      
      first_name—first name of the passenger
      
      last_name—last name of the passenger
    Figure 6. car
    - departure—object that contains departure information:
      
      city—name of the city in the departure address
      
      country—country code in the departure address in the ISO 3166-1 alpha-2 format
    - arrival—object that contains arrival information:
      
      city—name of the city in the departure address
      
      country—country code in the departure address in the ISO 3166-1 alpha-2 format
    - passengers—array of objects containing passenger information:
      
      first_name—first name of the passenger
      
      last_name—last name of the passenger
    Figure 7. bus, train, ferry
    - departure—object that contains departure information:
      
      date—departure date in the DD-MM-YYYY format
      
      city—name of the city in the departure address
      
      country—country code in the departure address in the ISO 3166-1 alpha-2 format
    - arrival—object that contains arrival information:
      
      city—name of the city in the arrival address
      
      country—country code in the arrival address in the ISO 3166-1 alpha-2 format
    - passengers—array of objects containing passenger information:
      
      first_name—first name of the passenger
      
      last_name—last name of the passenger
    Figure 8. hotel
    - hotel_name—name of the accommodation (for example, of a hotel or a hostel)
    - start_date—service start date (for example, check-in date) in the DD-MM-YYYY format
    - end_date—service end date (for example, check-out date) in the DD-MM-YYYY format
    - city—city name in the accommodation address
    - country—country code in the accommodation address in the ISO 3166-1 alpha-2 format
    - guests—array of objects containing information about guests:
      
      first_name—first name of the guest
      
      last_name—last name of the guest
    Figure 9. voucher
    - start_date—start date of the voucher or certificate in the DD-MM-YYYY format
    - company—name of the organisation issuing the voucher or certificate
    Figure 10. event
    - event_type—event type indicator that can have one of the following values: CONCERT—concert, FESTIVAL—festival, TOUR—excursion or tour, IN_PERSON_EDUCATION—in-person educational event, DIGITAL_EDUCATION—online educational event, SPORT—sporting event, CONFERENCE—conference, EXPO—exhibition.
    - start_date—event start date in the DD-MM-YYYY format
    - end_date—event end date in the DD-MM-YYYY format
    - country—country code in the event venue's address in the ISO 3166-1 alpha-2 format
    Figure 11. subscription
    - billing_plans, array of objects—array of objects containing subscription information
      
      interval, string—indicator that specifies the basic debiting period, can have one of the following values:
      
      DAY—day
      
      WEEK—week
      
      MONTH—month
      
      YEAR—year
      
      start_date, string, ^\\d{2}-\\d{2}-\\d{4}$—debiting start date in the DD-MM-YYYY format, starting from the day after the payment processing date
      
      frequency, number—multiplier to increase the basic debiting period
    Figure 12. ondemand
    - interval, string—indicator that specifies debiting frequency, can have one of the following values:
      
      DAY—day
      
      WEEK—week
      
      MONTH—month
      
      YEAR—year
    - frequency, number—multiplier to increase debiting frequency
    Figure 13. marketplace
    - seller—object containing information about the seller on the marketplace:
      
      name—name or title of the seller on the marketplace
      
      city—name of the city where the seller is located
      
      country—country code of the seller's location in the ISO 3166-1 alpha-2 format
      
      registation—date of seller registration on the marketplace in the DD-MM-YYYY format
    - product_category—product or service category indicator, can have one of the following values:
      
      ACCESSORIES—accessories
      
      APPLIANCES—home appliances
      
      APPS_AND_GAMES—applications and games
      
      ARTS_CRAFTS_AND_SEWING—arts and crafts
      
      AUTOMOTIVE—car products
      
      BEAUTY—personal care products
      
      BABY—children's products
      
      BABY_CLOTHING—children's clothing
      
      BAGS_AND_PURSES—bags and purses
      
      BOOKS—books and other printed publications
      
      CDS_AND_VINYL—compact discs, vinyl records, and other physical media audio recordings
      
      CELL_PHONES_AND_ACCESSORIES—mobile phones and accessories
      
      COLLECTIBLES_AND_FINE_ARTS—art and collectibles
      
      DIGITAL_MUSIC—musical recordings in digital format
      
      ELECTRONICS—electronic devices
      
      GROCERY_AND_GOURMET_FOOD—grocery and gourmet foods
      
      HANDMADE—handmade products
      
      HEALTH_AND_PERSONAL_CARE—health and personal care products
      
      HOME_AND_KITCHEN—home and kitchen products
      
      INDUSTRIAL_AND_SCIENTIFIC—industrial and scientific equipment
      
      LUGGAGE_AND_TRAVEL_GEAR—luggage, travel accessories, and other travel products
      
      MAGAZINE_SUBSCRIPTIONS—subscriptions to print or digital periodicals
      
      MEN_CLOTHING—men's clothing
      
      MUSICAL_INSTRUMENTS—musical instruments
      
      OFFICE_PRODUCTS—office supplies
      
      PATIO_LAWN_AND_GARDEN—patio and garden supplies
      
      PET_SUPPLIES—pet supplies
      
      SHOES—shoes
      
      SOFTWARE—software
      
      SPORTS_AND_OUTDOORS—sports and outdoor supplies
      
      TOOLS_AND_HOME_IMPROVEMENT—construction tools and home improvement supplies
      
      TOYS_AND_GAMES—toys and games
      
      VIDEO_GAMES—video games
      
      WOMEN_CLOTHING—women's clothing
- additional_info—string object containing additional information that may be relevant for payment processing:
  - integration_metadata, object—object containing information about how the payment was technically initiated:
    - originators, array of objects—array of objects containing information about the components used to initiate the payment (on the merchant's web service; up to six objects):
      - name, string—name of the service via which the payment was initiated, in the form of uppercase letters, digits, and underscores (_) instead of spaces (for example, COSMO_GAMES_STORE)
      - module_name, string—name of the technical module via which the payment was initiated, for example, cosmoshopPlugin
      - module_version, string—version number of the technical module via which the payment was initiated, for example, 2.1
      - session_reference, string—identifier of the operation or session within the web service, as a universally unique identifier version 7 (UUIDv7) in accordance with RFC 9562, for example, 018b163d-0b83-7ba0-b837-da575d0ff824

To ensure the user interface complies with Klarna service requirements, it is recommended to specify the payment form display language code in the language_code parameter and the customer address region code in the region_code parameter. The language code must be specified in accordance with the region code and the following compliance rules.

Figure 14. List of supported languages for different region codes


Region code	Supported languages
`AT`	`de`, `en`
`AU`	`en`
`BE`	`nl`, `fr`, `en`
`CA`	`en`, `fr`
`CH`	`en`, `de`, `fr`, `it`
`CZ`	`cs`, `en`
`DE`	`de`, `en`
`DK`	`da`, `en`
`ES`	`es`, `en`
`FI`	`fi`, `sv`, `en`
`FR`	`fr`, `en`
`GB`	`en`
`GR`	`el`, `en`
`HU`	`hu`, `en`
`IE`	`en`
`IT`	`it`, `en`
`NL`	`nl`, `en`
`NO`	`nb`, `nn`, `en`
`NZ`	`en`
`PL`	`pl`, `en`
`PT`	`pt`, `en`
`RO`	`ro`, `en`
`SE`	`sv`, `en`
`SK`	`sk`, `en`
`US`	`en`

If the language code is not specified in the request or a code that does not comply with the provided rules is specified, the payment form is displayed using English for the main form elements and possibly using the primary national language for specific Klarna service elements, which may lead to a decrease in conversion rate.

If you need to have the payment form displayed with the Klarna method selected, set the force_payment_method parameter to klarna.
Additionally, any other parameters available for working with Payment Page can be used (details).
After all target parameters are specified, create a signature (details).

Thus, a correct request for opening the payment form using the Klarna method must contain the project identifier, basic payment information (identifier, amount, and currency code), customer and line items information, as well as signature.

{
  "project_id": 12345,
  "payment_amount": 663800,
  "payment_currency": "EUR",
  "payment_id": "ORDER-20260309-0001",
  "payment_description": "Order with 2 computers, 2 flight tickets and 1 event reservation",
  "customer_id": "cust-9001001",
  "customer_first_name": "John",
  "customer_last_name": "Smith",
  "customer_phone": "+31612345678",
  "customer_street": "Herengracht",
  "building_address": "101",
  "customer_state": "NH",
  "customer_email": "john@example.com",
  "customer_city": "Amsterdam",
  "region_code": "NL",
  "language_code": "nl",
  "customer_zip": "1015BG",
  "customer_day_of_birth": "15-04-1985",
  "identify_doc_number": "19850415-1234",
  "doc_issue_country": "NL",
  "customer_account_info": "eyJkYXRlIjoiMTAtMDItMjAyMSIsImNoYW5nZV9kYXRlIjoiMDiOnsibG95YWx0eV9sZXZlbCI6IkhJR0giLCJhdXRoX3RpbWUiOiIwOS0wMy0yMDI2MTA6MTUiLCJhdXRoX21ldGhvZCI6IlBBU1NXT1JEIn19",
  "purchase_data": "eyJkYXRlIjoiMTAtMDItMjAyMSIsImNoYW5nZV9kYXRlIjoiMDEtMDMtMjAgiLCJhdXRoX3RpbWUiOiIwOS0wMy0yMDI2MTA6MTUiLCJhdXRoX21ldGhvZCI6IlBBU1NXT1JEIn18",
  "additional_info":{
   "integration_metadata":{
     "originators":[{
      "moduleName":"cosmoshopPlugin",
      "moduleVersion":"2.1",
      "name":"COSMO_GAMES_STORE",
      "session_reference":"018b163d-0b83-7ba0-b837-da575d0ff824"
    }]
   }
  }
}

Figure 15. Example of sufficient data in a purchase request

{
  "project_id": 12345,
  "payment_amount": 663800,
  "payment_currency": "EUR",
  "payment_id": "ORDER-20260309-0001",
  "payment_description": "Order with 2 computers, 2 flight tickets and 1 event reservation",
  "customer_id": "cust-9001001",
  "customer_first_name": "John",
  "customer_last_name": "Smith",
  "customer_phone": "+31612345678",
  "customer_street": "Herengracht",
  "building_address": "101",
  "customer_state": "NH",
  "customer_email": "john@example.com",
  "customer_city": "Amsterdam",
  "region_code": "NL",
  "language_code": "nl",
  "customer_zip": "1015BG",
  "customer_day_of_birth": "15-04-1985",
  "identify_doc_number": "19850415-1234",
  "doc_issue_country": "NL",
  "customer_account_info": "eyJkYXRlIjoiMTAtMDItMjAyMSIsImNoYW5nZV9kYXRlIjoiMDiOnsibG95YWx0eV9sZXZlbCI6IkhJR0giLCJhdXRoX3RpbWUiOiIwOS0wMy0yMDI2MTA6MTUiLCJhdXRoX21ldGhvZCI6IlBBU1NXT1JEIn19",
  "purchase_data": "eyJkYXRlIjoiMTAtMDItMjAyMSIsImNoYW5nZV9kYXRlIjoiMDEtMDMtMjAgiLCJhdXRoX3RpbWUiOiIwOS0wMy0yMDI2MTA6MTUiLCJhdXRoX21ldGhvZCI6IlBBU1NXT1JEIn18",
  "additional_info":{
   "integration_metadata":{
     "originators":[{
      "moduleName":"cosmoshopPlugin",
      "moduleVersion":"2.1",
      "name":"COSMO_GAMES_STORE",
      "session_reference":"018b163d-0b83-7ba0-b837-da575d0ff824"
    }]
   }
  }
}

Extended list of supported parameters

This section provides an extended list of parameters to specify in purchase requests. Required parameters are listed in the section Request format.


Parameter	Description
additional_info string, optional	String object containing additional information that may be relevant for payment processing. The JSON object can include various combinations of elements from the list of supported data. Figure 16. Supported data `integration_metadata`, object—object containing information about how the payment was technically initiated: `originators`, array of objects—array of objects containing information about the components used to initiate the payment (on the merchant's web service; up to six objects): `name`, string—name of the service via which the payment was initiated, in the form of uppercase letters, digits, and underscores (_) instead of spaces (for example, `COSMO_GAMES_STORE`) `module_name`, string—name of the technical module via which the payment was initiated, for example, `cosmoshopPlugin` `module_version`, string—version number of the technical module via which the payment was initiated, for example, `2.1` `session_reference`, string—identifier of the operation or session within the web service, as a universally unique identifier version 7 (UUIDv7) in accordance with RFC 9562, for example, `018b163d-0b83-7ba0-b837-da575d0ff824` `klarna_network_session_token`, string—token received from a payment system or provider and intended for secure interaction within a session (for example, Klarna Network Session Token) `klarna_network_data`, string—string object that contains specific information that can be used for ensuring interoperability between Klarna and it's partners. Information specified in this parameter can complement information specified in other parameters. The value length must be between 1 and 10240 characters (inclusive). The object must be formatted as follows: `"{\"content\":{\"customer_account_info\":[{\"unique_account_identifier\":\"test@example.com\",\"account_registration_date\":\"2017-02-13T10:49:20Z\",\"account_last_modified\":\"2019-03-13T11:45:27Z\"}]},\"content_type\":\"application/vnd.klarna.internal.emd-v2+json\"}"` Figure 17. Example of a JSON object "integration_metadata":{ "originators":[{ "moduleName":"cosmoshopPlugin", "moduleVersion":"2.1", "name":"COSMO_GAMES_STORE", "session_reference":"018b163d-0b83-7ba0-b837-da575d0ff824" }] }, "klarna_network_session_token":"453", "klarna_network_data": {\"content\":{\"customer_account_info\":[{\"unique_account_identifier\":\"test@gmail.com\",\"account_registration_date\":\"2017-02-13T10:49:20Z\",\"account_last_modified\":\"2019-03-13T11:45:27Z\"}]},\"content_type\":\"application/vnd.klarna.internal.emd-v2+json\"}"
customer_account_info string, optional	Information about the customer's account and contact details obtained by the web service. Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme. The JSON object can include the `customer` object containing various combinations of elements from the list of supported data. Figure 18. Supported data `address_match`, string—indicates whether the customer's billing address matches the address specified in the `shipping` object: `Y`—addresses match `N`—addresses do not match `home_phone`, string—the customer's home phone number, contains between 4 and 24 digits `work_phone`, string—the customer's work phone number, contains between 4 and 24 digits `account`, object—the object with the customer's account information kept on file by the merchant: `activity_day`, integer—number of payment attempts in the last 24 hours, 3 characters maximum `activity_year`, integer—number of payment attempts in the last 365 days, 3 characters maximum `additional`, string—additional information about the customer's account in free text, for example, its identifier. Can contain up to 64 characters `age_indicator`, string, `^0[1-5]$`—number of days since the customer account was created. Possible values: `01`—guest checkout `02`—the account was created at the moment of making a payment `03`—fewer than 30 days `04`—between 30 and 60 days `05`—more than 60 days `auth_data`, string—additional login information in free text, can contain up to 255 characters `auth_method`, string, `^(0[1-4]\|0[1-4][1-6])$`—indicates how the customer was authenticated during their most recent login to the web service. Can have one of the possible values: for standard card payments: `01`—no authentication `02`—logging in with authentication data kept on file by the merchant `03`—logging in with the federated identity credentials (for example, Google Account or Facebook ID) `04`—logging in with the use of FIDO authenticator (Fast Identity Online) for payments using alternative payment methods: `021`—authentication using an account password `022`—authentication using a reusable code `023`—authentication using a one-time verification code (One Time PIN, OTP) received in a short message (SMS) `024`—authentication using a one-time verification code (One Time PIN, OTP) received in an email `025`—authentication using an URL received in an email `026`—authentication using an URL received in a short message (SMS) `031`—Silent Network Authentication `032`—authentication using federated identity credentials via phone number `041`—authentication using an electronic key (passkey) `auth_time`, string, `^\\d{2}-\\d{2}-\\d{4}\\d{2}:\\d{2}$`—date and time of the customer's most recent account login in the `DD-MM-YYYYhh:mm` format `change_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—date of the most recent change to the account, except for the password change or password reset, in the `DD-MM-YYYY` format `change_indicator`, string, `^0[1-4]$`—number of days since the most recent change to the account, except for the password change or password reset. Possible values: `01`—the account was updated on the day when the payment was made `02`—fewer than 30 days `03`—between 30 and 60 days `04`—more than 60 days `date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—the account creation date in the `DD-MM-YYYY` format `device_purchase_history`, array of objects—array of objects containing information about previous purchases from the customer's device: `number_of_purchases`, number—number of purchases made in the last 12 months `number_of_paid_purchases`, number—number of paid purchases made in the last 12 months `number_of_disputed_purchases`, number—number of purchases with disputes in the last 12 months `total_amount`, number—total amount of purchases made in the last 12 months, in the smallest units of the currency specified in the `currency` parameter of this same object `currency`, string, `^[A-Z]{3}$`—currency code for the specified amount in the ISO-4217 alpha-3 format `payment_method`, string—indicator of the type of payment instrument used, can have one of the following values: `01`—payment card of the payment system via which the payment is initiated `02`—account with support of direct debiting of funds `03`—mobile wallet `04`—payment card of another payment system `999`—other instrument `first_purchase_at`, string, `^\\d{2}-\\d{2}-\\d{4}\\d{2}:\\d{2}$`—date and time of the customer's first purchase in the web service in the `DD-MM-YYYYhh:mm` format `last_purchase_at`, string, `^\\d{2}-\\d{2}-\\d{4}\\d{2}:\\d{2}$`—date and time of the customer's last purchase in the web service in the `DD-MM-YYYYhh:mm` format `loyalty_level`, string—indicator of the customer's level in the merchant's web service loyalty program, converted to one of the following values: `01`—high `02`—medium `03`—low `pass_change_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—date of the most recent password change or reset in the `DD-MM-YYYY` format `pass_change_indicator`, string, `^0[1-5]$`—number of days since the most recent password change or reset. Possible values: `01`—password was not changed or reset `02`—password was changed or reset on the day when the payment was made `03`—fewer than 30 days `04`—between 30 and 60 days `05`—more than 60 days `payment_age`, string, `^\\d{2}-\\d{2}-\\d{4}$`—card record creation date in the `DD-MM-YYYY` format `payment_age_indicator`, string, `^0[1-5]$`—number of days since the payment card details were saved to a customer's account. Possible values: `01`—guest checkout `02`—card details were saved on the day when the payment was made `03`—fewer than 30 days `04`—between 30 and 60 days `05`—more than 60 days `provision_attempts`, integer—number of attempts to save new card details to a customer's account in the last 24 hours, 3 characters maximum `purchase_history`, array of objects—array of objects containing information about the customer's previous purchases: `number_of_purchases`, number—number of purchases made in the last 12 months `number_of_paid_purchases`, number—number of paid purchases in the last 12 months `number_of_disputed_purchases`, number—number of purchases with chargebacks in the last 12 months `total_amount`, number—total amount of purchases made in the last 12 months, in the smallest units of currency specified in the `currency` parameter the same object `currency`, string, `^[A-Z]{3}$`—currency code for the specified amount in the ISO-4217 alpha-3 format `payment_method`, string—indicator of the type of payment instrument used, can have one of the following values: `01`—payment card of the payment system via which the payment is initiated `02`—account with support of direct debiting of funds `03`—mobile wallet `04`—payment card of another payment system `999`—other instrument `first_purchase_at`, string, `^\\d{2}-\\d{2}-\\d{4}\\d{2}:\\d{2}$`—date and time of the customer's first purchase in the web service in the `DD-MM-YYYYhh:mm` format `last_purchase_at`, string, `^\\d{2}-\\d{2}-\\d{4}\\d{2}:\\d{2}$`—date and time of the customer's last purchase in the web service in the `DD-MM-YYYYhh:mm` format `purchase_number`,—number of purchases made via the customer's account in the last 6 months, 4 characters maximum `suspicious_activity`, string, `^0[1-2]$`— indicates the presence of suspicious activity. Possible values: `01`—no suspicious activity detected `02`—suspicious activity detected Figure 19. Example of a JSON object `"date": "10-02-2021", "change_date": "01-03-2026", "additional": { "loyalty_level": "HIGH", "auth_time": "09-03-202610:15", "auth_method": "PASSWORD", "purchase_history": [ { "number_of_purchases": 18, "number_of_paid_purchases": 17, "number_of_disputed_purchases": 1, "total_amount": 845900, "currency": "EUR", "payment_method": "CREDIT_CARD", "first_purchase_at": "14-03-202309:40", "last_purchase_at": "01-03-202620:25" } ]` Figure 20. Example of the resulting string eyAKICAiY3VzdG9tZXIiOnsgCiAgICAiYWRkcmVzc19tYXRjaCI6IlkiLAogICAgImhvbWVfcGhvbmUiOiI0NDIwNTU1MjY2MDgiLAogICAgIndvcmtfcGhvbmUiOiI0NDIwNTU1Mzc3MDkiLAogICAgImFjY291bnQiOnsgCiAgICAgICJhZGRpdGlvbmFsIjoiZ2FtZXIxMjM0NSIsCiAgICAgICJhZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAiZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAiY2hhbmdlX2luZGljYXRvciI6IjAxIiwKICAgICAgImNoYW5nZV9kYXRlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJwYXNzX2NoYW5nZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJwYXNzX2NoYW5nZV9kYXRlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJwdXJjaGFzZV9udW1iZXIiOjEyLAogICAgICAicHJvdmlzaW9uX2F0dGVtcHRzIjoxNiwKICAgICAgImFjdGl2aXR5X2RheSI6MjIsCiAgICAgICJhY3Rpdml0eV95ZWFyIjoyMjIyLAogICAgICAicGF5bWVudF9hZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAicGF5bWVudF9hZ2UiOiIwMS0xMC0yMDIyIiwKICAgICAgInN1c3BpY2lvdXNfYWN0aXZpdHkiOiIwMSIsCiAgICAgICJhdXRoX21ldGhvZCI6IjAxIiwKICAgICAgImF1dGhfdGltZSI6IjAxLTEwLTIwMjIxMzoxMiIsCiAgICAgICJhdXRoX2RhdGEiOiJsb2dpbl8wMTAyIgogICAgfQogIH0KfQ=====
`customer_shipping` string, optional	Information about the delivery of a product or a service rendered to the customer (see this article). Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme. The JSON object can include various combinations of elements from the list of supported data. Figure 21. Supported data `shipping_extended`, array of objects—array of objects containing shipping information, which may be relevant for individual alternative payment methods and may include the following information: `address`, string—basic information about the shipping address in the form of a street name and a house number `address2`, string—additional information about the shipping address in the form of the name of the district, information additional to the house number or other information `carrier`, string—name of the shipping organisation `city`, string—name of the city (or other locality) in the shipping address `country`, string, `^[A-Z]{2}$`—country code in the shipping address in the ISO 3166-1 alpha-2 format `email`, string—email address `first_name`, string—first name of the recipient `last_name`, string—last name of the recipient `phone`, string, `^[0-9]{4,24}$`—phone number of the recipient, as a sequence of digits without separators `postal`, string—postal code in the shipping address `region_code`, string, `^[0-9A-Z]{1,3}$`—internal area code in the shipping address, representing the second part of the international area code (in the ISO 3166-2 format), without the two-letter country code and separating hyphen `shipping_reference`, string—shipping identifier within the web service or delivery service, required when specifying information about different deliveries in a single request `type`, string—shipping type indicator, can have one of the following values: `011`—door delivery to the customer's billing address `012`—delivery to the building at the customer's billing address `013`—delivery to a PO Box at the customer's billing address `021`—door delivery to another confirmed address `022`—delivery to the building at another confirmed address `023`—delivery to a PO Box at another confirmed address `031`—door delivery to an address that does not match the billing address and is not confirmed `032`—delivery to the building to an address that does not match the billing address and is not confirmed `033`—delivery to a mailbox at an address that does not match the billing address and is not confirmed `041`—pickup from a store `042`—pickup from a warehouse `043`—pickup from a parcel locker `044`—pickup from an order pickup point `051`—delivery to an email address `052`—delivery with file download from a web service `059`—other electronic delivery method `071`—other physical delivery method `type_attributes`, array of strings—array of strings with a list of additional shipping parameter indicators, can have the following values: `01`—indicator of the requirement of delivery confirmation by the customer (with receipt of their signature) `02`—indicator of the requirement of recipient identity verification (with verification of information by a delivery specialist) `03`—indicator of the requirement of contactless delivery `04`—indicator of the requirement of door-to-door delivery `05`—indicator of the requirement of delivery to the building `06`—indicator of the requirement of delivery to neighbors `07`—indicator of the requirement of express delivery `08`—indicator of the requirement of tracked delivery `09`—indicator of the requirement of using untracked delivery Figure 22. Example of a JSON object "customer_shipping": [ { "first_name": "John", "last_name": "Smith", "email": "john@example.com", "phone": "+31612345678", "address": "Herengracht 101", "address2": "Herengracht 101, apt 1", "postal": "1015BG", "city": "Amsterdam", "region_code": "NH", "country": "NL", "type": "TO_DOOR", "type_attributes": [ "TRACKED", "SIGNATURE_REQUIRED" ], "carrier": "PostNL", "shipping_reference": "SHIP-COMPUTER-1" }, { "first_name": "Jane", "last_name": "Smith", "email": "jane@example.com", "phone": "+31698765432", "address": "Keizersgracht 250", "address2": "Keizersgracht 250, office reception", "postal": "1016EV", "city": "Amsterdam", "region_code": "NH", "country": "NL", "type": "TO_DOOR", "type_attributes": [ "TRACKED", "EXPRESS" ], "carrier": "DHL", "shipping_reference": "SHIP-COMPUTER-2" } ] Figure 23. Example of the resulting string ImN1c3RvbWVyX3NoaXBwaW5nIjogWwogICAgewogICAgICAiZmlyc3RfbmFtZSI6ICJKb2huIiwKICAgICAgImxhc3RfbmFtZSI6ICJTbWl0aCIsCiAgICAgICJlbWFpbCI6ICJqb2huQGV4YW1wbGUuY29tIiwKICAgICAgInBob25lIjogIiszMTYxMjM0NTY3OCIsCiAgICAgICJhZGRyZXNzIjogIkhlcmVuZ3JhY2h0IDEwMSIsCiAgICAgICJhZGRyZXNzMiI6ICJIZXJlbmdyYWNodCAxMDEsIGFwdCAxIiwKICAgICAgInBvc3RhbCI6ICIxMDE1QkciLAogICAgICAiY2l0eSI6ICJBbXN0ZXJkYW0iLAogICAgICAicmVnaW9uX2NvZGUiOiAiTkgiLAogICAgICAiY291bnRyeSI6ICJOTCIsCiAgICAgICJ0eXBlIjogIlRPX0RPT1IiLAogICAgICAidHlwZV9hdHRyaWJ1dGVzIjogWwogICAgICAgICJUUkFDS0VEIiwKICAgICAgICAiU0lHTkFUVVJFX1JFUVVJUkVEIgogICAgICBdLAogICAgICAiY2FycmllciI6ICJQb3N0TkwiLAogICAgICAic2hpcHBpbmdfcmVmZXJlbmNlIjogIlNISVAtQ09NUFVURVItMSIKICAgIH0sCiAgICB7CiAgICAgICJmaXJzdF9uYW1lIjogIkphbmUiLAogICAgICAibGFzdF9uYW1lIjogIlNtaXRoIiwKICAgICAgImVtYWlsIjogImphbmVAZXhhbXBsZS5jb20iLAogICAgICAicGhvbmUiOiAiKzMxNjk4NzY1NDMyIiwKICAgICAgImFkZHJlc3MiOiAiS2VpemVyc2dyYWNodCAyNTAiLAogICAgICAiYWRkcmVzczIiOiAiS2VpemVyc2dyYWNodCAyNTAsIG9mZmljZSByZWNlcHRpb24iLAogICAgICAicG9zdGFsIjogIjEwMTZFViIsCiAgICAgICJjaXR5IjogIkFtc3RlcmRhbSIsCiAgICAgICJyZWdpb25fY29kZSI6ICJOSCIsCiAgICAgICJjb3VudHJ5IjogIk5MIiwKICAgICAgInR5cGUiOiAiVE9fRE9PUiIsCiAgICAgICJ0eXBlX2F0dHJpYnV0ZXMiOiBbCiAgICAgICAgIlRSQUNLRUQiLAogICAgICAgICJFWFBSRVNTIgogICAgICBdLAogICAgICAiY2FycmllciI6ICJESEwiLAogICAgICAic2hpcHBpbmdfcmVmZXJlbmNlIjogIlNISVAtQ09NUFVURVItMiIKICAgIH0KICBdCg==
`identify_doc_issue_country` string, optional	The code of the country where the document serving as a proof of the customer's identity was issued. Specified in the ISO 3166-1 alpha-2 format. Example: `GB`
`purchase_data` string, optional	Information about line items in an order. Consists of a string obtained by encoding a JSON object using the Base64 encoding scheme. The JSON object includes the `positions` array and can include various combinations of elements from the list of supported data. May be required for using specific payment methods such as Klarna. Figure 24. Supported data The `positions` array may contain the following information. General information about each line item (applicable to any item and sufficient for items with the `discount`, `product`, `service`, and `other` types) `type`, string—indicator that specifies the type of a line item, that can have one of the following values: `bus`—bus ride `car`—car rental `discount`—discount or promo code (for any goods or services) `event`—attending an event (for example a concert or exhibition) `ferry`—ferry crossing `flight`—air travel `hotel`—hotel accommodation `insurance`—insurance `marketplace`—product or service provided via a marketplace `ondemand`—product or service provided as part of an on-demand subscription plan (for example, watching a movie in an online cinema) `subscription`—product or service provided as part of a subscription plan with regular debiting (for example, access to watching movies in an online cinema for a month) `train`—train ride `voucher`—voucher or gift certificate `product`—a product of a different category `service`—a service of a different category `other`—another type of service provided to the customer `name`, string—name of the item `amount`, integer—cost of a unit of goods or services per item, in smallest currency units, specified as a negative value for items with the `discount` type (for example, `-1000`) `quantity`, number—number of goods or services per item `amount_total`, integer—total cost of goods or services per item, in smallest currency units, specified as a negative value for items with the `discount` type (for example, `-1000`) `tax_total`, integer—amount of tax or fee included in the item price, in smallest currency units, specified as a negative value for items with the `discount` type (for example, `-1000`) `product_reference`, string—identifier of a product or service as defined by the web service `product_url`, string—address of the web service page with the product or service card `product_image`, string—image URL of the product or service `item_reference`, string—item identifier within the list of all purchased items `shipping_reference`, string—the shipping identifier for an item as defined by a web service or shipping service Detailed information about transportation services (for items of the `bus`, `car`, `ferry`, `flight` and `train` types) `departure`, object—object that contains departure information: `address`, string—basic information about the departure address in the form of a street name and a house number (not applicable for the `flight` type) `address2`, string—additional information about the departure address in the form of the name of the district, information additional to the house number or other information (not applicable for the `flight` type) `date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—departure date in the `DD-MM-YYYY` format `city`, string—name of the city in the departure address `country`, string, `^[A-Z]{2}$`—country code in the departure address in the ISO 3166-1 alpha-2 format `location`, string—name of the departure location (not applicable for the `flight` type) `postal`, string—postal code in the address of the departure location (not applicable for the `flight` type) `region_code`, string, `^[0-9A-Z]{1,3}$`—the internal code of the region (state, province, or other territorial area) in the address of the departure location, is the second part of the international area code (in the ISO 3166-2 format), without the two-letter country code and separating hyphen (not applicable for the `flight` type) `airport`, string—three-letter code assigned to the departure airport by the International Air Transport Association (IATA) `arrival`, object—object that contains arrival information: `address`, string—basic information about the arrival address in the form of a street name and a house number (not applicable for the `flight` type) `address2`, string—additional information about the arrival address in the form of the name of the district, information additional to the house number or other information (not applicable for the `flight` type) `city`, string—name of the city in the arrival address `country`, string, `^[A-Z]{2}$`—country code in the arrival address in the ISO 3166-1 alpha-2 format (not applicable for the `flight` type) `postal`, string—postal code in the address of the arrival location (not applicable for the `flight` type) `region_code`, string, `^[0-9A-Z]{1,3}$`—the internal code of the region (state, province, or other territorial area) in the address of the arrival location, is the second part of the international area code (in the ISO 3166-2 format), without the two-letter country code and separating hyphen (not applicable for the `flight` type) `airport`, string—three-letter code assigned to the arrival airport by the International Air Transport Association (IATA) `bus_company`, string—name of the organisation providing bus transportation (only applicable for the `bus` type) `car_rental_company`, string—name of the organisation providing the rental car `ferry_line`, string—name of the organisation that operates the ferry service `airline`, string—two-letter code assigned to an airline by the International Air Transport Association (IATA) `train_company`, string—name of the organisation carrying out rail transportation `affiliate`, string—name of the partner organisation providing the service `booking_reference`, string—booking identifier (code) relevant for the flight `passengers`, array of objects—array of objects containing passenger information: `first_name`, string—first name of the passenger `last_name`,string—last name of the passenger `class`, string—indicator that specifies the service class, can have one of the following values: `COMPACT`—compact class `ECONOMY`—economy class `PREMIUM_ECONOMY`—premium economy class `BUSINESS`—business class `FIRST_CLASS`—first class `insurances`, array of objects—array of objects containing insurance services information: `company`, string—name of the insurance company `insurance_type`, string—indicator of the insurance service type, can have one of the following values for the types `bus`, `ferry`, `flight` and `train`: `BANKRUPTCY`—bankruptcy insurance for the service provider `CANCELATION`—service cancellation insurance `EMERGENCY`—emergency insurance `MEDICAL`—medical insurance For the `car` type the supported values are the following: `LIABILITY_SUPPLEMENT`—third-party liability insurance covering bodily injury and property damage `LOSS_DAMAGE_WAIVER`—vehicle theft or total damage insurance `PARTIAL_DAMAGE_WAIVER`—insurance from vehicle damage to a specific excess or deductible `PERSONAL_ACCIDENT`—insurance from medical expenses and accidental death for the driver and passengers `PERSONAL_EFFECTS`—insurance for personal belongings stolen or damaged inside the rental vehicle `amount`, number—cost of the insurance service in the smallest units of currency specified in the `currency` parameter of the same object currency `currency`, string, `^[A-Z]{3}$`—currency code for the cost of the insurance service in the ISO-4217 alpha-3 format `price`, number—cost of a ticket or reservation in the smallest units of currency specified in the `currency` parameter of the same object `currency`, string, `^[A-Z]{3}$`—currency code for the ticket or reservation price in the ISO-4217 alpha-3 format Detailed accommodation information (for items of the `hotel` type) `hotel_name`, string—name of the accommodation (for example, of a hotel or a hostel) `affiliate`, string—name of the partner organisation providing the service `host`, object—object containing information about the rental property owner: `type`, string—rental type indicator: `HOSTEL`—booking a room or bed in a hostel `HOTEL`—booking a room in a hotel `OWNER`—renting the property directly from the owner `RENTAL_AGENCY`—renting the property through an agency `host_reference`, string—host identifier `country`, string, `^[A-Z]{2}$`—country code in the host's address (legal address for a legal entity or residential address for an individual) in ISO 3166-1 alpha-2 format `registration_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—registration date of the host in the `DD-MM-YYYY` format `reservations`, number—number of reservations via the host over the past 12 months `lodging_type`, string—indicator of the accommodation type, can have one of the following values: `ROOM`—room `CABANA`—cabana (beach cabin or similar kind of shelter) `STANDARD`—standard room `SUITE`—suite `APARTMENT`—apartment `HOUSE`—house `VILLA`—villa `PENTHOUSE`—penthouse `address`, string—basic information about the accommodation address in the form of the street name and house number `address2`, string—additional information about the accommodation address in the form of the district name, additional information to the house number, or other details `city`, string—city name in the accommodation address `country`, string, `^[A-Z]{2}$`—country code in the accommodation address in the ISO 3166-1 alpha-2 format `postal`, string—postal code in the accommodation address `region_code`, string, `^[0-9A-Z]{1,3}$`—internal area code (state, province, or other territorial area) in the accommodation address, representing the second part of the international area code (in the ISO 3166-2 format), without the two-letter country code and separating hyphen `rooms`, number—number of accommodations being booked (for example, rooms or suites) `start_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—service start date (for example, check-in date) in the `DD-MM-YYYY` format `end_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—service end date (for example, check-out date) in the `DD-MM-YYYY` format `guests`, array of objects—array of objects containing information about guests: `first_name`, string—first name of the guest `last_name`, string—last name of the guest `insurances`, array of objects—array of objects containing information about insurance services: `company`, string—name of the insurance company `insurance_type`, string—indicator of the insurance service type, can have one of the following values: `BANKRUPTCY`—bankruptcy insurance for the service provider `CANCELATION`—service cancellation insurance `EMERGENCY`—emergency insurance `MEDICAL`—medical insurance `amount`,—cost of the insurance service in the smallest units of currency specified in the `currency` parameter of this same object `currency`, string, `^[A-Z]{3}$`—currency code for the cost of the insurance service in the ISO-4217 alpha-3 format `price`, number—cost of the service in the smallest units of currency specified in the `currency` parameter of this same object `currency`, string, `^[A-Z]{3}$`—currency code in which the cost of the service is indicated, in the ISO-4217 alpha-3 format Detailed information about the voucher or gift certificate (for items of the `voucher` type) `company`, string—name of the organisation issuing the voucher or certificate `affiliate`, string—name of the partner organisation issuing the voucher or certificate `start_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—start date of the voucher or certificate in the `DD-MM-YYYY` format `end_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—end date of the voucher or certificate in the `DD-MM-YYYY` format `voucher_type`, string—indicator of the voucher or certificate type, can have one of the following values: `DIGITAL_PRODUCT`—voucher for a digital product `DISCOUNT`—voucher for a discount, specified as a percentage or a fixed numeric amount `GIFT_CARD`—gift certificate with a fixed denomination `PHYSICAL_PRODUCT`—voucher for a physical product `SERVICES`—voucher for receiving a service Detailed information about the insurance service (for items of the `insurance` type) `company`, string—name of the organisation providing the service `insurance_type`, string—indicator of the insurance service type, can have one of the following values: `BANKRUPTCY`—bankruptcy insurance for the service provider `CANCELATION`—service cancellation insurance `EMERGENCY`— emergency insurance `MEDICAL`—medical insurance `amount`, number—cost of the insurance service in the smallest units of currency specified in the `currency` parameter of the same object `currency`, string, `^[A-Z]{3}$`—currency code for the cost of the insurance service in the ISO-4217 alpha-3 format Detailed information about the event (for items of the `event` type) `event_type`, string—event type indicator that can have one of the following values: `CONCERT`—concert `CONFERENCE`—conference `DIGITAL_EDUCATION`—online educational event `EXPO`—exhibition `FESTIVAL`—festival `IN_PERSON_EDUCATION`—in-person educational event `SPORT`—sporting event `TOUR`—excursion or tour `company`, string—name of the organisation providing the service `affiliate`, string—name of the partner organisation providing the service `venue_name`, string—name of the event venue (for example, the name of a park or conference hall) `address`, string—basic information about the event venue's address in the form of a street name and a house number `address2`, string—additional information about the event venue address in the form of the name of the district, information additional to the house number or other information `city`, string—name of the city in the event venue's address `country`, string, `^[A-Z]{2}$`—country code in the event venue's address in the ISO 3166-1 alpha-2 format `postal`, string—postal code in the event venue address `region_code`, string, `^[0-9A-Z]{1,3}$`—internal region code (state, province, or other territorial area) in the event venue address, representing the second part of the international area code (in the ISO 3166-2 format), without the two-letter country code and separating hyphen `start_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—event start date in the `DD-MM-YYYY` format `end_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—event end date in the `DD-MM-YYYY` format `access_controlled`, boolean—indicator of the of digital access control to the service `insurances`, array of objects—array of objects containing information about insurance services: `company`, string—name of the insurance company `insurance_type`, string—indicator of the type of insurance service, can have one of the following values: `BANKRUPTCY`—bankruptcy insurance for the service provider `CANCELATION`—service cancellation insurance `EMERGENCY`—emergency insurance `MEDICAL`—medical insurance `amount`, number—cost of the insurance service in the smallest units of currency specified in the `currency` parameter of the same object `currency`, string, `^[A-Z]{3}$`—currency code for the cost of the insurance service in the ISO-4217 alpha-3 format Detailed information about a product or service provided as part of an on-demand subscription plan (for items of the `ondemand` type) `amount_min`, number—minimum allowable amount of a single debiting in the smallest units of currency specified in the `currency` parameter of the same object `amount_max`, number—maximum allowable amount of a single debiting in the smallest units of currency specified in the `currency` parameter of the same object `amount_average`, number—estimated average amount of a single debiting in the smallest units of currency specified in the `currency` parameter of the same object `currency`, string, `^[A-Z]{3}$`—currency code for an individual debiting in the ISO-4217 alpha-3 format `interval`, string—indicator that specifies debiting frequency, can have one of the following values: `DAY`—day `WEEK`—week `MONTH`—month `YEAR`—year `frequency`, number—multiplier to increase debiting frequency Detailed information about a product or service provided as part of a subscription plan with regular debiting (for items of the `subscription` type) `billing_plans`, array of objects—array of objects containing subscription information `amount`, number—amount of an individual debiting in the smallest units of currency specified in the `currency` parameter of the same object `currency`, string, `^[A-Z]{3}$`—currency code for an individual charge in the ISO-4217 alpha-3 format `interval`, string—indicator that specifies the basic debiting period, can have one of the following values: `DAY`—day `WEEK`—week `MONTH`—month `YEAR`—year `frequency`, number—multiplier to increase the basic debiting period `start_date`, string, `^\\d{2}-\\d{2}-\\d{4}$`—debiting start date in the `DD-MM-YYYY` format, starting from the day after the payment processing date `free_trial`, string—indicator of whether the trial period is active, can have one of the following values: `ACTIVE`—with trial period `INACTIVE`—no trial period `subscription_reference`, string—identifier of the service or the service type within the web service, can be non-unique (for example, `PREMIUM_MONTHLY`) Detailed information about a good or service on the marketplace (for items of the `marketplace` type) `seller`, object—object containing information about the seller on the marketplace: `name`, string—name or title of the seller on the marketplace `address`, string—basic information about the seller's address in the form of a street name and a house number `address2`, string—additional information about the seller in the form of the name of the district, information additional to the house number or other information `city`, string—name of the city where the seller is located `country`, string, `^[A-Z]{2}$`—country code of the seller's location in the ISO 3166-1 alpha-2 format `postal`, string—postal code of the seller's location `region_code`, string, `^[0-9A-Z]{1,3}$`—internal region code (state, province, or other territorial area) in the seller's address, representing the second part of the international area code (in the ISO 3166-2 format), without the two-letter country code and separating hyphen `rating`, string—seller's rating on the marketplace converted to one of the following values: `VERY_HIGH`—very high `HIGH`—high `MEDIUM`—medium `LOW`—low `VERY_LOW`—very low `registration`, string, `^\\d{2}-\\d{2}-\\d{4}$`—date of seller registration on the marketplace in the `DD-MM-YYYY` format `registration_updated`, string, `^\\d{2}-\\d{2}-\\d{4}$`—date of last change to seller information in the `DD-MM-YYYY` format `last_login`, string, `^\\d{2}-\\d{2}-\\d{4}$`—date of last seller authentication on the marketplace in the `DD-MM-YYYY` format `reference`, string—seller identifier on the marketplace `number_of_transactions`, number—number of payment operations via the intermediary through which the product is sold, over the last 12 months `volume_of_transactions`, number—amount of payment transactions with the intermediary through which the product is sold, over the last 12 months, in smallest currency units `product_category`, string—product or service category indicator, can have one of the following values: `ACCESSORIES`—accessories `APPLIANCES`—home appliances `APPS_AND_GAMES`—applications and games `ARTS_CRAFTS_AND_SEWING`—arts and crafts `AUTOMOTIVE`—car products `BEAUTY`—personal care products `BABY`—children's products `BABY_CLOTHING`—children's clothing `BAGS_AND_PURSES`—bags and purses `BOOKS`—books and other printed publications `CDS_AND_VINYL`—compact discs, vinyl records, and other physical media audio recordings `CELL_PHONES_AND_ACCESSORIES`—mobile phones and accessories `COLLECTIBLES_AND_FINE_ARTS`—art and collectibles `DIGITAL_MUSIC`—musical recordings in digital format `ELECTRONICS`—electronic devices `GROCERY_AND_GOURMET_FOOD`—grocery and gourmet foods `HANDMADE`—handmade products `HEALTH_AND_PERSONAL_CARE`—health and personal care products `HOME_AND_KITCHEN`—home and kitchen products `INDUSTRIAL_AND_SCIENTIFIC`—industrial and scientific equipment `LUGGAGE_AND_TRAVEL_GEAR`—luggage, travel accessories, and other travel products `MAGAZINE_SUBSCRIPTIONS`—subscriptions to print or digital periodicals `MEN_CLOTHING`—men's clothing `MUSICAL_INSTRUMENTS`—musical instruments `OFFICE_PRODUCTS`—office supplies `PATIO_LAWN_AND_GARDEN`—patio and garden supplies `PET_SUPPLIES`—pet supplies `SHOES`—shoes `SOFTWARE`—software `SPORTS_AND_OUTDOORS`—sports and outdoor supplies `TOOLS_AND_HOME_IMPROVEMENT`—construction tools and home improvement supplies `TOYS_AND_GAMES`—toys and games `VIDEO_GAMES`—video games `WOMEN_CLOTHING`—women's clothing `line_item_references`, array of strings—array of web service page URLs with product or service descriptions `shipping_references`, array of strings—array of strings with a list of shipping identifiers for purchased items within a web service or delivery service

Callback format

The Klarna method uses the standard format for callbacks to deliver purchase results. For more information, see Handling callbacks.

The following is the example of a callback with information about a 10.00 EUR purchase made in the 442 project.

Figure 25. Example of data in a purchase callback

{
        "project_id": 442,
        "payment": {
            "id": "EP696e-3aea",
            "type": "purchase",
            "status": "success",
            "date": "2022-10-07T19:28:58+0000",
            "method": "Klarna",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "12345"
        },
        "operation": {
            "id": 33,
            "type": "sale",
            "status": "success",
            "date": "2022-10-07T19:28:58+0000",
            "created_date": "2022-10-07T19:28:14+0000",
            "request_id": "a8ea69fdc5a83a2622-00000001",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 18052,
                "payment_id": "1665170919576",
                "auth_code": ""
            }
        },
        "signature": "h14kSk782IZEgezTRpbZVe/54KGgd7mA=="
    }

The following is the example of a callback with information about a declined purchase.

Figure 26. Example of data in a declined purchase callback

{
        "project_id": 442,
        "payment": {
            "id": "EP1d27-e7ee",
            "type": "purchase",
            "status": "decline",
            "date": "2022-10-10T09:28:33+0000",
            "method": "Klarna",
            "sum": {
                "amount": 1500000,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "12345"
        },
        "operation": {
            "id": 38,
            "type": "sale",
            "status": "decline",
            "date": "2022-10-10T09:28:33+0000",
            "created_date": "2022-10-10T09:28:19+0000",
            "request_id": "f56812a9270c19c04-00000001",
            "sum_initial": {
                "amount": 1500000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1500000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 18052,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "ZS90VEL4x5avOhc4MG85STSog=="
    }

Useful links

The following articles can be useful when implementing purchases via Payment Page:

Interaction concepts—how to organise interaction with the payment platform by using Payment Page
Signature generation and verification—about the procedure of creating and verifying signatures in requests and callbacks.
Payment processing—about the types, processing models, and possible statuses of supported payments and operations.
One-time one-step purchase—about processing of one-time one-step purchases by using Payment Page.
Handling operation processing information—about error and response codes that are used in the payment platform to record information about performing of operations.

Using payment inks

General information

This method allows to process purchases via payment links created by using Gate. General information about using payment links is presented in the Payment link purchases article. Specifics of the format of requests relevant to the Klarna are presented below.

Request format

When creating requests, you need to consider the following:

The request is sent by using POST (HTTP) method to /v2/payment/invoice/create.
The following objects and parameters must be specified in the request:
- Object general—general request identification information:
  - project_id—the project identifier obtained from Ecommpay when onboarding
  - payment_id—payment identifier that must be unique within the project
  - signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
- Object customer—customer information:
  - id—customer identifier in merchant's web service
  - ip_address—customer IP address relevant for the initiated payment
  - identify—information about the document which establishes identity:
  - doc_number—identifier of the document serving as a proof of identity for the customer, the format depends on the customer's country of registration:
    - Sweden—Personal Identity Number of the form YYYYMMDD-SSSS
    - Norway—National Identity Number of the form DDMMYYIIIKK
    - Italy—Fiscal Code of the form LLLLLLYYMMDDSSSC
    - Finland—Personal Identity Code of the form DDMMYYCZZZQ
    - Spain—National Identity Document of the form SSSSSSSSA
    - Denmark—Personal Identification Number of the form DDMMYY-SSSS
    - USA—Social Security Number, consists of 9 digits
  - doc_issue_country—code of the country where the document serving as a proof of the customer's identity was issued. Specified in the ISO 3166-1 alpha-2 format
  - Object account—information about the customer's account and contact details obtained by the web service:
    - date—account creation date in the DD-MM-YYYY format
    - loyalty_level—indicator of the customer's level in the merchant's web service loyalty program, converted to one of the following values (the parameter can be omitted if the purchase_history object is included in the account object):
      - 01—high
      - 02—medium
      - 03—low
- Object payment—payment information:
  - amount—payment amount in minor currency units
  - currency—payment currency in the ISO-4217 alpha-3 format
  - best_before—expiry date and time of the payment link in the following format: YYYY-MM-DDThh:mm:ss±hh:mm. Keep in mind that the validity period of the payment link cannot exceed 30 days.
To send the payment link via the Ecommpay payment platform, specify the following parameters:
- send_email—the indicator that communicates the need to send the link automatically (must be set to true).
- email (in the customer object)—the email of the customer to be used.
- language (in the customer object)—the code of the language to be used in the email. The parameter is required if the customer language is not English (used by default) and the email template in this language has been previously configured in the payment platform.
To send the payment link via your web service (and, thus, removing the option to send the email via the Ecommpay platform), pass the send_email parameter set to false.
The specific objects and parameters relevant to the Klarna method must be specified in the klarna object included in the payment_method_options object. These objects and parameters correspond to the ones used when for making purchase requests via Gate by using the Klarna method.
Figure 27. Klarna specific objects and parameters
- customer—customer information:
  - Object account—information about the customer's account and contact details obtained by the web service:
    - purchase_history—array of objects containing information about the customer's previous purchases (the parameter can be omitted if the purchase_history object is included in the account object):
      
      number_of_purchases—number of purchases made in the last 12 months
      
      number_of_paid_purchases—number of paid purchases in the last 12 months
      
      total_amount—total amount of purchases made in the last 12 months, in the smallest units of currency specified in the currency parameter the same object
      
      currency—currency code for the specified amount in the ISO-4217 alpha-3 format
      
      payment_method—indicator of the type of payment instrument used, can have one of the following values: 01—payment card of the payment system via which the payment is initiated, 02—account with support of direct debiting of funds, 03—mobile wallet, 04—payment card of another payment system, 999—other instrument
      
      first_purchase_at—date and time of the customer's first purchase in the web service in the DD-MM-YYYYhh:mm format
      
      last_purchase_at—date and time of the customer's first purchase in the web service in the DD-MM-YYYYhh:mm format
- Object purchase_data—information about line items in an order, array and can include various combinations of elements from the list of supported data:
  - positions—array, that contains information about line items, relevant to the purchase, must contain at least one object that includes the following parameters (for each item of goods or services):
    - type—indicator that specifies the type of a line item, that can have one of the following values, defining the composition of the required parameters to be specified in the positions object: discount—discount or promo code (for any goods or services), flight—air travel, car—car rental, bus—bus ride, ferry—ferry crossing, train—train ride, hotel—hotel accommodation, voucher—voucher or gift certificate, insurance—insurance, event—attending an event (for example a concert or exhibition), subscription—product or service provided as part of a subscription plan with regular debiting (for example, access to watching movies in an online cinema for a month), ondemand—product or service provided as part of an on-demand subscription plan (for example, watching a movie in an online cinema), marketplace—product or service provided via a marketplace, product—a product of a different category, service—a service of a different category, other—another type of service provided to the customer
    - name—name of the item
    - quantity—number of goods or services per item
    - amount_total—total cost of goods or services per item, in smallest currency units or as a hyphen (-) for items with the discount type
      The product, service, discount and other types require only the parameters type, name, quantity and amount_total.
  - Whether the following parameters are required to be specified in the positions array depends on the position type.
    The flight type requires the following:
    - departure—object that contains departure information:
      
      airport—three-letter code assigned to the departure airport by the International Air Transport Association (IATA)
      
      date—departure date in the DD-MM-YYYY format
      
      country—country code in the departure address in the ISO 3166-1 alpha-2 format
    - arrival—object that contains arrival information:
      
      airport—three-letter code assigned to the arrival airport by the International Air Transport Association (IATA)
      
      country—country code in the arrival address in the ISO 3166-1 alpha-2 format
    - passengers—array of objects containing passenger information:
      
      first_name—first name of the passenger
      
      last_name—last name of the passenger
    The car type requires the following:
    - departure—object that contains departure information:
      
      city—name of the city in the departure address
      
      country—country code in the departure address in the ISO 3166-1 alpha-2 format
    - arrival—object that contains arrival information:
      
      city—name of the city in the departure address
      
      country—country code in the departure address in the ISO 3166-1 alpha-2 format
    - passengers—array of objects containing passenger information:
      
      first_name—first name of the passenger
      
      last_name—last name of the passenger
    The bus, train, ferry types require the following:
    - departure—object that contains departure information:
      
      date—departure date in the DD-MM-YYYY format
      
      city—name of the city in the departure address
      
      country—country code in the departure address in the ISO 3166-1 alpha-2 format
    - arrival—object that contains arrival information:
      
      city—name of the city in the arrival address
      
      country—country code in the arrival address in the ISO 3166-1 alpha-2 format
    - passengers—array of objects containing passenger information:
      
      first_name—first name of the passenger
      
      last_name—last name of the passenger
    The hotel type requires the following:
    - hotel_name—name of the accommodation (for example, of a hotel or a hostel)
    - start_date—service start date (for example, check-in date) in the DD-MM-YYYY format
    - end_date—service end date (for example, check-out date) in the DD-MM-YYYY format
    - city—city name in the accommodation address
    - country—country code in the accommodation address in the ISO 3166-1 alpha-2 format
    - guests—array of objects containing information about guests:
      
      first_name—first name of the guest
      
      last_name—last name of the guest
    The voucher type requires the following:
    - start_date—start date of the voucher or certificate in the DD-MM-YYYY format
    - company—name of the organisation issuing the voucher or certificate
    The event type requires the following:
    - event_type—event type indicator that can have one of the following values: CONCERT—concert, FESTIVAL—festival, TOUR—excursion or tour, IN_PERSON_EDUCATION—in-person educational event, DIGITAL_EDUCATION—online educational event, SPORT—sporting event, CONFERENCE—conference, EXPO—exhibition.
    - start_date—event start date in the DD-MM-YYYY format
    - end_date—event end date in the DD-MM-YYYY format
    - country—country code in the event venue's address in the ISO 3166-1 alpha-2 format
    The subscription type requires the following:
    - billing_plans, array of objects—array of objects containing subscription information
      
      interval, string—indicator that specifies the basic debiting period, can have one of the following values:
      
      DAY—day
      
      WEEK—week
      
      MONTH—month
      
      YEAR—year
      
      start_date, string, ^\\d{2}-\\d{2}-\\d{4}$—debiting start date in the DD-MM-YYYY format, starting from the day after the payment processing date
      
      frequency, number—multiplier to increase the basic debiting period
    The ondemand type requires the following:
    - interval, string—indicator that specifies debiting frequency, can have one of the following values:
      
      DAY—day
      
      WEEK—week
      
      MONTH—month
      
      YEAR—year
    - frequency, number—multiplier to increase debiting frequency
    The marketplace type requires the following:
    - seller—object containing information about the seller on the marketplace:
      
      name—name or title of the seller on the marketplace
      
      city—name of the city where the seller is located
      
      country—country code of the seller's location in the ISO 3166-1 alpha-2 format
      
      registation—date of seller registration on the marketplace in the DD-MM-YYYY format
    - product_category—product or service category indicator, can have one of the following values:
      
      ACCESSORIES—accessories
      
      APPLIANCES—home appliances
      
      APPS_AND_GAMES—applications and games
      
      ARTS_CRAFTS_AND_SEWING—arts and crafts
      
      AUTOMOTIVE—car products
      
      BEAUTY—personal care products
      
      BABY—children's products
      
      BABY_CLOTHING—children's clothing
      
      BAGS_AND_PURSES—bags and purses
      
      BOOKS—books and other printed publications
      
      CDS_AND_VINYL—compact discs, vinyl records, and other physical media audio recordings
      
      CELL_PHONES_AND_ACCESSORIES—mobile phones and accessories
      
      COLLECTIBLES_AND_FINE_ARTS—art and collectibles
      
      DIGITAL_MUSIC—musical recordings in digital format
      
      ELECTRONICS—electronic devices
      
      GROCERY_AND_GOURMET_FOOD—grocery and gourmet foods
      
      HANDMADE—handmade products
      
      HEALTH_AND_PERSONAL_CARE—health and personal care products
      
      HOME_AND_KITCHEN—home and kitchen products
      
      INDUSTRIAL_AND_SCIENTIFIC—industrial and scientific equipment
      
      LUGGAGE_AND_TRAVEL_GEAR—luggage, travel accessories, and other travel products
      
      MAGAZINE_SUBSCRIPTIONS—subscriptions to print or digital periodicals
      
      MEN_CLOTHING—men's clothing
      
      MUSICAL_INSTRUMENTS—musical instruments
      
      OFFICE_PRODUCTS—office supplies
      
      PATIO_LAWN_AND_GARDEN—patio and garden supplies
      
      PET_SUPPLIES—pet supplies
      
      SHOES—shoes
      
      SOFTWARE—software
      
      SPORTS_AND_OUTDOORS—sports and outdoor supplies
      
      TOOLS_AND_HOME_IMPROVEMENT—construction tools and home improvement supplies
      
      TOYS_AND_GAMES—toys and games
      
      VIDEO_GAMES—video games
      
      WOMEN_CLOTHING—women's clothing
- additional—object containing additional information that may be relevant for payment processing:
  - integration_metadata, object—object containing information about how the payment was technically initiated:
    - originators, array of objects—array of objects containing information about the components used to initiate the payment (on the merchant's web service; up to six objects):
      
      name, string—name of the service via which the payment was initiated, in the form of uppercase letters, digits, and underscores (_) instead of spaces (for example, COSMO_GAMES_STORE)
      
      module_name, string—name of the technical module via which the payment was initiated, for example, cosmoshopPlugin
      
      module_version, string—version number of the technical module via which the payment was initiated, for example, 2.1
      
      session_reference, string—identifier of the operation or session within the web service, as a universally unique identifier version 7 (UUIDv7) in accordance with RFC 9562, for example, 018b163d-0b83-7ba0-b837-da575d0ff824
To increase acceptance rate and improve customer experience it is recommended to specify the following parameters in the additional object included in the payment_methods_options object:
- klarna_network_data—string object that contains specific information that can be used for ensuring interoperability between Klarna and it's partners. Information specified in this parameter can complement information specified in other parameters. The value length must be between 1 and 10240 characters (inclusive). The object must be formatted as follows:
```
"{\"content\":{\"customer_account_info\":[{\"unique_account_identifier\":\"test@example.com\",\"account_registration_date\":\"2017-02-13T10:49:20Z\",\"account_last_modified\":\"2019-03-13T11:45:27Z\"}]},\"content_type\":\"application/vnd.klarna.internal.emd-v2+json\"}"
```
- klarna_network_session_token—token received from a payment system or provider and intended for secure interaction within a session (for example, Klarna Network Session Token)
To ensure the user interface complies with Klarna service requirements, it is recommended to specify the customer address country code in the country parameter of the customer object. If the country code is not specified in the request or a code of a not officially supported country is specified, the English language can be used for displaying the Klarna service user interface, which may lead to a decrease in conversion rate.
Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Klarna method via a payment link must contain the project identifier, basic payment information (identifier, amount, and currency code), customer and line item information, as well as signature.

{
  "general": {
    "project_id": 123456,
    "payment_id": "PMT123456-789",
    "signature": "<signature>"
  },
  "payment": {
    "amount": 10000,
    "currency": "EUR",
    "description": "Order ORD123456-789",
    "best_before": "2026-03-08T09:00:00+03:00"
  },
  "customer": {
    "id": "cust-9001001",
    "first_name": "John",
    "last_name": "Smith",
    "phone": "31612345678",
    "street": "Herengracht",
    "address": "101",
    "state": "NH",
    "email": "john@example.com",
    "city": "Amsterdam",
    "country": "NL",
    "zip": "1015BG",
    "day_of_birth": "15-04-1985",
    "ip_address": "1.0.0.4",
    "identify": {
      "doc_number": "19850415-1234",
      "doc_issue_country": "SE"
    },
    "account": {
      "date": "10-02-2021",
      "change_date": "01-03-2026",
      "loyalty_level": "01",
      "auth_time": "09-03-202610:15",
      "auth_method": "021"
    }
  },
  "return_url": {
    "return": "https://example.com/echo/success"
  },
  "payment_methods_options": {
    "customer": {
      "account": {
        "purchase_history": [
          {
            "number_of_purchases": 18,
            "number_of_paid_purchases": 17,
            "number_of_disputed_purchases": 1,
            "total_amount": 845900,
            "currency": "EUR",
            "payment_method": "01",
            "first_purchase_at": "14-03-202309:40",
            "last_purchase_at": "01-03-202620:25"
          }
        ],
        "device_purchase_history": [
          {
            "number_of_purchases": 18,
            "number_of_paid_purchases": 17,
            "number_of_disputed_purchases": 1,
            "total_amount": 845900,
            "currency": "EUR",
            "payment_method": "01",
            "first_purchase_at": "14-03-202309:40",
            "last_purchase_at": "01-03-202620:25"
          }
        ]
      },
      "shipping_extended": [
        {
          "first_name": "John",
          "last_name": "Smith",
          "email": "john@example.com",
          "phone": "31612345678",
          "address": "Herengracht 101",
          "address2": "Herengracht 101",
          "postal": "1015BG",
          "city": "Amsterdam",
          "region_code": "NH",
          "country": "NL",
          "type": "011",
          "type_attributes": [
            "08",
            "01"
          ],
          "carrier": "PostNL",
          "shipping_reference": "SHIP-COMPUTER-1"
        },
        {
          "first_name": "Jane",
          "last_name": "Smith",
          "email": "jane@example.com",
          "phone": "31698765432",
          "address": "Keizersgracht 250",
          "address2": "Keizersgracht 250",
          "postal": "1016EV",
          "city": "Amsterdam",
          "region_code": "NH",
          "country": "NL",
          "type": "011",
          "type_attributes": [
            "08",
            "07",
            "02"
          ],
          "carrier": "DHL",
          "shipping_reference": "SHIP-COMPUTER-2"
        }
      ]
    },
    "purchase_data": {
      "positions": [
        {
          "type": "product",
          "name": "ExampleName",
          "quantity": 1,
          "amount_total": 189900,
          "tax_total": 32958,
          "amount": 189900,
          "product_url": "https://merchant.example.com",
          "product_image": "https://merchant.example.com",
          "product_reference": "SKU-LEN-X1G12",
          "item_reference": "ITEM-001",
          "shipping_reference": "SHIP-001"
        },
        {
          "type": "service",
          "name": "Extended Warranty 2 Years",
          "quantity": 1,
          "amount_total": 19900,
          "tax_total": 3458,
          "amount": 19900,
          "product_url": "https://merchant.example.com",
          "product_image": "https://merchant.example.com",
          "product_reference": "SVC-WARRANTY-2Y",
          "item_reference": "ITEM-002",
          "shipping_reference": "SHIP-001"
        },
        {
          "type": "discount",
          "name": "Summer Sale 10%",
          "quantity": 1,
          "amount_total": 20990,
          "tax_total": 3643,
          "amount": 20990,
          "item_reference": "ITEM-003"
        },
        {
          "type": "other",
          "name": "some",
          "quantity": 1,
          "amount_total": 20990,
          "tax_total": 3643,
          "amount": 20990,
          "item_reference": "ITEM-003"
        },
        {
          "type": "flight",
          "name": "Amsterdam → Stockholm",
          "quantity": 2,
          "amount_total": 45000,
          "tax_total": 7820,
          "amount": 22500,
          "item_reference": "ITEM-004",
          "booking_reference": "KL-20260601-AMS-ARN",
          "departure": {
            "airport": "AMS",
            "date": "01-06-2026",
            "city": "Amsterdam",
            "country": "NL"
          },
          "arrival": {
            "airport": "ARN",
            "city": "Stockholm",
            "country": "SE"
          },
          "airline": "KL",
          "price": 22500,
          "currency": "EUR",
          "class": "ECONOMY",
          "passengers": [
            {
              "first_name": "John",
              "last_name": "Smith"
            }
          ],
          "insurances": [
            {
              "company": "AXA",
              "insurance_type": "CANCELATION",
              "amount": 2500,
              "currency": "EUR"
            }
          ],
          "affiliate": "ExamplePartner BV"
        },
        {
          "type": "car",
          "name": "7 days rental",
          "quantity": 1,
          "amount_total": 35000,
          "tax_total": 6079,
          "amount": 35000,
          "item_reference": "ITEM-005",
          "departure": {
            "address": "Schiphol Airport",
            "address2": "Terminal 3",
            "postal": "1118CP",
            "city": "Amsterdam",
            "region_code": "NH",
            "country": "NL",
            "date": "15-06-2026"
          },
          "arrival": {
            "address": "Arlanda Airport",
            "address2": "Terminal 5",
            "postal": "19060",
            "city": "Stockholm",
            "region_code": "AB",
            "country": "SE"
          },
          "car_rental_company": "Hertz",
          "price": 35000,
          "currency": "EUR",
          "class": "ECONOMY",
          "passengers": [
            {
              "first_name": "John",
              "last_name": "Smith"
            }
          ],
          "insurances": [
            {
              "company": "Allianz",
              "insurance_type": "LOSS_DAMAGE_WAIVER",
              "amount": 1500,
              "currency": "EUR"
            }
          ],
          "affiliate": "example.com"
        },
        {
          "type": "bus",
          "name": "Amsterdam → Brussels Express",
          "quantity": 1,
          "amount_total": 2500,
          "tax_total": 434,
          "amount": 2500,
          "item_reference": "ITEM-006",
          "departure": {
            "date": "15-06-2026",
            "location": "Amsterdam",
            "address": "Orlyplein",
            "address2": "1",
            "postal": "1043DP",
            "city": "Amsterdam",
            "region_code": "NH",
            "country": "NL"
          },
          "arrival": {
            "address": "Rue du Progrès",
            "address2": "80",
            "postal": "1210",
            "city": "Brussels",
            "region_code": "BRU",
            "country": "BE"
          },
          "bus_company": "FlixBus",
          "price": 2500,
          "currency": "EUR",
          "class": "ECONOMY",
          "passengers": [
            {
              "first_name": "John",
              "last_name": "Smith"
            }
          ],
          "insurances": [
            {
              "company": "AXA",
              "insurance_type": "CANCELATION",
              "amount": 500,
              "currency": "EUR"
            }
          ],
          "affiliate": "example.eu"
        },
        {
          "type": "train",
          "name": "Amsterdam → Newcastle Ferry",
          "quantity": 2,
          "amount_total": 18000,
          "tax_total": 3127,
          "amount": 9000,
          "item_reference": "ITEM-007",
          "departure": {
            "date": "20-06-2026",
            "location": "IJmuiden",
            "address": "Sluisplein",
            "address2": "33",
            "postal": "1975AG",
            "city": "IJmuiden",
            "region_code": "NH",
            "country": "NL"
          },
          "arrival": {
            "address": "Royal Quays",
            "address2": "Coble Dene",
            "postal": "NE29 6EA",
            "city": "Newcastle",
            "region_code": "ENG",
            "country": "GB"
          },
          "train_company": "DFDS",
          "price": 9000,
          "currency": "EUR",
          "class": "PREMIUM_ECONOMY",
          "passengers": [
            {
              "first_name": "John",
              "last_name": "Smith"
            },
            {
              "first_name": "Jane",
              "last_name": "Smith"
            }
          ],
          "insurances": [
            {
              "company": "Allianz",
              "insurance_type": "CANCELATION",
              "amount": 1000,
              "currency": "EUR"
            }
          ],
          "affiliate": "example.eu"
        },
        {
          "type": "ferry",
          "name": "Amsterdam → Newcastle Ferry",
          "quantity": 2,
          "amount_total": 18000,
          "tax_total": 3127,
          "amount": 9000,
          "item_reference": "ITEM-007",
          "departure": {
            "date": "20-06-2026",
            "location": "IJmuiden Ferry",
            "address": "Sluisplein",
            "address2": "33",
            "postal": "1975AG",
            "city": "IJmuiden",
            "region_code": "NH",
            "country": "NL"
          },
          "arrival": {
            "address": "Royal Quays, Coble Dene",
            "address2": "Royal Quays, Coble Dene",
            "postal": "NE29 6EA",
            "city": "Newcastle",
            "region_code": "ENG",
            "country": "GB"
          },
          "ferry_line": "DFDS",
          "price": 9000,
          "currency": "EUR",
          "class": "PREMIUM_ECONOMY",
          "passengers": [
            {
              "first_name": "John",
              "last_name": "Smith"
            }
          ],
          "insurances": [
            {
              "company": "Allianz",
              "insurance_type": "CANCELATION",
              "amount": 1000,
              "currency": "EUR"
            }
          ],
          "affiliate": "example.eu"
        },
        {
          "type": "hotel",
          "name": "Hotel 1",
          "quantity": 1,
          "amount_total": 75000,
          "tax_total": 13025,
          "amount": 75000,
          "item_reference": "ITEM-008",
          "hotel_name": "Hotel",
          "start_date": "01-06-2026",
          "end_date": "04-06-2026",
          "address": "Nes",
          "address2": "49",
          "postal": "1012KD",
          "city": "Amsterdam",
          "region_code": "NH",
          "country": "NL",
          "lodging_type": "ROOM",
          "rooms": 1,
          "price": 25000,
          "currency": "EUR",
          "guests": [
            {
              "first_name": "John",
              "last_name": "Smith"
            },
            {
              "first_name": "Jane",
              "last_name": "Smith"
            }
          ],
          "host": {
            "host_reference": "HOST-0042",
            "type": "HOTEL",
            "country": "NL",
            "registration_date": "12-01-2015",
            "reservations": 312
          },
          "insurances": [
            {
              "company": "Europ",
              "insurance_type": "CANCELATION",
              "amount": 3000,
              "currency": "EUR"
            }
          ],
          "affiliate": "example.com"
        },
        {
          "type": "voucher",
          "name": "Gift Card",
          "quantity": 1,
          "amount_total": 5000,
          "tax_total": 869,
          "amount": 5000,
          "item_reference": "ITEM-009",
          "start_date": "01-06-2026",
          "end_date": "01-06-2027",
          "voucher_type": "GIFT_CARD",
          "company": "example.com",
          "affiliate": "example.nl"
        },
        {
          "type": "insurance",
          "name": "Travel",
          "quantity": 1,
          "amount_total": 4500,
          "tax_total": 782,
          "item_reference": "ITEM-010",
          "company": "AXA",
          "insurance_type": "MEDICAL",
          "amount": 4500,
          "currency": "EUR"
        },
        {
          "type": "event",
          "name": "Dance Event",
          "quantity": 2,
          "amount_total": 15000,
          "tax_total": 2607,
          "amount": 7500,
          "item_reference": "ITEM-011",
          "company": "ID&T",
          "event_type": "FESTIVAL",
          "start_date": "14-10-2026",
          "end_date": "18-10-2026",
          "venue_name": "Example Dome",
          "access_controlled": true,
          "address": "De Passage 100",
          "address2": "De Passage 100",
          "postal": "1101AX",
          "city": "Amsterdam",
          "region_code": "NH",
          "country": "NL",
          "insurances": [
            {
              "company": "AXA",
              "insurance_type": "CANCELATION",
              "amount": 1500,
              "currency": "EUR"
            }
          ],
          "affiliate": "example.nl"
        },
        {
          "type": "marketplace",
          "name": "Jacket",
          "quantity": 1,
          "amount_total": 12500,
          "tax_total": 2172,
          "amount": 12500,
          "product_url": "https://marketplace.example.com",
          "product_image": "https://marketplace.example.com",
          "product_reference": "SKU-VLJ-001",
          "item_reference": "ITEM-014",
          "shipping_reference": "SHIP-002",
          "seller": {
            "reference": "SELLER-7890",
            "name": "BV",
            "address": "263",
            "address2": "123",
            "postal": "1016GV",
            "city": "Amsterdam",
            "region_code": "NH",
            "country": "NL",
            "registration": "15-03-2019",
            "registration_updated": "10-01-2025",
            "last_login": "16-04-2026",
            "rating": "HIGH"
          },
          "product_category": "WOMEN_CLOTHING",
          "line_item_references": [
            "ITEM-014"
          ],
          "shipping_references": [
            "SHIP-002"
          ],
          "number_of_transactions": 145,
          "volume_of_transactions": 1875000
        }
      ]
    },
    "additional": {
      "integration_metadata": {
        "originators": [
          {
            "moduleName": "cosmoshopPlugin",
            "moduleVersion": "2.1",
            "name": "COSMO_GAMES_STORE",
            "session_reference": "018b163d-0b83-7ba0-b837-da575d0ff824"
          }
        ]
      },
      "klarna_network_session_token": "krn:network:eu1:test:session-token:eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImY0ZThhZTBjLWQyNjYtNDY0Zi05OWNjLWYyNjcyYmVjOWJiNCJ9.eyJzaG9wcGluZ19zZXNzaW9uX2lkIjoia3JuOnNob3BwaW5nOmV1MTp0ZXN0OnNlc3Npb246OWRiNDM5M2YtMmJjMC00MDk3LWFlMjgtOWFiYzA5NTk5MjcyIiwicGF5bWVudF9yZXF1ZXN0cyI6W10sInByZV9xdWFsaWZpY2F0aW9uIjp7fSwiaXNzIjoic2Vzc2lvbi1hY3F1aXJpbmctc2VydmljZSIsInZlciI6IjEuMC4wIiwiaWF0IjoxNzg2MDExMTYyLCJleHAiOjE3ODYwMTQ3NjJ9.V7rciwYKNPUb-4B_-sJ7dWVRkSTNcCmdwdf1_WQn5ZfjVEKh5Ua_gDUXAQRaHilB8JLM0YODQXcAdy81ONLTfQ",
      "klarna_network_data": "{\"content_type\":\"vnd.klarna.network-data.v2+json\",\"content\":{\"operation\":\"payment_request\",\"request\":{\"supplementary_purchase_data\":{\"purchase_reference\":\"KLARNA_SALE_ORDER_ID_2026_06_15_12_17_06_054808_5RxIU\",\"customer\":{\"identity_identification\":{\"number\":\"198504******1234\",\"country\":\"SE\"},\"customer_account\":{\"loyalty_level\":\"HIGH\",\"created_at\":\"2021-02-10T09:17:12Z\"},\"customer_device\":{\"ip_address\":\"1.0.0.4\"}},\"line_items\":[{\"name\":\"Lenovo ThinkPad X1 Carbon Gen 12\",\"quantity\":1,\"total_amount\":189900}]}}}}"
    }
  }
}

Figure 28. Example of sufficient data in a purchase request

{
  "general": {
    "project_id": 123456,
    "payment_id": "PMT123456-789",
    "signature": "<signature>"
  },
  "payment": {
    "amount": 10000,
    "currency": "EUR",
    "description": "Order ORD123456-789",
    "best_before": "2026-03-08T09:00:00+03:00"
  },
  "customer": {
    "id": "cust-9001001",
    "first_name": "John",
    "last_name": "Smith",
    "phone": "31612345678",
    "street": "Herengracht",
    "address": "101",
    "state": "NH",
    "email": "john@example.com",
    "city": "Amsterdam",
    "country": "NL",
    "zip": "1015BG",
    "day_of_birth": "15-04-1985",
    "ip_address": "1.0.0.4",
    "identify": {
      "doc_number": "19850415-1234",
      "doc_issue_country": "SE"
    },
    "account": {
      "date": "10-02-2021",
      "change_date": "01-03-2026",
      "loyalty_level": "01",
      "auth_time": "09-03-202610:15",
      "auth_method": "021"
    }
  },
  "return_url": {
    "return": "https://example.com/echo/success"
  },
  "payment_methods_options": {
    "customer": {
      "account": {
        "purchase_history": [
          {
            "number_of_purchases": 18,
            "number_of_paid_purchases": 17,
            "number_of_disputed_purchases": 1,
            "total_amount": 845900,
            "currency": "EUR",
            "payment_method": "01",
            "first_purchase_at": "14-03-202309:40",
            "last_purchase_at": "01-03-202620:25"
          }
        ],
        "device_purchase_history": [
          {
            "number_of_purchases": 18,
            "number_of_paid_purchases": 17,
            "number_of_disputed_purchases": 1,
            "total_amount": 845900,
            "currency": "EUR",
            "payment_method": "01",
            "first_purchase_at": "14-03-202309:40",
            "last_purchase_at": "01-03-202620:25"
          }
        ]
      },
      "shipping_extended": [
        {
          "first_name": "John",
          "last_name": "Smith",
          "email": "john@example.com",
          "phone": "31612345678",
          "address": "Herengracht 101",
          "address2": "Herengracht 101",
          "postal": "1015BG",
          "city": "Amsterdam",
          "region_code": "NH",
          "country": "NL",
          "type": "011",
          "type_attributes": [
            "08",
            "01"
          ],
          "carrier": "PostNL",
          "shipping_reference": "SHIP-COMPUTER-1"
        },
        {
          "first_name": "Jane",
          "last_name": "Smith",
          "email": "jane@example.com",
          "phone": "31698765432",
          "address": "Keizersgracht 250",
          "address2": "Keizersgracht 250",
          "postal": "1016EV",
          "city": "Amsterdam",
          "region_code": "NH",
          "country": "NL",
          "type": "011",
          "type_attributes": [
            "08",
            "07",
            "02"
          ],
          "carrier": "DHL",
          "shipping_reference": "SHIP-COMPUTER-2"
        }
      ]
    },
    "purchase_data": {
      "positions": [
        {
          "type": "product",
          "name": "ExampleName",
          "quantity": 1,
          "amount_total": 189900,
          "tax_total": 32958,
          "amount": 189900,
          "product_url": "https://merchant.example.com",
          "product_image": "https://merchant.example.com",
          "product_reference": "SKU-LEN-X1G12",
          "item_reference": "ITEM-001",
          "shipping_reference": "SHIP-001"
        },
        {
          "type": "service",
          "name": "Extended Warranty 2 Years",
          "quantity": 1,
          "amount_total": 19900,
          "tax_total": 3458,
          "amount": 19900,
          "product_url": "https://merchant.example.com",
          "product_image": "https://merchant.example.com",
          "product_reference": "SVC-WARRANTY-2Y",
          "item_reference": "ITEM-002",
          "shipping_reference": "SHIP-001"
        },
        {
          "type": "discount",
          "name": "Summer Sale 10%",
          "quantity": 1,
          "amount_total": 20990,
          "tax_total": 3643,
          "amount": 20990,
          "item_reference": "ITEM-003"
        },
        {
          "type": "other",
          "name": "some",
          "quantity": 1,
          "amount_total": 20990,
          "tax_total": 3643,
          "amount": 20990,
          "item_reference": "ITEM-003"
        },
        {
          "type": "flight",
          "name": "Amsterdam → Stockholm",
          "quantity": 2,
          "amount_total": 45000,
          "tax_total": 7820,
          "amount": 22500,
          "item_reference": "ITEM-004",
          "booking_reference": "KL-20260601-AMS-ARN",
          "departure": {
            "airport": "AMS",
            "date": "01-06-2026",
            "city": "Amsterdam",
            "country": "NL"
          },
          "arrival": {
            "airport": "ARN",
            "city": "Stockholm",
            "country": "SE"
          },
          "airline": "KL",
          "price": 22500,
          "currency": "EUR",
          "class": "ECONOMY",
          "passengers": [
            {
              "first_name": "John",
              "last_name": "Smith"
            }
          ],
          "insurances": [
            {
              "company": "AXA",
              "insurance_type": "CANCELATION",
              "amount": 2500,
              "currency": "EUR"
            }
          ],
          "affiliate": "ExamplePartner BV"
        },
        {
          "type": "car",
          "name": "7 days rental",
          "quantity": 1,
          "amount_total": 35000,
          "tax_total": 6079,
          "amount": 35000,
          "item_reference": "ITEM-005",
          "departure": {
            "address": "Schiphol Airport",
            "address2": "Terminal 3",
            "postal": "1118CP",
            "city": "Amsterdam",
            "region_code": "NH",
            "country": "NL",
            "date": "15-06-2026"
          },
          "arrival": {
            "address": "Arlanda Airport",
            "address2": "Terminal 5",
            "postal": "19060",
            "city": "Stockholm",
            "region_code": "AB",
            "country": "SE"
          },
          "car_rental_company": "Hertz",
          "price": 35000,
          "currency": "EUR",
          "class": "ECONOMY",
          "passengers": [
            {
              "first_name": "John",
              "last_name": "Smith"
            }
          ],
          "insurances": [
            {
              "company": "Allianz",
              "insurance_type": "LOSS_DAMAGE_WAIVER",
              "amount": 1500,
              "currency": "EUR"
            }
          ],
          "affiliate": "example.com"
        },
        {
          "type": "bus",
          "name": "Amsterdam → Brussels Express",
          "quantity": 1,
          "amount_total": 2500,
          "tax_total": 434,
          "amount": 2500,
          "item_reference": "ITEM-006",
          "departure": {
            "date": "15-06-2026",
            "location": "Amsterdam",
            "address": "Orlyplein",
            "address2": "1",
            "postal": "1043DP",
            "city": "Amsterdam",
            "region_code": "NH",
            "country": "NL"
          },
          "arrival": {
            "address": "Rue du Progrès",
            "address2": "80",
            "postal": "1210",
            "city": "Brussels",
            "region_code": "BRU",
            "country": "BE"
          },
          "bus_company": "FlixBus",
          "price": 2500,
          "currency": "EUR",
          "class": "ECONOMY",
          "passengers": [
            {
              "first_name": "John",
              "last_name": "Smith"
            }
          ],
          "insurances": [
            {
              "company": "AXA",
              "insurance_type": "CANCELATION",
              "amount": 500,
              "currency": "EUR"
            }
          ],
          "affiliate": "example.eu"
        },
        {
          "type": "train",
          "name": "Amsterdam → Newcastle Ferry",
          "quantity": 2,
          "amount_total": 18000,
          "tax_total": 3127,
          "amount": 9000,
          "item_reference": "ITEM-007",
          "departure": {
            "date": "20-06-2026",
            "location": "IJmuiden",
            "address": "Sluisplein",
            "address2": "33",
            "postal": "1975AG",
            "city": "IJmuiden",
            "region_code": "NH",
            "country": "NL"
          },
          "arrival": {
            "address": "Royal Quays",
            "address2": "Coble Dene",
            "postal": "NE29 6EA",
            "city": "Newcastle",
            "region_code": "ENG",
            "country": "GB"
          },
          "train_company": "DFDS",
          "price": 9000,
          "currency": "EUR",
          "class": "PREMIUM_ECONOMY",
          "passengers": [
            {
              "first_name": "John",
              "last_name": "Smith"
            },
            {
              "first_name": "Jane",
              "last_name": "Smith"
            }
          ],
          "insurances": [
            {
              "company": "Allianz",
              "insurance_type": "CANCELATION",
              "amount": 1000,
              "currency": "EUR"
            }
          ],
          "affiliate": "example.eu"
        },
        {
          "type": "ferry",
          "name": "Amsterdam → Newcastle Ferry",
          "quantity": 2,
          "amount_total": 18000,
          "tax_total": 3127,
          "amount": 9000,
          "item_reference": "ITEM-007",
          "departure": {
            "date": "20-06-2026",
            "location": "IJmuiden Ferry",
            "address": "Sluisplein",
            "address2": "33",
            "postal": "1975AG",
            "city": "IJmuiden",
            "region_code": "NH",
            "country": "NL"
          },
          "arrival": {
            "address": "Royal Quays, Coble Dene",
            "address2": "Royal Quays, Coble Dene",
            "postal": "NE29 6EA",
            "city": "Newcastle",
            "region_code": "ENG",
            "country": "GB"
          },
          "ferry_line": "DFDS",
          "price": 9000,
          "currency": "EUR",
          "class": "PREMIUM_ECONOMY",
          "passengers": [
            {
              "first_name": "John",
              "last_name": "Smith"
            }
          ],
          "insurances": [
            {
              "company": "Allianz",
              "insurance_type": "CANCELATION",
              "amount": 1000,
              "currency": "EUR"
            }
          ],
          "affiliate": "example.eu"
        },
        {
          "type": "hotel",
          "name": "Hotel 1",
          "quantity": 1,
          "amount_total": 75000,
          "tax_total": 13025,
          "amount": 75000,
          "item_reference": "ITEM-008",
          "hotel_name": "Hotel",
          "start_date": "01-06-2026",
          "end_date": "04-06-2026",
          "address": "Nes",
          "address2": "49",
          "postal": "1012KD",
          "city": "Amsterdam",
          "region_code": "NH",
          "country": "NL",
          "lodging_type": "ROOM",
          "rooms": 1,
          "price": 25000,
          "currency": "EUR",
          "guests": [
            {
              "first_name": "John",
              "last_name": "Smith"
            },
            {
              "first_name": "Jane",
              "last_name": "Smith"
            }
          ],
          "host": {
            "host_reference": "HOST-0042",
            "type": "HOTEL",
            "country": "NL",
            "registration_date": "12-01-2015",
            "reservations": 312
          },
          "insurances": [
            {
              "company": "Europ",
              "insurance_type": "CANCELATION",
              "amount": 3000,
              "currency": "EUR"
            }
          ],
          "affiliate": "example.com"
        },
        {
          "type": "voucher",
          "name": "Gift Card",
          "quantity": 1,
          "amount_total": 5000,
          "tax_total": 869,
          "amount": 5000,
          "item_reference": "ITEM-009",
          "start_date": "01-06-2026",
          "end_date": "01-06-2027",
          "voucher_type": "GIFT_CARD",
          "company": "example.com",
          "affiliate": "example.nl"
        },
        {
          "type": "insurance",
          "name": "Travel",
          "quantity": 1,
          "amount_total": 4500,
          "tax_total": 782,
          "item_reference": "ITEM-010",
          "company": "AXA",
          "insurance_type": "MEDICAL",
          "amount": 4500,
          "currency": "EUR"
        },
        {
          "type": "event",
          "name": "Dance Event",
          "quantity": 2,
          "amount_total": 15000,
          "tax_total": 2607,
          "amount": 7500,
          "item_reference": "ITEM-011",
          "company": "ID&T",
          "event_type": "FESTIVAL",
          "start_date": "14-10-2026",
          "end_date": "18-10-2026",
          "venue_name": "Example Dome",
          "access_controlled": true,
          "address": "De Passage 100",
          "address2": "De Passage 100",
          "postal": "1101AX",
          "city": "Amsterdam",
          "region_code": "NH",
          "country": "NL",
          "insurances": [
            {
              "company": "AXA",
              "insurance_type": "CANCELATION",
              "amount": 1500,
              "currency": "EUR"
            }
          ],
          "affiliate": "example.nl"
        },
        {
          "type": "marketplace",
          "name": "Jacket",
          "quantity": 1,
          "amount_total": 12500,
          "tax_total": 2172,
          "amount": 12500,
          "product_url": "https://marketplace.example.com",
          "product_image": "https://marketplace.example.com",
          "product_reference": "SKU-VLJ-001",
          "item_reference": "ITEM-014",
          "shipping_reference": "SHIP-002",
          "seller": {
            "reference": "SELLER-7890",
            "name": "BV",
            "address": "263",
            "address2": "123",
            "postal": "1016GV",
            "city": "Amsterdam",
            "region_code": "NH",
            "country": "NL",
            "registration": "15-03-2019",
            "registration_updated": "10-01-2025",
            "last_login": "16-04-2026",
            "rating": "HIGH"
          },
          "product_category": "WOMEN_CLOTHING",
          "line_item_references": [
            "ITEM-014"
          ],
          "shipping_references": [
            "SHIP-002"
          ],
          "number_of_transactions": 145,
          "volume_of_transactions": 1875000
        }
      ]
    },
    "additional": {
      "integration_metadata": {
        "originators": [
          {
            "moduleName": "cosmoshopPlugin",
            "moduleVersion": "2.1",
            "name": "COSMO_GAMES_STORE",
            "session_reference": "018b163d-0b83-7ba0-b837-da575d0ff824"
          }
        ]
      },
      "klarna_network_session_token": "krn:network:eu1:test:session-token:eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImY0ZThhZTBjLWQyNjYtNDY0Zi05OWNjLWYyNjcyYmVjOWJiNCJ9.eyJzaG9wcGluZ19zZXNzaW9uX2lkIjoia3JuOnNob3BwaW5nOmV1MTp0ZXN0OnNlc3Npb246OWRiNDM5M2YtMmJjMC00MDk3LWFlMjgtOWFiYzA5NTk5MjcyIiwicGF5bWVudF9yZXF1ZXN0cyI6W10sInByZV9xdWFsaWZpY2F0aW9uIjp7fSwiaXNzIjoic2Vzc2lvbi1hY3F1aXJpbmctc2VydmljZSIsInZlciI6IjEuMC4wIiwiaWF0IjoxNzg2MDExMTYyLCJleHAiOjE3ODYwMTQ3NjJ9.V7rciwYKNPUb-4B_-sJ7dWVRkSTNcCmdwdf1_WQn5ZfjVEKh5Ua_gDUXAQRaHilB8JLM0YODQXcAdy81ONLTfQ",
      "klarna_network_data": "{\"content_type\":\"vnd.klarna.network-data.v2+json\",\"content\":{\"operation\":\"payment_request\",\"request\":{\"supplementary_purchase_data\":{\"purchase_reference\":\"KLARNA_SALE_ORDER_ID_2026_06_15_12_17_06_054808_5RxIU\",\"customer\":{\"identity_identification\":{\"number\":\"198504******1234\",\"country\":\"SE\"},\"customer_account\":{\"loyalty_level\":\"HIGH\",\"created_at\":\"2021-02-10T09:17:12Z\"},\"customer_device\":{\"ip_address\":\"1.0.0.4\"}},\"line_items\":[{\"name\":\"Lenovo ThinkPad X1 Carbon Gen 12\",\"quantity\":1,\"total_amount\":189900}]}}}}"
    }
  }
}

Purchases by using Gate

General information

To process a purchase through Gate by using the Klarna method, the merchant's web service is required to do the following:

Send a request with all the required parameters and signature to the Ecommpay URL.
Receive an intermediate callback from the payment platform and redirect the customer to the Klarna service.
Receive the final callback from the payment platform.

Klarna method allows customers to use the following payment options Pay in full, Pay in 3, Pay in 4, Pay in 30 days, Financing / Pay over time. The full sequence and special aspects of purchase processing are provided below.

Figure 29. Purchase processing by using Gate: step-by-step description

A customer initiates a purchase by using the Klarna method in the web service.
The web service sends the request for processing the purchase by using Gate to the specified Ecommpay URL.
The payment platform receives the request.
The payment platform validates the required parameters and signature in the request.
The payment platform sends the response to the web service with information about the receipt of the request and its validity (details).
The payment platform performs further processing of the request (with parameter consistency check) and sends it to the Klarna service.
The request is processed on the Klarna service side.
The Klarna service sends the redirection data to the payment platform.
The payment platform sends the callback with the redirection data to the web service.
The customer is redirected to the Klarna service.
The customer completes all required payment steps.
The purchase is processed on the side of the Klarna service.
The result is displayed to the customer.
The customer is redirected to the web service.
The Klarna service sends the payment result notification to the payment platform.
The payment platform sends the payment result callback to the web service.
The customer receives the payment result information from the web service.

Information about the formats of requests and callbacks used for processing payments by using the Klarna method via Gate is presented further in this section. General information about working with the Gate API is presented in Interaction concepts.

Format of requests for purchase processing

There are several things you need to consider when sending purchase requests for by using the Klarna method:

To initiate each purchase, send a separate POST request to one of the following endpoints:
- /v2/payment/klarna/sale for one-step purchases
- /v2/payment/klarna/auth for two-step purchases
Each request must include the following objects and parameters:
- Object general—general purchase information:
  - project_id—project identifier obtained from Ecommpay during integration
  - payment_id—payment identifier unique within the project
  - signature—request signature generated after all required parameters are specified (details—in the Signature generation and verification) (details)
- Object payment—payment information:
  - amount—payment amount in the smallest currency unit
  - currency—payment currency code in the ISO-4217 alpha-3 format
- Object customer—customer information:
  - id—customer identifier unique within the project
  - ip_address—customer IP address relevant for the initiated payment
  - identify—information about the document which establishes identity:
    - doc_number—identifier of the document serving as a proof of identity for the customer, the format depends on the customer's country of registration:
      - Sweden—Personal Identity Number of the form YYYYMMDD-SSSS
      - Norway—National Identity Number of the form DDMMYYIIIKK
      - Italy—Fiscal Code of the form LLLLLLYYMMDDSSSC
      - Finland—Personal Identity Code of the form DDMMYYCZZZQ
      - Spain—National Identity Document of the form SSSSSSSSA
      - Denmark—Personal Identification Number of the form DDMMYY-SSSS
      - USA—Social Security Number, consists of 9 digits
  - doc_issue_country—code of the country where the document serving as a proof of the customer's identity was issued. Specified in the ISO 3166-1 alpha-2 format
  - Object account—information about the customer's account and contact details obtained by the web service:
    - date—account creation date in the DD-MM-YYYY format
    - loyalty_level—indicator of the customer's level in the merchant's web service loyalty program, converted to one of the following values (the parameter can be omitted if the purchase_history object is included in the account object):
      - 01—high
      - 02—medium
      - 03—low
    - purchase_history—array of objects containing information about the customer's previous purchases (the parameter can be omitted if the purchase_history object is included in the account object):
      - number_of_purchases—number of purchases made in the last 12 months
      - number_of_paid_purchases—number of paid purchases in the last 12 months
      - total_amount—total amount of purchases made in the last 12 months, in the smallest units of currency specified in the currency parameter the same object
      - currency—currency code for the specified amount in the ISO-4217 alpha-3 format
      - payment_method—indicator of the type of payment instrument used, can have one of the following values: 01—payment card of the payment system via which the payment is initiated, 02—account with support of direct debiting of funds, 03—mobile wallet, 04—payment card of another payment system, 999—other instrument
      - first_purchase_at—date and time of the customer's first purchase in the web service in the DD-MM-YYYYhh:mm format
      - last_purchase_at—date and time of the customer's first purchase in the web service in the DD-MM-YYYYhh:mm format
- Object purchase_data—information about line items in an order, array and can include various combinations of elements from the list of supported data:
  - positions—array, that contains information about line items, relevant to the purchase, must contain at least one object that includes the following parameters (for each item of goods or services):
    - type—indicator that specifies the type of a line item, that can have one of the following values, defining the composition of the required parameters to be specified in the positions object: discount—discount or promo code (for any goods or services), flight—air travel, car—car rental, bus—bus ride, ferry—ferry crossing, train—train ride, hotel—hotel accommodation, voucher—voucher or gift certificate, insurance—insurance, event—attending an event (for example a concert or exhibition), subscription—product or service provided as part of a subscription plan with regular debiting (for example, access to watching movies in an online cinema for a month), ondemand—product or service provided as part of an on-demand subscription plan (for example, watching a movie in an online cinema), marketplace—product or service provided via a marketplace, product—a product of a different category, service—a service of a different category, other—another type of service provided to the customer
    - name—name of the item
    - quantity—number of goods or services per item
    - amount_total—total cost of goods or services per item, in smallest currency units or as a hyphen (-) for items with the discount type
      The product, service, discount and other types require only the parameters type, name, quantity and amount_total.
  - Whether the following parameters are required to be specified in the positions array depends on the position type.
    Figure 30. flight
    - departure—object that contains departure information:
      
      airport—three-letter code assigned to the departure airport by the International Air Transport Association (IATA)
      
      date—departure date in the DD-MM-YYYY format
      
      country—country code in the departure address in the ISO 3166-1 alpha-2 format
    - arrival—object that contains arrival information:
      
      airport—three-letter code assigned to the arrival airport by the International Air Transport Association (IATA)
      
      country—country code in the arrival address in the ISO 3166-1 alpha-2 format
    - passengers—array of objects containing passenger information:
      
      first_name—first name of the passenger
      
      last_name—last name of the passenger
    Figure 31. car
    - departure—object that contains departure information:
      
      city—name of the city in the departure address
      
      country—country code in the departure address in the ISO 3166-1 alpha-2 format
    - arrival—object that contains arrival information:
      
      city—name of the city in the departure address
      
      country—country code in the departure address in the ISO 3166-1 alpha-2 format
    - passengers—array of objects containing passenger information:
      
      first_name—first name of the passenger
      
      last_name—last name of the passenger
    Figure 32. bus, train, ferry
    - departure—object that contains departure information:
      
      date—departure date in the DD-MM-YYYY format
      
      city—name of the city in the departure address
      
      country—country code in the departure address in the ISO 3166-1 alpha-2 format
    - arrival—object that contains arrival information:
      
      city—name of the city in the arrival address
      
      country—country code in the arrival address in the ISO 3166-1 alpha-2 format
    - passengers—array of objects containing passenger information:
      
      first_name—first name of the passenger
      
      last_name—last name of the passenger
    Figure 33. hotel
    - hotel_name—name of the accommodation (for example, of a hotel or a hostel)
    - start_date—service start date (for example, check-in date) in the DD-MM-YYYY format
    - end_date—service end date (for example, check-out date) in the DD-MM-YYYY format
    - city—city name in the accommodation address
    - country—country code in the accommodation address in the ISO 3166-1 alpha-2 format
    - guests—array of objects containing information about guests:
      
      first_name—first name of the guest
      
      last_name—last name of the guest
    Figure 34. voucher
    - start_date—start date of the voucher or certificate in the DD-MM-YYYY format
    - company—name of the organisation issuing the voucher or certificate
    Figure 35. event
    - event_type—event type indicator that can have one of the following values: CONCERT—concert, FESTIVAL—festival, TOUR—excursion or tour, IN_PERSON_EDUCATION—in-person educational event, DIGITAL_EDUCATION—online educational event, SPORT—sporting event, CONFERENCE—conference, EXPO—exhibition.
    - start_date—event start date in the DD-MM-YYYY format
    - end_date—event end date in the DD-MM-YYYY format
    - country—country code in the event venue's address in the ISO 3166-1 alpha-2 format
    Figure 36. subscription
    - billing_plans, array of objects—array of objects containing subscription information
      
      interval, string—indicator that specifies the basic debiting period, can have one of the following values:
      
      DAY—day
      
      WEEK—week
      
      MONTH—month
      
      YEAR—year
      
      start_date, string, ^\\d{2}-\\d{2}-\\d{4}$—debiting start date in the DD-MM-YYYY format, starting from the day after the payment processing date
      
      frequency, number—multiplier to increase the basic debiting period
    Figure 37. ondemand
    - interval, string—indicator that specifies debiting frequency, can have one of the following values:
      
      DAY—day
      
      WEEK—week
      
      MONTH—month
      
      YEAR—year
    - frequency, number—multiplier to increase debiting frequency
    Figure 38. marketplace
    - seller—object containing information about the seller on the marketplace:
      
      name—name or title of the seller on the marketplace
      
      city—name of the city where the seller is located
      
      country—country code of the seller's location in the ISO 3166-1 alpha-2 format
      
      registation—date of seller registration on the marketplace in the DD-MM-YYYY format
    - product_category—product or service category indicator, can have one of the following values:
      
      ACCESSORIES—accessories
      
      APPLIANCES—home appliances
      
      APPS_AND_GAMES—applications and games
      
      ARTS_CRAFTS_AND_SEWING—arts and crafts
      
      AUTOMOTIVE—car products
      
      BEAUTY—personal care products
      
      BABY—children's products
      
      BABY_CLOTHING—children's clothing
      
      BAGS_AND_PURSES—bags and purses
      
      BOOKS—books and other printed publications
      
      CDS_AND_VINYL—compact discs, vinyl records, and other physical media audio recordings
      
      CELL_PHONES_AND_ACCESSORIES—mobile phones and accessories
      
      COLLECTIBLES_AND_FINE_ARTS—art and collectibles
      
      DIGITAL_MUSIC—musical recordings in digital format
      
      ELECTRONICS—electronic devices
      
      GROCERY_AND_GOURMET_FOOD—grocery and gourmet foods
      
      HANDMADE—handmade products
      
      HEALTH_AND_PERSONAL_CARE—health and personal care products
      
      HOME_AND_KITCHEN—home and kitchen products
      
      INDUSTRIAL_AND_SCIENTIFIC—industrial and scientific equipment
      
      LUGGAGE_AND_TRAVEL_GEAR—luggage, travel accessories, and other travel products
      
      MAGAZINE_SUBSCRIPTIONS—subscriptions to print or digital periodicals
      
      MEN_CLOTHING—men's clothing
      
      MUSICAL_INSTRUMENTS—musical instruments
      
      OFFICE_PRODUCTS—office supplies
      
      PATIO_LAWN_AND_GARDEN—patio and garden supplies
      
      PET_SUPPLIES—pet supplies
      
      SHOES—shoes
      
      SOFTWARE—software
      
      SPORTS_AND_OUTDOORS—sports and outdoor supplies
      
      TOOLS_AND_HOME_IMPROVEMENT—construction tools and home improvement supplies
      
      TOYS_AND_GAMES—toys and games
      
      VIDEO_GAMES—video games
      
      WOMEN_CLOTHING—women's clothing
- additional—object containing additional information that may be relevant for payment processing:
  - integration_metadata, object—object containing information about how the payment was technically initiated:
    - originators, array of objects—array of objects containing information about the components used to initiate the payment (on the merchant's web service; up to six objects):
      - name, string—name of the service via which the payment was initiated, in the form of uppercase letters, digits, and underscores (_) instead of spaces (for example, COSMO_GAMES_STORE)
      - module_name, string—name of the technical module via which the payment was initiated, for example, cosmoshopPlugin
      - module_version, string—version number of the technical module via which the payment was initiated, for example, 2.1
      - session_reference, string—identifier of the operation or session within the web service, as a universally unique identifier version 7 (UUIDv7) in accordance with RFC 9562, for example, 018b163d-0b83-7ba0-b837-da575d0ff824
To ensure the user interface complies with Klarna service requirements, it is recommended to specify the customer address country code in the country parameter of the customer object. If the country code is not specified in the request or a code of a not officially supported country is specified, the English language can be used for displaying the Klarna service user interface, which may lead to a decrease in conversion rate.
Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Klarna method must contain the project identifier, basic payment information (identifier, amount, and currency code), customer and line item information, as well as signature.

{
    "general": {
        "project_id": 123456,
        "payment_id": "PMT123456-789",
        "signature": "<signature>",
    },
    "payment": {
        "amount": 10000,
        "currency": EUR,
        "description": "Order ORD123456-789"
    },
    "customer": {
        "id": "cust-9001001",
        "first_name": "John",
        "last_name": "Smith",
        "phone": "31612345678",
        "street": "Herengracht",
        "address": "101",
        "state": "NH",
        "email": "john@example.com",
        "city": "Amsterdam",
        "country": "NL",
        "zip": "1015BG",
        "day_of_birth": "15-04-1985",
        "ip_address": "1.0.0.4",
        "identify": {
            "doc_number": "19850415-1234",
            "doc_issue_country": "SE",
        },
        "account": {
            "date": "10-02-2021",
            "change_date": "01-03-2026",
            "loyalty_level": "01",
            "auth_time": "09-03-202610:15",
            "auth_method": "021",
            "purchase_history": [
                {
                    "number_of_purchases": 18,
                    "number_of_paid_purchases": 17,
                    "number_of_disputed_purchases": 1,
                    "total_amount": 845900,
                    "currency": "EUR",
                    "payment_method": "01",
                    "first_purchase_at": "14-03-202309:40",
                    "last_purchase_at": "01-03-202620:25",
                }
            ],
            "device_purchase_history": [
                {
                    "number_of_purchases": 18,
                    "number_of_paid_purchases": 17,
                    "number_of_disputed_purchases": 1,
                    "total_amount": 845900,
                    "currency": "EUR",
                    "payment_method": "01",
                    "first_purchase_at": "14-03-202309:40",
                    "last_purchase_at": "01-03-202620:25",
                }
            ],
        },
        "shipping_extended": [
            {
                "first_name": "John",
                "last_name": "Smith",
                "email": "john@example.com",
                "phone": "31612345678",
                "address": "Herengracht 101",
                "address2": "Herengracht 101",
                "postal": "1015BG",
                "city": "Amsterdam",
                "region_code": "NH",
                "country": "NL",
                "type": "011",
                "type_attributes": ["08", "01"],
                "carrier": "PostNL",
                "shipping_reference": "SHIP-COMPUTER-1",
            },
            {
                "first_name": "Jane",
                "last_name": "Smith",
                "email": "jane@example.com",
                "phone": "31698765432",
                "address": "Keizersgracht 250",
                "address2": "Keizersgracht 250",
                "postal": "1016EV",
                "city": "Amsterdam",
                "region_code": "NH",
                "country": "NL",
                "type": "011",
                "type_attributes": ["08", "07", "02"],
                "carrier": "DHL",
                "shipping_reference": "SHIP-COMPUTER-2",
            },
        ],
    },
    "return_url": {
        "return": "https://example.com/echo/success",
    },
    "purchase_data": {
        "positions": [
            {
                "type": "product",
                "name": "ExampleName",
                "quantity": 1,
                "amount_total": 189900,
                "tax_total": 32958,
                "amount": 189900,
                "product_url": "https://merchant.example.com",
                "product_image": "https://merchant.example.com",
                "product_reference": "SKU-LEN-X1G12",
                "item_reference": "ITEM-001",
                "shipping_reference": "SHIP-001",
            },
            {
                "type": "service",
                "name": "Extended Warranty 2 Years",
                "quantity": 1,
                "amount_total": 19900,
                "tax_total": 3458,
                "amount": 19900,
                "product_url": "https://merchant.example.com",
                "product_image": "https://merchant.example.com",
                "product_reference": "SVC-WARRANTY-2Y",
                "item_reference": "ITEM-002",
                "shipping_reference": "SHIP-001",
            },
            {
                "type": "discount",
                "name": "Summer Sale 10%",
                "quantity": 1,
                "amount_total": 20990,
                "tax_total": 3643,
                "amount": 20990,
                "item_reference": "ITEM-003",
            },
            {
                "type": "other",
                "name": "some",
                "quantity": 1,
                "amount_total": 20990,
                "tax_total": 3643,
                "amount": 20990,
                "item_reference": "ITEM-003",
            },
            {
                "type": "flight",
                "name": "Amsterdam → Stockholm",
                "quantity": 2,
                "amount_total": 45000,
                "tax_total": 7820,
                "amount": 22500,
                "item_reference": "ITEM-004",
                "booking_reference": "KL-20260601-AMS-ARN",
                "departure": {"airport": "AMS", "date": "01-06-2026", "city": "Amsterdam", "country": "NL"},
                "arrival": {"airport": "ARN", "city": "Stockholm", "country": "SE"},
                "airline": "KL",
                "price": 22500,
                "currency": "EUR",
                "class": "ECONOMY",
                "passengers": [
                    {"first_name": "John", "last_name": "Smith"}
                ],
                "insurances": [{"company": "AXA", "insurance_type": "CANCELATION", "amount": 2500, "currency": "EUR"}],
                "affiliate": "ExamplePartner BV",
            },
            {
                "type": "car",
                "name": "7 days rental",
                "quantity": 1,
                "amount_total": 35000,
                "tax_total": 6079,
                "amount": 35000,
                "item_reference": "ITEM-005",
                "departure": {
                    "address": "Schiphol Airport",
                    "address2": "Terminal 3",
                    "postal": "1118CP",
                    "city": "Amsterdam",
                    "region_code": "NH",
                    "country": "NL",
                    "date": "15-06-2026",
                },
                "arrival": {
                    "address": "Arlanda Airport",
                    "address2": "Terminal 5",
                    "postal": "19060",
                    "city": "Stockholm",
                    "region_code": "AB",
                    "country": "SE",
                },
                "car_rental_company": "Hertz",
                "price": 35000,
                "currency": "EUR",
                "class": "ECONOMY",
                "passengers": [{"first_name": "John", "last_name": "Smith"}],
                "insurances": [{"company": "Allianz", "insurance_type": "LOSS_DAMAGE_WAIVER", "amount": 1500, "currency": "EUR"}],
                "affiliate": "example.com",
            },
            {
                "type": "bus",
                "name": "Amsterdam → Brussels Express",
                "quantity": 1,
                "amount_total": 2500,
                "tax_total": 434,
                "amount": 2500,
                "item_reference": "ITEM-006",
                "departure": {
                    "date": "15-06-2026",
                    "location": "Amsterdam",
                    "address": "Orlyplein",
                    "address2": "1",
                    "postal": "1043DP",
                    "city": "Amsterdam",
                    "region_code": "NH",
                    "country": "NL",
                },
                "arrival": {
                    "address": "Rue du Progrès",
                    "address2": "80",
                    "postal": "1210",
                    "city": "Brussels",
                    "region_code": "BRU",
                    "country": "BE",
                },
                "bus_company": "FlixBus",
                "price": 2500,
                "currency": "EUR",
                "class": "ECONOMY",
                "passengers": [{"first_name": "John", "last_name": "Smith"}],
                "insurances": [{"company": "AXA", "insurance_type": "CANCELATION", "amount": 500, "currency": "EUR"}],
                "affiliate": "example.eu",
            },
            {
                "type": "train",
                "name": "Amsterdam → Newcastle Ferry",
                "quantity": 2,
                "amount_total": 18000,
                "tax_total": 3127,
                "amount": 9000,
                "item_reference": "ITEM-007",
                "departure": {
                    "date": "20-06-2026",
                    "location": "IJmuiden",
                    "address": "Sluisplein",
                    "address2": "33",
                    "postal": "1975AG",
                    "city": "IJmuiden",
                    "region_code": "NH",
                    "country": "NL",
                },
                "arrival": {
                    "address": "Royal Quays",
                    "address2": "Coble Dene",
                    "postal": "NE29 6EA",
                    "city": "Newcastle",
                    "region_code": "ENG",
                    "country": "GB",
                },
                "train_company": "DFDS",
                "price": 9000,
                "currency": "EUR",
                "class": "PREMIUM_ECONOMY",
                "passengers": [
                    {"first_name": "John", "last_name": "Smith"},
                    {"first_name": "Jane", "last_name": "Smith"},
                ],
                "insurances": [
                    {"company": "Allianz", "insurance_type": "CANCELATION", "amount": 1000, "currency": "EUR"}
                ],
                "affiliate": "example.eu",
            },
            {
                "type": "ferry",
                "name": "Amsterdam → Newcastle Ferry",
                "quantity": 2,
                "amount_total": 18000,
                "tax_total": 3127,
                "amount": 9000,
                "item_reference": "ITEM-007",
                "departure": {
                    "date": "20-06-2026",
                    "location": "IJmuiden Ferry",
                    "address": "Sluisplein",
                    "address2": "33",
                    "postal": "1975AG",
                    "city": "IJmuiden",
                    "region_code": "NH",
                    "country": "NL",
                },
                "arrival": {
                    "address": "Royal Quays, Coble Dene",
                    "address2": "Royal Quays, Coble Dene",
                    "postal": "NE29 6EA",
                    "city": "Newcastle",
                    "region_code": "ENG",
                    "country": "GB",
                },
                "ferry_line": "DFDS",
                "price": 9000,
                "currency": "EUR",
                "class": "PREMIUM_ECONOMY",
                "passengers": [
                    {"first_name": "John", "last_name": "Smith"},
                ],
                "insurances": [
                    {"company": "Allianz", "insurance_type": "CANCELATION", "amount": 1000, "currency": "EUR"}
                ],
                "affiliate": "example.eu",
            },
            {
                "type": "hotel",
                "name": "Hotel 1",
                "quantity": 1,
                "amount_total": 75000,
                "tax_total": 13025,
                "amount": 75000,
                "item_reference": "ITEM-008",
                "hotel_name": "Hotel",
                "start_date": "01-06-2026",
                "end_date": "04-06-2026",
                "address": "Nes",
                "address2": "49",
                "postal": "1012KD",
                "city": "Amsterdam",
                "region_code": "NH",
                "country": "NL",
                "lodging_type": "ROOM",
                "rooms": 1,
                "price": 25000,
                "currency": "EUR",
                "guests": [{"first_name": "John", "last_name": "Smith"}, {"first_name": "Jane", "last_name": "Smith"}],
                "host": {
                    "host_reference": "HOST-0042",
                    "type": "HOTEL",
                    "country": "NL",
                    "registration_date": "12-01-2015",
                    "reservations": 312,
                },
                "insurances": [
                    {"company": "Europ", "insurance_type": "CANCELATION", "amount": 3000, "currency": "EUR"}
                ],
                "affiliate": "example.com",
            },
            {
                "type": "voucher",
                "name": "Gift Card",
                "quantity": 1,
                "amount_total": 5000,
                "tax_total": 869,
                "amount": 5000,
                "item_reference": "ITEM-009",
                "start_date": "01-06-2026",
                "end_date": "01-06-2027",
                "voucher_type": "GIFT_CARD",
                "company": "example.com",
                "affiliate": "example.nl",
            },
            {
                "type": "insurance",
                "name": "Travel",
                "quantity": 1,
                "amount_total": 4500,
                "tax_total": 782,
                "item_reference": "ITEM-010",
                "company": "AXA",
                "insurance_type": "MEDICAL",
                "amount": 4500,
                "currency": "EUR",
            },
            {
                "type": "event",
                "name": "Dance Event",
                "quantity": 2,
                "amount_total": 15000,
                "tax_total": 2607,
                "amount": 7500,
                "item_reference": "ITEM-011",
                "company": "ID&T",
                "event_type": "FESTIVAL",
                "start_date": "14-10-2026",
                "end_date": "18-10-2026",
                "venue_name": "Example Dome",
                "access_controlled": True,
                "address": "De Passage 100",
                "address2": "De Passage 100",
                "postal": "1101AX",
                "city": "Amsterdam",
                "region_code": "NH",
                "country": "NL",
                "insurances": [{"company": "AXA", "insurance_type": "CANCELATION", "amount": 1500, "currency": "EUR"}],
                "affiliate": "example.nl",
            },
            {
                "type": "marketplace",
                "name": "Jacket",
                "quantity": 1,
                "amount_total": 12500,
                "tax_total": 2172,
                "amount": 12500,
                "product_url": "https://marketplace.example.com",
                "product_image": "https://marketplace.example.com",
                "product_reference": "SKU-VLJ-001",
                "item_reference": "ITEM-014",
                "shipping_reference": "SHIP-002",
                "seller": {
                    "reference": "SELLER-7890",
                    "name": "BV",
                    "address": "263",
                    "address2": "123",
                    "postal": "1016GV",
                    "city": "Amsterdam",
                    "region_code": "NH",
                    "country": "NL",
                    "registration": "15-03-2019",
                    "registration_updated": "10-01-2025",
                    "last_login": "16-04-2026",
                    "rating": "HIGH",
                },
                "product_category": "WOMEN_CLOTHING",
                "line_item_references": ["ITEM-014"],
                "shipping_references": ["SHIP-002"],
                "number_of_transactions": 145,
                "volume_of_transactions": 1875000,
            },
        ]
    },
    "additional": {
        "integration_metadata": {
           "originators": [
              "moduleName":"cosmoshopPlugin",
              "moduleVersion":"2.1",
              "name":"COSMO_GAMES_STORE",
              "session_reference":"018b163d-0b83-7ba0-b837-da575d0ff824"
    ]
   }
 }
}

Figure 39. Example of sufficient data in a purchase request

{
    "general": {
        "project_id": 123456,
        "payment_id": "PMT123456-789",
        "signature": "<signature>",
    },
    "payment": {
        "amount": 10000,
        "currency": EUR,
        "description": "Order ORD123456-789"
    },
    "customer": {
        "id": "cust-9001001",
        "first_name": "John",
        "last_name": "Smith",
        "phone": "31612345678",
        "street": "Herengracht",
        "address": "101",
        "state": "NH",
        "email": "john@example.com",
        "city": "Amsterdam",
        "country": "NL",
        "zip": "1015BG",
        "day_of_birth": "15-04-1985",
        "ip_address": "1.0.0.4",
        "identify": {
            "doc_number": "19850415-1234",
            "doc_issue_country": "SE",
        },
        "account": {
            "date": "10-02-2021",
            "change_date": "01-03-2026",
            "loyalty_level": "01",
            "auth_time": "09-03-202610:15",
            "auth_method": "021",
            "purchase_history": [
                {
                    "number_of_purchases": 18,
                    "number_of_paid_purchases": 17,
                    "number_of_disputed_purchases": 1,
                    "total_amount": 845900,
                    "currency": "EUR",
                    "payment_method": "01",
                    "first_purchase_at": "14-03-202309:40",
                    "last_purchase_at": "01-03-202620:25",
                }
            ],
            "device_purchase_history": [
                {
                    "number_of_purchases": 18,
                    "number_of_paid_purchases": 17,
                    "number_of_disputed_purchases": 1,
                    "total_amount": 845900,
                    "currency": "EUR",
                    "payment_method": "01",
                    "first_purchase_at": "14-03-202309:40",
                    "last_purchase_at": "01-03-202620:25",
                }
            ],
        },
        "shipping_extended": [
            {
                "first_name": "John",
                "last_name": "Smith",
                "email": "john@example.com",
                "phone": "31612345678",
                "address": "Herengracht 101",
                "address2": "Herengracht 101",
                "postal": "1015BG",
                "city": "Amsterdam",
                "region_code": "NH",
                "country": "NL",
                "type": "011",
                "type_attributes": ["08", "01"],
                "carrier": "PostNL",
                "shipping_reference": "SHIP-COMPUTER-1",
            },
            {
                "first_name": "Jane",
                "last_name": "Smith",
                "email": "jane@example.com",
                "phone": "31698765432",
                "address": "Keizersgracht 250",
                "address2": "Keizersgracht 250",
                "postal": "1016EV",
                "city": "Amsterdam",
                "region_code": "NH",
                "country": "NL",
                "type": "011",
                "type_attributes": ["08", "07", "02"],
                "carrier": "DHL",
                "shipping_reference": "SHIP-COMPUTER-2",
            },
        ],
    },
    "return_url": {
        "return": "https://example.com/echo/success",
    },
    "purchase_data": {
        "positions": [
            {
                "type": "product",
                "name": "ExampleName",
                "quantity": 1,
                "amount_total": 189900,
                "tax_total": 32958,
                "amount": 189900,
                "product_url": "https://merchant.example.com",
                "product_image": "https://merchant.example.com",
                "product_reference": "SKU-LEN-X1G12",
                "item_reference": "ITEM-001",
                "shipping_reference": "SHIP-001",
            },
            {
                "type": "service",
                "name": "Extended Warranty 2 Years",
                "quantity": 1,
                "amount_total": 19900,
                "tax_total": 3458,
                "amount": 19900,
                "product_url": "https://merchant.example.com",
                "product_image": "https://merchant.example.com",
                "product_reference": "SVC-WARRANTY-2Y",
                "item_reference": "ITEM-002",
                "shipping_reference": "SHIP-001",
            },
            {
                "type": "discount",
                "name": "Summer Sale 10%",
                "quantity": 1,
                "amount_total": 20990,
                "tax_total": 3643,
                "amount": 20990,
                "item_reference": "ITEM-003",
            },
            {
                "type": "other",
                "name": "some",
                "quantity": 1,
                "amount_total": 20990,
                "tax_total": 3643,
                "amount": 20990,
                "item_reference": "ITEM-003",
            },
            {
                "type": "flight",
                "name": "Amsterdam → Stockholm",
                "quantity": 2,
                "amount_total": 45000,
                "tax_total": 7820,
                "amount": 22500,
                "item_reference": "ITEM-004",
                "booking_reference": "KL-20260601-AMS-ARN",
                "departure": {"airport": "AMS", "date": "01-06-2026", "city": "Amsterdam", "country": "NL"},
                "arrival": {"airport": "ARN", "city": "Stockholm", "country": "SE"},
                "airline": "KL",
                "price": 22500,
                "currency": "EUR",
                "class": "ECONOMY",
                "passengers": [
                    {"first_name": "John", "last_name": "Smith"}
                ],
                "insurances": [{"company": "AXA", "insurance_type": "CANCELATION", "amount": 2500, "currency": "EUR"}],
                "affiliate": "ExamplePartner BV",
            },
            {
                "type": "car",
                "name": "7 days rental",
                "quantity": 1,
                "amount_total": 35000,
                "tax_total": 6079,
                "amount": 35000,
                "item_reference": "ITEM-005",
                "departure": {
                    "address": "Schiphol Airport",
                    "address2": "Terminal 3",
                    "postal": "1118CP",
                    "city": "Amsterdam",
                    "region_code": "NH",
                    "country": "NL",
                    "date": "15-06-2026",
                },
                "arrival": {
                    "address": "Arlanda Airport",
                    "address2": "Terminal 5",
                    "postal": "19060",
                    "city": "Stockholm",
                    "region_code": "AB",
                    "country": "SE",
                },
                "car_rental_company": "Hertz",
                "price": 35000,
                "currency": "EUR",
                "class": "ECONOMY",
                "passengers": [{"first_name": "John", "last_name": "Smith"}],
                "insurances": [{"company": "Allianz", "insurance_type": "LOSS_DAMAGE_WAIVER", "amount": 1500, "currency": "EUR"}],
                "affiliate": "example.com",
            },
            {
                "type": "bus",
                "name": "Amsterdam → Brussels Express",
                "quantity": 1,
                "amount_total": 2500,
                "tax_total": 434,
                "amount": 2500,
                "item_reference": "ITEM-006",
                "departure": {
                    "date": "15-06-2026",
                    "location": "Amsterdam",
                    "address": "Orlyplein",
                    "address2": "1",
                    "postal": "1043DP",
                    "city": "Amsterdam",
                    "region_code": "NH",
                    "country": "NL",
                },
                "arrival": {
                    "address": "Rue du Progrès",
                    "address2": "80",
                    "postal": "1210",
                    "city": "Brussels",
                    "region_code": "BRU",
                    "country": "BE",
                },
                "bus_company": "FlixBus",
                "price": 2500,
                "currency": "EUR",
                "class": "ECONOMY",
                "passengers": [{"first_name": "John", "last_name": "Smith"}],
                "insurances": [{"company": "AXA", "insurance_type": "CANCELATION", "amount": 500, "currency": "EUR"}],
                "affiliate": "example.eu",
            },
            {
                "type": "train",
                "name": "Amsterdam → Newcastle Ferry",
                "quantity": 2,
                "amount_total": 18000,
                "tax_total": 3127,
                "amount": 9000,
                "item_reference": "ITEM-007",
                "departure": {
                    "date": "20-06-2026",
                    "location": "IJmuiden",
                    "address": "Sluisplein",
                    "address2": "33",
                    "postal": "1975AG",
                    "city": "IJmuiden",
                    "region_code": "NH",
                    "country": "NL",
                },
                "arrival": {
                    "address": "Royal Quays",
                    "address2": "Coble Dene",
                    "postal": "NE29 6EA",
                    "city": "Newcastle",
                    "region_code": "ENG",
                    "country": "GB",
                },
                "train_company": "DFDS",
                "price": 9000,
                "currency": "EUR",
                "class": "PREMIUM_ECONOMY",
                "passengers": [
                    {"first_name": "John", "last_name": "Smith"},
                    {"first_name": "Jane", "last_name": "Smith"},
                ],
                "insurances": [
                    {"company": "Allianz", "insurance_type": "CANCELATION", "amount": 1000, "currency": "EUR"}
                ],
                "affiliate": "example.eu",
            },
            {
                "type": "ferry",
                "name": "Amsterdam → Newcastle Ferry",
                "quantity": 2,
                "amount_total": 18000,
                "tax_total": 3127,
                "amount": 9000,
                "item_reference": "ITEM-007",
                "departure": {
                    "date": "20-06-2026",
                    "location": "IJmuiden Ferry",
                    "address": "Sluisplein",
                    "address2": "33",
                    "postal": "1975AG",
                    "city": "IJmuiden",
                    "region_code": "NH",
                    "country": "NL",
                },
                "arrival": {
                    "address": "Royal Quays, Coble Dene",
                    "address2": "Royal Quays, Coble Dene",
                    "postal": "NE29 6EA",
                    "city": "Newcastle",
                    "region_code": "ENG",
                    "country": "GB",
                },
                "ferry_line": "DFDS",
                "price": 9000,
                "currency": "EUR",
                "class": "PREMIUM_ECONOMY",
                "passengers": [
                    {"first_name": "John", "last_name": "Smith"},
                ],
                "insurances": [
                    {"company": "Allianz", "insurance_type": "CANCELATION", "amount": 1000, "currency": "EUR"}
                ],
                "affiliate": "example.eu",
            },
            {
                "type": "hotel",
                "name": "Hotel 1",
                "quantity": 1,
                "amount_total": 75000,
                "tax_total": 13025,
                "amount": 75000,
                "item_reference": "ITEM-008",
                "hotel_name": "Hotel",
                "start_date": "01-06-2026",
                "end_date": "04-06-2026",
                "address": "Nes",
                "address2": "49",
                "postal": "1012KD",
                "city": "Amsterdam",
                "region_code": "NH",
                "country": "NL",
                "lodging_type": "ROOM",
                "rooms": 1,
                "price": 25000,
                "currency": "EUR",
                "guests": [{"first_name": "John", "last_name": "Smith"}, {"first_name": "Jane", "last_name": "Smith"}],
                "host": {
                    "host_reference": "HOST-0042",
                    "type": "HOTEL",
                    "country": "NL",
                    "registration_date": "12-01-2015",
                    "reservations": 312,
                },
                "insurances": [
                    {"company": "Europ", "insurance_type": "CANCELATION", "amount": 3000, "currency": "EUR"}
                ],
                "affiliate": "example.com",
            },
            {
                "type": "voucher",
                "name": "Gift Card",
                "quantity": 1,
                "amount_total": 5000,
                "tax_total": 869,
                "amount": 5000,
                "item_reference": "ITEM-009",
                "start_date": "01-06-2026",
                "end_date": "01-06-2027",
                "voucher_type": "GIFT_CARD",
                "company": "example.com",
                "affiliate": "example.nl",
            },
            {
                "type": "insurance",
                "name": "Travel",
                "quantity": 1,
                "amount_total": 4500,
                "tax_total": 782,
                "item_reference": "ITEM-010",
                "company": "AXA",
                "insurance_type": "MEDICAL",
                "amount": 4500,
                "currency": "EUR",
            },
            {
                "type": "event",
                "name": "Dance Event",
                "quantity": 2,
                "amount_total": 15000,
                "tax_total": 2607,
                "amount": 7500,
                "item_reference": "ITEM-011",
                "company": "ID&T",
                "event_type": "FESTIVAL",
                "start_date": "14-10-2026",
                "end_date": "18-10-2026",
                "venue_name": "Example Dome",
                "access_controlled": True,
                "address": "De Passage 100",
                "address2": "De Passage 100",
                "postal": "1101AX",
                "city": "Amsterdam",
                "region_code": "NH",
                "country": "NL",
                "insurances": [{"company": "AXA", "insurance_type": "CANCELATION", "amount": 1500, "currency": "EUR"}],
                "affiliate": "example.nl",
            },
            {
                "type": "marketplace",
                "name": "Jacket",
                "quantity": 1,
                "amount_total": 12500,
                "tax_total": 2172,
                "amount": 12500,
                "product_url": "https://marketplace.example.com",
                "product_image": "https://marketplace.example.com",
                "product_reference": "SKU-VLJ-001",
                "item_reference": "ITEM-014",
                "shipping_reference": "SHIP-002",
                "seller": {
                    "reference": "SELLER-7890",
                    "name": "BV",
                    "address": "263",
                    "address2": "123",
                    "postal": "1016GV",
                    "city": "Amsterdam",
                    "region_code": "NH",
                    "country": "NL",
                    "registration": "15-03-2019",
                    "registration_updated": "10-01-2025",
                    "last_login": "16-04-2026",
                    "rating": "HIGH",
                },
                "product_category": "WOMEN_CLOTHING",
                "line_item_references": ["ITEM-014"],
                "shipping_references": ["SHIP-002"],
                "number_of_transactions": 145,
                "volume_of_transactions": 1875000,
            },
        ]
    },
    "additional": {
        "integration_metadata": {
           "originators": [
              "moduleName":"cosmoshopPlugin",
              "moduleVersion":"2.1",
              "name":"COSMO_GAMES_STORE",
              "session_reference":"018b163d-0b83-7ba0-b837-da575d0ff824"
    ]
   }
 }
}

Extended list of supported parameters

This section provides an extended list of parameters to specify in purchase requests. Required parameters are listed in the section Format of requests for purchase processing.


Parameter	Description
`additional` object	Object that contains additional information that may be relevant for payment processing in certain cases	3
`integration_metadata` object	Object containing information about how the payment was technically initiated	3-13
`originators` array	Array of objects containing information about the components used to initiate the payment (on the merchant's web service; up to six objects)	3-1-13-1
`name` string	Name of the service via which the payment was initiated, in the form of uppercase letters, digits, and underscores (_) instead of spaces (for example, `COSMO_GAMES_STORE`)	3-1-23-1
`module_name` string	Name of the technical module via which the payment was initiated, for example, `cosmoshopPlugin`	3-1-33-1
`module_version` string	Version number of the technical module via which the payment was initiated, for example, `2.1`	3-1-43-1
`session_reference` string	Identifier of the operation or session within the web service, as a universally unique identifier version 7 (UUIDv7) in accordance with RFC 9562, for example, `018b163d-0b83-7ba0-b837-da575d0ff824`	3-1-53-1
`klarna_network_session_token` string	Token received from a payment system or provider and intended for secure interaction within a session (for example, Klarna Network Session Token)	3-23
`klarna_network_data` string	String object that contains specific information that can be used for ensuring interoperability between Klarna and it's partners. Information specified in this parameter can complement information specified in other parameters. The value length must be between 1 and 10240 characters (inclusive). The object must be formatted as follows: `"{\"content\":{\"customer_account_info\":[{\"unique_account_identifier\":\"test@example.com\",\"account_registration_date\":\"2017-02-13T10:49:20Z\",\"account_last_modified\":\"2019-03-13T11:45:27Z\"}]},\"content_type\":\"application/vnd.klarna.internal.emd-v2+json\"}"`	3-33
`customer` object	Object that contains customer data.	1
`account` object	Object with the customer's account information kept on file by the merchant.	1-11
`auth_method` string	Indicates how the customer was authenticated during their most recent login to the web service. Can have one of the possible values: `021`—authentication using an account password `022`—authentication using a reusable code `023`—authentication using a one-time verification code (One Time PIN, OTP) received in a short message (SMS) `024`—authentication using a one-time verification code (One Time PIN, OTP) received in an email `025`—authentication using an URL received in an email `026`—authentication using an URL received in a short message (SMS) `031`—Silent Network Authentication `032`—authentication using federated identity credentials via phone number `041`—authentication using an electronic key (passkey)	1-1-11-1
`auth_time` string	Date and time of the customer's most recent account login in the `DD-MM-YYYYhh:mm` format	1-1-21-1
`change_date` string	Date of the most recent change to the account, except for the password change or password reset, in the `DD-MM-YYYY` format	1-1-31-1
`date` string	The account creation date in the `DD-MM-YYYY` format	1-1-41-1
`device_purchase_history` array of objects	Array of objects containing information about previous purchases from the customer's device	1-1-51-1
`number_of_purchases` integer	Number of purchases made in the last 12 months	1-1-5-11-1-5
`number_of_paid_purchases` integer	Number of paid purchases made in the last 12 months	1-1-5-21-1-5
`number_of_disputed_purchases` integer	Number of purchases with disputes in the last 12 months	1-1-5-31-1-5
`total_amount` integer	Total amount of purchases made in the last 12 months, in the smallest units of the currency specified in the `currency` parameter of this same object	1-1-5-41-1-5
`currency` string	Currency code for the specified amount in the ISO-4217 alpha-3 format	1-1-5-51-1-5
`payment_method` string	Indicator of the type of payment instrument used, can have one of the following values: `01`—payment card of the payment system via which the payment is initiated `02`—account with support of direct debiting of funds `03`—mobile wallet `04`—payment card of another payment system `999`—other instrument	1-1-5-61-1-5
`first_purchase_at` string	Date and time of the customer's first purchase in the web service in the `DD-MM-YYYYhh:mm` format	1-1-5-71-1-5
`last_purchase_at` string	Date and time of the customer's last purchase in the web service in the `DD-MM-YYYYhh:mm` format	1-1-5-81-1-5
`loyalty_level` string	Indicator of the customer's level in the merchant's web service loyalty program, converted to one of the following values: `01`—high `02`—medium `03`—low	1-1-61-1
`purchase_history` array of objects	Array of objects containing information about the customer's previous purchases	1-1-71-1
`number_of_purchases` integer	Number of purchases made in the last 12 months	1-1-7-11-1-7
`number_of_paid_purchases` integer	Number of paid purchases made in the last 12 months	1-1-7-21-1-7
`number_of_disputed_purchases` integer	Number of purchases with disputes in the last 12 months	1-1-7-31-1-7
`total_amount` integer	Total amount of purchases made in the last 12 months, in the smallest units of the currency specified in the `currency` parameter of this same object	1-1-7-41-1-7
`currency` string	Currency code for the specified amount in the ISO-4217 alpha-3 format	1-1-7-51-1-7
`payment_method` string	Indicator of the type of payment instrument used, can have one of the following values: `01`—payment card of the payment system via which the payment is initiated `02`—account with support of direct debiting of funds `03`—mobile wallet `04`—payment card of another payment system `999`—other instrument	1-1-7-61-1-7
`first_purchase_at` string	Date and time of the customer's first purchase in the web service in the `DD-MM-YYYYhh:mm` format	1-1-7-71-1-7
`last_purchase_at` string	Date and time of the customer's last purchase in the web service in the `DD-MM-YYYYhh:mm` format	1-1-7-81-1-7
`identify` object	Object that contains customer identification document details	1-21
`doc_issue_country` string	The code of the country where the document serving as a proof of the customer's identity was issued. Specified in the ISO 3166-1 alpha-2 format. Example: `GB`	1-2-11-2
`doc_number` string	Identification document number	1-2-21-2
`shipping_extended` array of objects	Array of objects containing shipping information, which may be relevant for individual alternative payment methods and may include the following information	1-31
`address` string	Basic information about the shipping address in the form of a street name and a house number	1-3-11-3
`address2` string	Additional information about the shipping address in the form of the name of the district, information additional to the house number or other information	1-3-21-3
`carrier` string	Name of the shipping organization	1-3-31-3
`city` string	Name of the city (or other locality) in the shipping address	1-3-41-3
`country` string	Country code in the shipping address in the ISO 3166-1 alpha-2 format	1-3-51-3
`email` string	Email address	1-3-61-3
`first_name` string	First name of the recipient	1-3-71-3
`last_name` string	Last name of the recipient	1-3-81-3
`phone` string	Phone number of the recipient, as a sequence of digits without separators	1-3-91-3
`postal` string	Postal code in the shipping address	1-3-101-3
`region_code` string	Internal area code in the shipping address, representing the second part of the international area code (in the ISO 3166-2 format), without the two-letter country code and separating hyphen	1-3-111-3
`shipping_reference` string	Shipping identifier within the web service or delivery service, required when specifying information about different deliveries in a single request	1-3-121-3
`type` string	Shipping type indicator, can have one of the following values: `011`—door delivery to the customer's billing address `012`—delivery to the building at the customer's billing address `013`—delivery to a PO Box at the customer's billing address `021`—door delivery to another confirmed address `022`—delivery to the building at another confirmed address `023`—delivery to a PO Box at another confirmed address `031`—door delivery to an address that does not match the billing address and is not confirmed `032`—delivery to the building to an address that does not match the billing address and is not confirmed `033`—delivery to a mailbox at an address that does not match the billing address and is not confirmed `041`—pickup from a store `042`—pickup from a warehouse `043`—pickup from a parcel locker `044`—pickup from an order pickup point `051`—delivery to an email address `052`—delivery with file download from a web service `059`—other electronic delivery method `071`—other physical delivery method	1-3-131-3
`type_attributes` array of strings	Array of strings with a list of additional shipping parameter indicators, can have the following values: `01`—indicator of the requirement of delivery confirmation by the customer (with receipt of their signature) `02`—indicator of the requirement of recipient identity verification (with verification of information by a delivery specialist) `03`—indicator of the requirement of contactless delivery `04`—indicator of the requirement of door-to-door delivery `05`—indicator of the requirement of delivery to the building `06`—indicator of the requirement of delivery to neighbors `07`—indicator of the requirement of express delivery `08`—indicator of the requirement of tracked delivery `09`—indicator of the requirement of using untracked delivery	1-3-141-3
`purchase_data` object	Object that contains purchase data	2
`type` string	Indicator that specifies the type of a line item, that can have one of the following values: `bus`—bus ride `car`—car rental `discount`—discount or promo code (for any goods or services) `event`—attending an event (for example a concert or exhibition) `ferry`—ferry crossing `flight`—air travel `hotel`—hotel accommodation `insurance`—insurance `marketplace`—product or service provided via a marketplace `ondemand`—product or service provided as part of an on-demand subscription plan (for example, watching a movie in an online cinema) `subscription`—product or service provided as part of a subscription plan with regular debiting (for example, access to watching movies in an online cinema for a month) `train`—train ride `voucher`—voucher or gift certificate `product`—a product of a different category `service`—a service of a different category `other`—another type of service provided to the customer	2-12
`name` string	Name of the item	2-22
`amount` integer	Cost of a unit of goods or services per item, in smallest currency units or as a hyphen (`-`) for items with the `discount` type	2-32
`quantity` integer	Number of goods or services per item	2-42
`amount_total` integer	Total cost of goods or services per item, in smallest currency units or as a hyphen (`-`) for items with the `discount` type	2-52
`tax_total` integer	Amount of tax or fee included in the item price, in smallest currency units or as a hyphen (`-`) for items with the `discount` type	2-62
`product_reference` string	Identifier of a product or service as defined by the web service	2-72
`product_url` string	Address of the web service page with the product or service card	2-82
`product_image` string	Image URL of the product or service	2-92
`item_reference` string	Item identifier within the list of all purchased items	2-102
`shipping_reference` string	The shipping identifier for an item as defined by a web service or shipping service	2-112
`departure` object	Object that contains departure information	2-122
`address` string	Basic information about the departure address in the form of a street name and a house number	2-12-12-12
`address2` string	Additional information about the departure address in the form of the name of the district, information additional to the house number or other information	2-12-22-12
`date` string	Departure date in the `DD-MM-YYYY` format	2-12-32-12
`city` string	Name of the city in the departure address	2-12-42-12
`country` string	Country code in the departure address in the ISO 3166-1 alpha-2 format	2-12-52-12
`location` string	Name of the departure location	2-12-62-12
`postal` string	Postal code in the address of the departure location	2-12-72-12
`region_code` string	The internal code of the region (state, province, or other territorial area) in the address of the departure location, is the second part of the international area code (in the ISO 3166-2 format), without the two-letter country code and separating hyphen	2-12-82-12
`airport` string	Three-letter code assigned to the departure airport by the International Air Transport Association (IATA)	2-12-92-12
`arrival` object	Object that contains arrival information	2-132
`address` string	Basic information about the arrival address in the form of a street name and a house number	2-13-12-13
`address2` string	Additional information about the arrival address in the form of the name of the district, information additional to the house number or other information	2-13-22-13
`date` string	Arrival date in the `DD-MM-YYYY` format	2-13-32-13
`city` string	Name of the city in the arrival address	2-13-42-13
`country` string	Country code in the arrival address in the ISO 3166-1 alpha-2 format	2-13-52-13
`postal` string	Postal code in the address of the arrival location	2-13-62-13
`region_code` string	The internal code of the region (state, province, or other territorial area) in the address of the arrival location, is the second part of the international area code (in the ISO 3166-2 format), without the two-letter country code and separating hyphen	2-13-72-13
`airport` string	Three-letter code assigned to the arrival airport by the International Air Transport Association (IATA)	2-13-82-13
`bus_company` string	Name of the organization providing bus transportation	2-142
`car_rental_company` string	Name of the organization providing the rental car	2-152
`ferry_line` string	Name of the organization that operates the ferry service	2-162
`airline` string	Two-letter code assigned to an airline by the International Air Transport Association (IATA)	2-172
`train_company` string	Name of the organization carrying out rail transportation	2-182
`affiliate` string	Name of the partner organization providing the service	2-192
`booking_reference` string	Booking identifier (code) relevant for the flight	2-202
`passengers` array of objects	Array of objects containing passenger information	2-212
`first_name` string	First name of the passenger	2-21-12-21
`last_name` string	Last name of the passenger	2-21-22-21
`class` string	Indicator that specifies the service class, can have one of the following values: `COMPACT`—compact class `ECONOMY`—economy class `PREMIUM_ECONOMY`—premium economy class `BUSINESS`—business class `FIRST_CLASS`—first class	2-222
`insurances` array of objects	Array of objects containing insurance services information	2-232
`insurance_type` string	Indicator of the insurance service type, can have one of the following values: `BANKRUPTCY`—bankruptcy insurance for the service provider `CANCELATION`—service cancellation insurance `EMERGENCY`—emergency insurance `MEDICAL`—medical insurance `LIABILITY_SUPPLEMENT`—third-party liability insurance covering bodily injury and property damage `LOSS_DAMAGE_WAIVER`—vehicle theft or total damage insurance `PARTIAL_DAMAGE_WAIVER`—insurance from vehicle damage to a specific excess or deductible `PERSONAL_ACCIDENT`—insurance from medical expenses and accidental death for the driver and passengers `PERSONAL_EFFECTS`—insurance for personal belongings stolen or damaged inside the rental vehicle	2-23-22-23
`amount` integer	Cost of the insurance service in the smallest units of currency specified in the `currency` parameter of the same object currency	2-23-32-23
`price` integer	Cost of a ticket or reservation in the smallest units of currency specified in the `currency` parameter of the same object	2-242
`currency` string	Currency code for the ticket, reservation or insurance service price in the ISO-4217 alpha-3 format	2-252
`hotel_name` string	Name of the accommodation (for example, of a hotel or a hostel)	2-262
`host` object	Object containing information about the rental property owner	2-282
`type` string	Rental type indicator: `HOSTEL`—booking a room or bed in a hostel `HOTEL`—booking a room in a hotel `OWNER`—renting the property directly from the owner `RENTAL_AGENCY`—renting the property through an agency	2-28-12-28
`host_reference` string	Host identifier	2-28-22-28
`country` string	Country code in the host's address (legal address for a legal entity or residential address for an individual) in ISO 3166-1 alpha-2 format	2-28-32-28
`registration_date` string	Registration date of the host in the `DD-MM-YYYY` format	2-28-42-28
`price` integer	Number of reservations via the host over the past 12 months	2-28-52-28
`lodging_type` integer	Indicator of the accommodation type, can have one of the following values: `ROOM`—room `CABANA`—cabana (beach cabin or similar kind of shelter) `STANDARD`—standard room `SUITE`—suite `APARTMENT`—apartment `HOUSE`—house `VILLA`—villa `PENTHOUSE`—penthouse	2-292
`address` string	Basic information about the accommodation address in the form of a street name and a house number	2-302
`address2` string	Additional information about the accommodation address in the form of the name of the district, information additional to the house number or other information	2-312
`city` string	Name of the city in the accommodation address	2-322
`country` string	Country code in the accommodation address in the ISO 3166-1 alpha-2 format	2-332
`postal` string	Postal code in the address of the accommodation location	2-342
`region_code` string	The internal code of the region (state, province, or other territorial area) in the address of the accommodation location, is the second part of the international area code (in the ISO 3166-2 format), without the two-letter country code and separating hyphen	2-352
`rooms` integer	Number of accommodations being booked (for example, rooms or suites)	2-362
`start_date` string	Service start date (for example, check-in date) in the `DD-MM-YYYY` format	2-372
`end_date` string	Service end date (for example, check-in date) in the `DD-MM-YYYY` format	2-382
`guests` array of objects	Array of objects containing information about guests	2-392
`first_name` string	First name of the guest	2-39-12-39
`last_name` string	Last name of the guest	2-39-22-39
`company` string	Name of the organisation issuing the voucher or certificate or providing insurance services	2-402
`voucher_type` string	Indicator of the voucher or certificate type, can have one of the following values: `DIGITAL_PRODUCT`—voucher for a digital product `DISCOUNT`—voucher for a discount, specified as a percentage or a fixed numeric amount `GIFT_CARD`—gift certificate with a fixed denomination `PHYSICAL_PRODUCT`—voucher for a physical product `SERVICES`—voucher for receiving a service	2-422
`insurance_type` string	Indicator of the insurance service type, can have one of the following values: `BANKRUPTCY`—bankruptcy insurance for the service provider `CANCELATION`—service cancellation insurance `EMERGENCY`—emergency insurance `MEDICAL`—medical insurance	2-442
`amount` integer	Cost of the insurance service in the smallest units of currency specified in the `currency` parameter of the same object currency	2-452
`event_type` string	Event type indicator that can have one of the following values: `CONCERT`—concert `CONFERENCE`—conference `DIGITAL_EDUCATION`—online educational event `EXPO`—exhibition `FESTIVAL`—festival `IN_PERSON_EDUCATION`—in-person educational event `SPORT`—sporting event `TOUR`—excursion or tour	2-472
`venue_name` string	Name of the event venue (for example, the name of a park or conference hall)	2-482
`access_controlled` boolean	Indicator of the of digital access control to the service	2-492
`seller` object	Object containing information about the seller on the marketplace	2-502
`name` string	Name or title of the seller on the marketplace	2-50-12-50
`address` string	Basic information about the seller's address in the form of a street name and a house number	2-50-22-50
`address2` string	Additional information about the seller's address in the form of the name of the district, information additional to the house number or other information	2-50-32-50
`city` string	Name of the city where the seller is located	2-50-42-50
`country` string	Country code of the seller's location in the ISO 3166-1 alpha-2 format	2-50-52-50
`postal` string	Postal code in the address of the seller's location	2-50-62-50
`region_code` string	Internal region code (state, province, or other territorial area) in the seller's address, representing the second part of the international area code (in the ISO 3166-2 format), without the two-letter country code and separating hyphen	2-50-72-50
`rating` string	Seller's rating on the marketplace converted to one of the following values: `VERY_HIGH`—very high `HIGH`—high `MEDIUM`—medium `LOW`—low `VERY_LOW`—very low	2-50-82-50
`registration` string	Date of seller registration on the marketplace in the `DD-MM-YYYY` format	2-50-92-50
`registration_updated` string	Date of last change to seller information in the `DD-MM-YYYY` format	2-50-102-50
`last_login` string	Date of last seller authentication on the marketplace in the `DD-MM-YYYY` format	2-50-112-50
`reference` string	Seller identifier on the marketplace	2-50-122-50
`number_of_transactions` integer	Number of payment operations via the intermediary through which the product is sold, over the last 12 months	2-512
`volume_of_transactions` integer	Amount of payment transactions with the intermediary through which the product is sold, over the last 12 months, in smallest currency units	2-522
`product_category` string	Product or service category indicator, can have one of the following values: `ACCESSORIES`—accessories `APPLIANCES`—home appliances `APPS_AND_GAMES`—applications and games `ARTS_CRAFTS_AND_SEWING`—arts and crafts `AUTOMOTIVE`—car products `BEAUTY`—personal care products `BABY`—children's products `BABY_CLOTHING`—children's clothing `BAGS_AND_PURSES`—bags and purses `BOOKS`—books and other printed publications `CDS_AND_VINYL`—compact discs, vinyl records, and other physical media audio recordings `CELL_PHONES_AND_ACCESSORIES`—mobile phones and accessories `COLLECTIBLES_AND_FINE_ARTS`—art and collectibles `DIGITAL_MUSIC`—musical recordings in digital format `ELECTRONICS`—electronic devices `GROCERY_AND_GOURMET_FOOD`—grocery and gourmet foods `HANDMADE`—handmade products `HEALTH_AND_PERSONAL_CARE`—health and personal care products `HOME_AND_KITCHEN`—home and kitchen products `INDUSTRIAL_AND_SCIENTIFIC`—industrial and scientific equipment `LUGGAGE_AND_TRAVEL_GEAR`—luggage, travel accessories, and other travel products `MAGAZINE_SUBSCRIPTIONS`—subscriptions to print or digital periodicals `MEN_CLOTHING`—men's clothing `MUSICAL_INSTRUMENTS`—musical instruments `OFFICE_PRODUCTS`—office supplies `PATIO_LAWN_AND_GARDEN`—patio and garden supplies `PET_SUPPLIES`—pet supplies `SHOES`—shoes `SOFTWARE`—software `SPORTS_AND_OUTDOORS`—sports and outdoor supplies `TOOLS_AND_HOME_IMPROVEMENT`—construction tools and home improvement supplies `TOYS_AND_GAMES`—toys and games `VIDEO_GAMES`—video games `WOMEN_CLOTHING`—women's clothing	2-532
`line_item_references` array of strings	Array of web service page URLs with product or service descriptions	2-542
`shipping_references` array of strings	Array of strings with a list of shipping identifiers for purchased items within a web service or delivery service	2-552

Two-step purchase debiting request format

There are several things you need to consider when sending debiting requests by using the Klarna method:

To initiate each debiting, send a separate POST request to the /v2/payment/klarna/capture endpoint.
Each request must include the following objects and parameters:
- Object general—general purchase information:
  - project_id—project identifier obtained from Ecommpay during integration
  - payment_id—payment identifier unique within the project
  - signature—request signature generated after all required parameters are specified (details—in the Signature generation and verification) (details)
- Object payment—payment information:
  - amount—payment amount in the smallest currency unit
  - currency—payment currency code in the ISO-4217 alpha-3 format
- Array purchase_data—information about the relevant bill items. The structure and format of the data specified in this parameter are the same as those described in the section Format of requests for purchase processing.
The amount and currency must match the values in the authorisation request.
Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Klarna method must contain the project identifier, basic payment information (identifier, amount, and currency code), relevant bill items information as well as signature.

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6ta/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "EUR"
  },
    "purchase_data": {
        "positions": [
            {
                "type": "product",
                "name": "Lenovo",
                "quantity": 1,
                "amount_total": 189900,
                "tax_total": 32958,
                "amount": 189900,
                "product_url": "https://example.com",
                "product_image": "https://example.com",
                "product_reference": "SKU-LEN-X1G12",
                "item_reference": "ITEM-001",
                "shipping_reference": "SHIP-001",
            }
          ]
}

Figure 40. Example of sufficient data in a debiting request

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6ta/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "EUR"
  },
    "purchase_data": {
        "positions": [
            {
                "type": "product",
                "name": "Lenovo",
                "quantity": 1,
                "amount_total": 189900,
                "tax_total": 32958,
                "amount": 189900,
                "product_url": "https://example.com",
                "product_image": "https://example.com",
                "product_reference": "SKU-LEN-X1G12",
                "item_reference": "ITEM-001",
                "shipping_reference": "SHIP-001",
            }
          ]
}

Two-step purchase cancellation request format

There are several things you need to consider when sending purchase cancellation requests by using the Klarna method:

To initiate each cancellation, send a separate POST request to one of the /v2/payment/klarna/cancel endpoint.
Each request must include the following objects and parameters:
- Object general—general purchase information:
  - project_id—project identifier obtained from Ecommpay during integration
  - payment_id—payment identifier unique within the project
  - signature—request signature generated after all required parameters are specified (details—in the Signature generation and verification) (details)
Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Klarna method must contain the project and payment identifiers, as well as signature.

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "9DRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4U...=="
  }

Figure 41. Example of sufficient data in a purchase cancellation request

{
  "general": {
    "project_id": 580,
    "payment_id": "TEST_15427033321774",
    "signature": "9DRrl+Se5mDLXHChlDZrjJXZw7ew6ow3RpGYv4U...=="
  }

Formats of intermediate callbacks for customer redirection

Each payment made with the Klarna method requires redirection of customers from the merchant's web service to the Klarna service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information details in the redirect_data object. The Klarna SDK (details) or the URL from the callback can be used to redirect the customer. The format of such callbacks is standard (details), and the following objects and parameters are included in the redirect_data object:

body—object with data to be sent in the request body, includes the payment_request_id parameter containing data for redirecting the customer by using the Klarna SDK;
method—parameter specifying the HTTP method for sending the request (GET or POST)
url—parameter containing a link for redirection

Figure 42. redirect_data example

  "redirect_data": {
    "body": {
      "payment_request_id": "krn:payment:eu1:request:e6bab34f"
    },
    "method": "GET",
    "url": "https://pay.examople.com/eu/requests/92ba6a6b"
  },

Callback format

The Klarna method uses the standard format for callbacks to deliver purchase results. For more information, see Handling callbacks.

The following is the example of a callback with information about a 10.00 purchase made in the 442 project.

Figure 43. Example of data in a purchase callback

{
        "project_id": 442,
        "payment": {
            "id": "EP696e-3aea",
            "type": "purchase",
            "status": "success",
            "date": "2022-10-07T19:28:58+0000",
            "method": "Klarna",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "12345"
        },
        "operation": {
            "id": 33,
            "type": "sale",
            "status": "success",
            "date": "2022-10-07T19:28:58+0000",
            "created_date": "2022-10-07T19:28:14+0000",
            "request_id": "a8ea69fdc5a83a2622-00000001",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 18052,
                "payment_id": "1665170919576",
                "auth_code": ""
            }
        },
        "signature": "h14kSk782IZEgezTRpbZVe/54KGgd7mA=="
    }

The following is the example of a callback with information about a declined purchase.

Figure 44. Example of data in a declined purchase callback

{
        "project_id": 442,
        "payment": {
            "id": "EP1d27-e7ee",
            "type": "purchase",
            "status": "decline",
            "date": "2022-10-10T09:28:33+0000",
            "method": "Klarna",
            "sum": {
                "amount": 1500000,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "12345"
        },
        "operation": {
            "id": 38,
            "type": "sale",
            "status": "decline",
            "date": "2022-10-10T09:28:33+0000",
            "created_date": "2022-10-10T09:28:19+0000",
            "request_id": "f56812a9270c19c04-00000001",
            "sum_initial": {
                "amount": 1500000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1500000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 18052,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "ZS90VEL4x5avOhc4MG85STSog=="
    }

Useful links

The following articles can be useful when implementing purchases via Gate:

Interaction concepts—how to organise interaction with the payment platform by using Gate
Signature generation and verification—about the procedure of creating and verifying signatures in requests and callbacks.
Payment processing—about the types, processing models, and possible statuses of supported payments and operations.
One-time one-step purchase—about processing of one-time one-step purchases by using Gate.
Handling operation processing information—about error and response codes that are used in the payment platform to record information about performing of operations.

Refunds by using Gate

General information

To perform a refund through Gate by using the Klarna method, send a request with all required parameters and signature to the Ecommpay URL and receive a callback with the result. The full sequence and special aspects of refund performing are provided below.

Figure 45. Refund performing by using Gate: step-by-step description

A customer initiates a refund.
The web service sends the request for performing the refund by using Gate to the specified Ecommpay URL.
The payment platform receives the request.
The payment platform validates the required parameters and signature in the request.
The payment platform sends the response to the web service with information about the receipt of the request and its validity (details).
The payment platform performs further processing of the request (with parameter consistency check) and sends it to the Klarna service.
The refund is processed on the side of the Klarna service.
The Klarna service sends the result notification to the payment platform.
The payment platform sends the result callback to the web service.
The customer receives the refund result information from the web service.

Information about the formats of requests and callbacks used for performing refunds by using the Klarna method via Gate is presented further in this section. General information about working with the Gate API is presented in Interaction concepts.

Request format

There are several things you need to consider when sending refund requests by using the Klarna method:

To initiate each refund, send a POST request to the /v2/payment/refund endpoint.
Each request must include the following objects and parameters:
- Object general—general request information:
  - project_id—project identifier obtained from Ecommpay during integration
  - payment_id—identifier of the payment that needs to be refundedpayment identifier
  - signature—request signature created after all required parameters are specified (details—in the Signature generation and verification)
- Object payment—refund information:
  - description—refund description or comment
  - amount—refund amount in the smallest currency unit (required for a partial refund)
  - currency—refund currency code in the ISO-4217 alpha-3 format (required for a partial refund)
- Object customer—customer information:
  - ip_address—customer IP address relevant for the initiated refund
- Array purchase_data—information about the bill items for which a refund must be initiated (for a full refund, all items for which a purchase was processed or authorisation hold was applied must be specified).The structure and format of the data specified in this parameter are the same as those described in the section Purchases by using Gate.
Additionally, any other parameters included in the specification can be used.

Thus, a correct refund request by using the Klarna method must contain the project and payment identifiers, description of the refund, the customer IP address, bill items information, signature, and, if necessary, currency code and refund amount.

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  },
    "purchase_data": {
        "positions": [
            {
                "type": "product",
                "name": "Lenovo",
                "quantity": 1,
                "amount_total": 189900,
                "tax_total": 32958,
                "amount": 189900,
                "product_url": "https://example.com",
                "product_image": "https://example.com",
                "product_reference": "SKU-LEN-X1G12",
                "item_reference": "ITEM-001",
                "shipping_reference": "SHIP-001",
            }
          ]
}

Figure 46. Example of sufficient data in a refund request

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  },
    "purchase_data": {
        "positions": [
            {
                "type": "product",
                "name": "Lenovo",
                "quantity": 1,
                "amount_total": 189900,
                "tax_total": 32958,
                "amount": 189900,
                "product_url": "https://example.com",
                "product_image": "https://example.com",
                "product_reference": "SKU-LEN-X1G12",
                "item_reference": "ITEM-001",
                "shipping_reference": "SHIP-001",
            }
          ]
}

Callback format

The Klarna method uses the standard format for callbacks to deliver refund results. For more information, see Handling callbacks.

The following is the example of a callback with information about a 3.00 EUR partial refund made in the 442 project.

Figure 47. Example of data in a refund callback

{
        "project_id": 442,
        "payment": {
            "id": "EP8806-91ba",
            "type": "purchase",
            "status": "partially refunded",
            "date": "2022-10-10T13:21:33+0000",
            "method": "Klarna",
            "sum": {
                "amount": 300,
                "currency": "EUR"
            },
            "description": ""
        },
        "customer": {
            "id": "12345"
        },
        "operation": {
            "id": 46,
            "type": "refund",
            "status": "success",
            "date": "2022-10-10T13:21:33+0000",
            "created_date": "2022-10-10T13:21:23+0000",
            "request_id": "b132a7883e19d0fe21b8fd1-00000001",
            "sum_initial": {
                "amount": 700,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 700,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 18052,
                "payment_id": "1665408090952",
                "auth_code": ""
            }
        },
        "signature": "7upYXNzrL/tQfYO0rwjvkc9LbDPkwSw=="
    }

The following is the example of a callback with information about a refund declined as the amount in the refund requested is greater than the amount in the initial payment.

Figure 48. Example of data in a declined refund callback

{
        "project_id": 211,
        "payment": {
            "id": "refund_02",
            "type": "purchase",
            "status": "success",
            "date": "2019-02-19T14:25:25+0000",
            "method": "Klarna",
            "sum": {
                "amount": 100000,
                "currency": "EUR"
            },
            "description": "test_02"
        },
        "account": {
            "number": "035209875690435"
        },
        "operation": {
            "id": 14153000003282,
            "type": "refund",
            "status": "decline",
            "date": "2019-02-19T14:25:25+0000",
            "created_date": "2019-02-19T14:25:24+0000",
            "request_id": "9d11b2ca618ec3ba0f5fa58f174",
            "sum_initial": {
                "amount": 100000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1169,
                "payment_id": "105887607",
                "date": "2019-02-19T14:25:24+0000",
                "auth_code": ""
            },
            "code": "3283",
            "message": "Refund amount more than init amount"
        },
        "signature": "of8k9xerKSKpFBR4XL0Sf/7eg=="
    }

Useful links

The following articles can be useful when implementing refunds via Gate:

Interaction concepts—how to organise interaction with the payment platform by using Gate
Signature generation and verification—about the procedure of creating and verifying signatures in requests and callbacks.
Payment processing—about the types, processing models, and possible statuses of supported payments and operations.
Purchase refunds—about performing of refunds by using Gate.
Handling operation processing information—about error and response codes that are used in the payment platform to record information about performing of operations.

Refunds by using Dashboard

When working with Dashboard, you can perform single and mass refunds by using the Klarna method.

To perform a single refund, select the target purchase, open its information tab, specify the amount of the refund, send a request and verify that the refund has been performed.
To perform a mass refund, prepare and upload a file with information about all target refunds, send a batch request, and verify that the refunds have been performed.

Use a CSV file structured according to the requirements presented in the Mass payments data section. The refund parameters must comply with the requirements (you do not have to generate a signature because it is specified by Dashboard).

More information Information about performing refunds by using Dashboard is presented in a separate section.

Analysis of payments results

To analyse information about payments made with the Klarna method as well as other methods, you can use:

Dashboard interface toolkit with various lists and analytic panels.
Reports in CSV file format, available via the Reports section (one-time and periodically).
Data in JSON format, sent by program requests to a specified URL available by using the Data API interface.

If you have any questions, refer to the documentation (Dashboard and Using Data API) and Ecommpay technical support.