Klarna

Введение

Klarna — метод, позволяющий проводить платежи с использованием электронных кошельков в разных валютах в отдельных европейских странах. Для этого метода в платёжной платформе Ecommpay поддерживаются оплаты в одну и две стадии и возвраты.

В этой статье представлена информация о работе с методом Klarna: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.

Характеристика

Схема работы

В проведении отдельного платежа с использованием метода Klarna задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса Klarna.

Основные операции

Для проведения платежей и выполнения операций с использованием метода Klarna могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок), а возвраты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения.

При работе с методом Klarna, независимо от используемых интерфейсов, актуальны следующие свойства и ограничения.

Сценарии использования

Проведение оплат с использованием метода Klarna осуществляется с перенаправлением пользователей к сервису Klarna, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса.

Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах. При использовании дополнительных возможностей (таких как платёжные ссылки) сценарии выполнения операций методом Klarna соответствуют специфике этих возможностей.

Общая информация

Для проведения оплаты через Payment Page с использованием метода Klarna со стороны веб-сервиса в общем случае необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате. При этом в случае с оплатой в две стадии позднее может быть необходимым подтвердить списание заблокированных средств (подробнее). При работе с методом поддерживаются четыре способа оплаты: Pay in N (3 or 4) parts, Pay in 30 Days, Pay in Full, Financing. Полная схема проведения оплаты в одну стадию выглядит следующим образом.

В случае с оплатой в две стадии схема блокировки средств через Payment Page с использованием метода Klarna идентична представленной схеме оплаты в одну стадию, с той разницей, что вместо незамедлительного списания средств инициируется и выполняется их предварительная блокировка.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом Klarna через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.

Формат запросов

При формировании запросов на открытие платёжной формы с применением метода Klarna необходимо учитывать следующее:

1. Должен использоваться базовый минимум параметров, обязательный для любого платежа:
   • project_id — идентификатор проекта, полученный от Ecommpay при интеграции;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
   • payment_amount — сумма платежа в дробных единицах валюты;
   • customer_id — идентификатор пользователя в рамках проекта.
2. Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
3. Для указания варианта проведения оплаты, отличного от заданного по умолчанию для используемого проекта, необходимо указывать параметр operation_type со значением sale (для незамедлительного списания средств при оплате в одну стадию) или auth (для предварительной блокировки средств при оплате в две стадии).
4. Должна указываться информация о пользователе через следующие параметры:
   • identify_doc_number — идентификатор документа, удостоверяющего личность пользователя, формат зависит от страны регистрации пользователя:
     • Швеция — Personal Identity Number вида YYYYMMDD-SSSS
     • Норвегия — National Identity Number вида DDMMYYIIIKK
     • Италия— Fiscal Code вида LLLLLLYYMMDDSSSC
     • Финляндия— Personal Identity Code вида DDMMYYCZZZQ
     • Испания— National Identity Document вида SSSSSSSSA
     • Дания— Personal Identification Number вида DDMMYY-SSSS
     • США— Social Secutity Number, состоит из 9 цифр
   • identify_doc_issue_country — код страны, в которой выпущен документ, удостоверяющий личность пользователя, в формате ISO 3166-1 alpha-2.
   • customer_account_info — информация об учётной записи пользователя на стороне веб-сервиса в виде строки, полученной в результате кодирования исходного JSON-объекта с применением алгоритма Base64. Этот объект должен включать в себя следующие объекты и параметры:
     • account — объект со сведениями об учётной записи пользователя на стороне веб-сервиса мерчанта:
       • date — дата создания учётной записи пользователя на стороне веб-сервиса в формате ДД-ММ-ГГГГ
       • loyalty_level — индикатор уровня пользователя в программе лояльности веб-сервиса мерчанта, (параметр можно не указывать, если в объект account включается объект purchase_history):
         • 01 — высокий
         • 02 — средний
         • 03 — низкий
       • purchase_history — массив объектов со сведениями о предыдущих заказах пользователя (параметр можно не указывать, если в объект account включается объект loyalty_level):
         • number_of_purchases — количество оформленных заказов за последние 12 месяцев
         • number_of_paid_purchases — количество оплаченных заказов за последние 12 месяцев
         • total_amount — общая сумма, на которую были сформированы заказы за последние 12 месяцев, в дробных единицах валюты, указанной в параметре currency этого же объекта
         • currency — код валюты для указанной суммы в формате ISO-4217 alpha-3
         • payment_method — указатель типа используемого платёжного инструмента, который может принимать одно из следующих значений: 01 — платёжная карта той платёжной системы, через которую инициируется проведение платежа, 02 — счёт с возможностью прямого списания средств, 03 — мобильный кошелёк, 04 — платёжная карта другой платёжной системы, 999 — иной инструмент.
         • first_purchase_at — дата и время первой покупки пользователя в веб-сервисе в формате ДД-ММ-ГГГГчч:мм
         • last_purchase_at — дата и время последней покупки пользователя в веб-сервисе в формате ДД-ММ-ГГГГчч:мм
   • purchase_data — информация о товарных позициях оплачиваемого заказа, представляет собой строку, полученную в результате кодирования исходного JSON-объекта с применением алгоритма Base64, и включает в себя массив объектов positions с различными сведениями из числа допустимых:
     • positions — массив, содержащий информацию о товарных позициях, относящихся с оплате, должен содержать хотя бы один объект, включающий в себя следующие параметры (для каждой позиции товаров или услуг):
       • type — указатель типа оплачиваемой позиции, который может принимать одно из следующих значений, определяющих состав необходимых параметров для указания в объекте positions: discount — скидка или промокод (на какие-либо товары или услуги), flight — авиаперелёт, car — аренда автомобиля, bus — поездка на автобусе, ferry — паромная переправа, train — поездка на поезде, hotel — проживание в отеле, voucher — ваучер или подарочный сертификат, insurance — страхование, event — посещение мероприятия (например, концерта или выставки), subscription — товар или услуга по подписке с регулярными списаниями (например, доступ к просмотру фильмов в онлайн-кинотеатре на месяц), ondemand — товар или услуга по подписке с нерегулярными списаниями (например, просмотр фильма в онлайн-кинотеатре), marketplace — товар или услуга на торговой площадке, product — товар иной категории, service — услуга иной категории, other — иной вид сервиса, оказываемого пользователю.
       • name — название позиции.
       • quantity — количество товаров или услуг в рамках позиции.
       • amount_total — итоговая стоимость товаров или услуг в рамках позиции, в дробных единицах валюты платежа или в виде дефиса (-) для позиций с типом discount.

         Для типов product, service, discount и other достаточно указания параметров type, name, quantity и amount_total.

     • Обязательность следующих параметров для указания в массиве positions зависит от типа позиции.

       • departure — объект, содержащий информацию о вылете:
         • airport — трёхбуквенный код, присвоенный аэропорту вылета Международной ассоциацией воздушного транспорта (IATA).
         • date — дата вылета в формате ДД-ММ-ГГГГ.
         • country — код страны в адресе места вылета в формате ISO 3166-1 alpha-2.
       • arrival — объект, содержащий информацию о прибытии:
         • airport — трёхбуквенный код, присвоенный аэропорту прибытия Международной ассоциацией воздушного транспорта (ИАТА).
         • country — код страны в адресе места прибытия в формате ISO 3166-1 alpha-2.
       • passengers — массив объектов со сведениями о пассажирах:
         • first_name — имя пассажира.
         • last_name — фамилия пассажира.

       • departure — объект, содержащий информацию об отправлении:
         • city — название города в адресе места отправления.
         • country — код страны в адресе места отправления в формате ISO 3166-1 alpha-2.
       • arrival — объект, содержащий информацию о прибытии:
         • city — название города в адресе места прибытия.
         • country — код страны в адресе места прибытия в формате ISO 3166-1 alpha-2.
       • passengers — массив объектов со сведениями о пассажирах:
         • first_name — имя пассажира.
         • last_name — фамилия пассажира.

       • departure — объект, содержащий информацию об отправлении:
         • date — дата отправления в формате ДД-ММ-ГГГГ.
         • city — название города в адресе места отправления.
         • country — код страны в адресе места отправления в формате ISO 3166-1 alpha-2.
       • arrival — объект, содержащий информацию о прибытии:
         • city — название города в адресе места прибытия.
         • country — код страны в адресе места прибытия в формате ISO 3166-1 alpha-2.
       • passengers — массив объектов со сведениями о пассажирах:
         • first_name — имя пассажира.
         • last_name — фамилия пассажира.

       • hotel_name — название объекта размещения (например, отеля или хостела).
       • start_date — дата начала оказания услуги (например, дата въезда в отель) в формате ДД-ММ-ГГГГ
       • end_date — дата окончания услуги (например, дата выезда из отеля) в формате ДД-ММ-ГГГГ.
       • city — название города в адресе объекта размещения.
       • country — код страны в адресе объекта размещения в формате ISO 3166-1 alpha-2.
       • guests — массив объектов со сведениями о постояльцах:
         • first_name — имя постояльца.
         • last_name — фамилия постояльца.

       • start_date — дата начала действия ваучера или сертификата в формате ДД-ММ-ГГГГ.
       • company — название организации, предоставляющей ваучер или сертификат.

       • event_type — тип мероприятия, возможные значения: CONCERT — концерт, FESTIVAL — фестиваль, TOUR — экскурсия или тур, IN_PERSON_EDUCATION — образовательное мероприятие в очном формате, DIGITAL_EDUCATION — образовательное мероприятие в формате онлайн, SPORT — спортивное мероприятие, CONFERENCE — конференция, EXPO — выставка.
       • start_date — дата начала мероприятия в формате ДД-ММ-ГГГГ.
       • end_date — дата окончания мероприятия в формате ДД-ММ-ГГГГ.
       • country — код страны в адресе места проведения мероприятия в формате ISO 3166-1 alpha-2.

       • billing_plans — массив объектов со сведениями о подписке:
         • start_date — дата начала списаний в формате ДД-ММ-ГГГГ, начиная со следующего дня от даты проведения платежа.
         • interval — указатель базового периода списаний, который может принимать одно из следующих значений:
           • DAY — день.
           • WEEK — неделя.
           • MONTH — месяц.
           • YEAR — год.
         • frequency — множитель для кратного увеличения базового периода списаний

       • interval — указатель ориентировочного базового периода списаний, который может принимать одно из следующих значений:
         • DAY — день.
         • WEEK — неделя.
         • MONTH — месяц.
         • YEAR — год.
       • frequency — множитель для кратного увеличения ориентировочного базового периода списаний.

       • seller — объект со сведениями о продавце на торговой площадке:
         • name — имя или название продавца на торговой площадке.
         • city — название города местонахождения продавца.
         • country — код страны местонахождения продавца в формате ISO 3166-1 alpha-2.
         • registation — дата регистрации продавца на торговой площадке в формате ДД-ММ-ГГГГ.
       • product_category — указатель категории товара или услуги, который может принимать одно из допустимых значений:
         • ACCESSORIES — аксессуары
         • APPLIANCES — бытовая техника
         • APPS_AND_GAMES — приложения и игры
         • ARTS_CRAFTS_AND_SEWING — товары для рукоделия и творчества
         • AUTOMOTIVE — товары для автомобилей
         • BEAUTY — товары для ухода за собой
         • BABY — товары для детей
         • BABY_CLOTHING — одежда для детей
         • BAGS_AND_PURSES — сумки и кошельки
         • BOOKS — книги и другие печатные издания
         • CDS_AND_VINYL — компакт-диски, виниловые пластинки и другие физические носители с аудиозаписями
         • CELL_PHONES_AND_ACCESSORIES — мобильные телефоны и аксессуары для них
         • COLLECTIBLES_AND_FINE_ARTS — предметы искусства и коллекционирования
         • DIGITAL_MUSIC — музыкальные записи в электронном формате
         • ELECTRONICS — электронные устройства
         • GROCERY_AND_GOURMET_FOOD — продукты питания и деликатесы
         • HANDMADE — изделия ручной работы
         • HEALTH_AND_PERSONAL_CARE — товары для здоровья и личной гигиены
         • HOME_AND_KITCHEN — товары для дома и кухни
         • INDUSTRIAL_AND_SCIENTIFIC — промышленное и научное оборудование
         • LUGGAGE_AND_TRAVEL_GEAR — чемоданы, дорожные аксессуары и другие товары для путешествий
         • MAGAZINE_SUBSCRIPTIONS — подписки на печатные или цифровые периодические издания
         • MEN_CLOTHING — мужская одежда
         • MUSICAL_INSTRUMENTS — музыкальные инструменты
         • OFFICE_PRODUCTS — офисные товары
         • PATIO_LAWN_AND_GARDEN — товары для сада и дачи
         • PET_SUPPLIES — товары для животных
         • SHOES — обувь
         • SOFTWARE — программное обеспечение
         • SPORTS_AND_OUTDOORS — товары для спорта и активного отдыха
         • TOOLS_AND_HOME_IMPROVEMENT — строительные инструменты и товары для ремонта
         • TOYS_AND_GAMES — игрушки и игры
         • VIDEO_GAMES — видеоигры
         • WOMEN_CLOTHING — женская одежда

   • additional_info — строковый объект с дополнительными сведениями, которые могут быть актуальны для проведения платежа в отдельных случаях:
     • integration_metadata, object — объект со сведениями о том, как технически был инициирован платёж:
       • originators, array of objects — массив объектов со сведениями о компонентах, использованных для инициирования платежа (на стороне веб-сервиса мерчанта; вплоть до шести объектов):
         • name, string — название пользовательского сервиса, с помощью которого был инициирован платёж, в виде прописных (заглавных) букв, цифр и нижних подчёркиваний (_) вместо пробелов (например, COSMO_GAMES_STORE)
         • module_name, string — название технического модуля, с помощью которого был инициирован платёж, например cosmoshopPlugin
         • module_version, string — номер версии технического модуля, с помощью которого был инициирован платёж, например 2.1
         • session_reference, string — идентификатор операции или сеанса работы в рамках веб-сервиса в виде универсального уникального идентификатора версии 7 (UUIDv7) в соответствии со стандартом RFC 9562, например 018b163d-0b83-7ba0-b837-da575d0ff824

5. Для соответствия пользовательского интерфейса требованиям сервиса Klarna рекомендуется указывать код языка отображения платёжной формы в параметре language_code и код региона в адресе проживания пользователя в параметре region_code. Код языка должен указываться в соответствии с кодом региона и следующими правилами соответствия.

   Код региона	Допустимые языки
   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

   Если в запросе не указывается код языка или указывается код, не соответствующий представленным правилам, платёжная форма отображается с использованием английского языка для основных элементов формы и возможным использованием основного национального языка для специфических элементов сервиса Klarna, что может вести к снижению конверсии.

6. Для предварительного выбора метода Klarna необходимо указывать код этого метода в параметре force_payment_method — klarna.
7. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
8. После указания всех целевых параметров необходимо составлять подпись (подробнее).

Таким образом, корректный запрос на открытие платёжной формы с применением метода Klarna должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе и товарных позициях, а также подпись.

{
  "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"
    }]
   }
  }
}

{
  "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"
    }]
   }
  }
}

Расширенный перечень допустимых параметров

В данном разделе представлен расширенный список параметров для указания в запросах на оплату. Обязательные параметры представлены в разделе Формат запросов.

"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_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"
    }
  ]

ImN1c3RvbWVyX3NoaXBwaW5nIjogWwogICAgewogICAgICAiZmlyc3RfbmFtZSI6ICJKb2huIiwKICAgICAgImxhc3RfbmFtZSI6ICJTbWl0aCIsCiAgICAgICJlbWFpbCI6ICJqb2huQGV4YW1wbGUuY29tIiwKICAgICAgInBob25lIjogIiszMTYxMjM0NTY3OCIsCiAgICAgICJhZGRyZXNzIjogIkhlcmVuZ3JhY2h0IDEwMSIsCiAgICAgICJhZGRyZXNzMiI6ICJIZXJlbmdyYWNodCAxMDEsIGFwdCAxIiwKICAgICAgInBvc3RhbCI6ICIxMDE1QkciLAogICAgICAiY2l0eSI6ICJBbXN0ZXJkYW0iLAogICAgICAicmVnaW9uX2NvZGUiOiAiTkgiLAogICAgICAiY291bnRyeSI6ICJOTCIsCiAgICAgICJ0eXBlIjogIlRPX0RPT1IiLAogICAgICAidHlwZV9hdHRyaWJ1dGVzIjogWwogICAgICAgICJUUkFDS0VEIiwKICAgICAgICAiU0lHTkFUVVJFX1JFUVVJUkVEIgogICAgICBdLAogICAgICAiY2FycmllciI6ICJQb3N0TkwiLAogICAgICAic2hpcHBpbmdfcmVmZXJlbmNlIjogIlNISVAtQ09NUFVURVItMSIKICAgIH0sCiAgICB7CiAgICAgICJmaXJzdF9uYW1lIjogIkphbmUiLAogICAgICAibGFzdF9uYW1lIjogIlNtaXRoIiwKICAgICAgImVtYWlsIjogImphbmVAZXhhbXBsZS5jb20iLAogICAgICAicGhvbmUiOiAiKzMxNjk4NzY1NDMyIiwKICAgICAgImFkZHJlc3MiOiAiS2VpemVyc2dyYWNodCAyNTAiLAogICAgICAiYWRkcmVzczIiOiAiS2VpemVyc2dyYWNodCAyNTAsIG9mZmljZSByZWNlcHRpb24iLAogICAgICAicG9zdGFsIjogIjEwMTZFViIsCiAgICAgICJjaXR5IjogIkFtc3RlcmRhbSIsCiAgICAgICJyZWdpb25fY29kZSI6ICJOSCIsCiAgICAgICJjb3VudHJ5IjogIk5MIiwKICAgICAgInR5cGUiOiAiVE9fRE9PUiIsCiAgICAgICJ0eXBlX2F0dHJpYnV0ZXMiOiBbCiAgICAgICAgIlRSQUNLRUQiLAogICAgICAgICJFWFBSRVNTIgogICAgICBdLAogICAgICAiY2FycmllciI6ICJESEwiLAogICAgICAic2hpcHBpbmdfcmVmZXJlbmNlIjogIlNISVAtQ09NUFVURVItMiIKICAgIH0KICBdCg==

"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"
    }
  ]

eyAKICAiY3VzdG9tZXIiOnsgCiAgICAiYWRkcmVzc19tYXRjaCI6IlkiLAogICAgImhvbWVfcGhvbmUiOiI3OTEwNTIxMTExMSIsCiAgICAid29ya19waG9uZSI6Ijc0OTU1MjExMTExIiwKICAgICJhY2NvdW50Ijp7IAogICAgICAiYWRkaXRpb25hbCI6ImdhbWVyMTIzNDUiLAogICAgICAiYWdlX2luZGljYXRvciI6IjAxIiwKICAgICAgImRhdGUiOiIwMS0xMC0yMDIyIiwKICAgICAgImNoYW5nZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJjaGFuZ2VfZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAicGFzc19jaGFuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAicGFzc19jaGFuZ2VfZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAicHVyY2hhc2VfbnVtYmVyIjoxMiwKICAgICAgInByb3Zpc2lvbl9hdHRlbXB0cyI6MTYsCiAgICAgICJhY3Rpdml0eV9kYXkiOjIyLAogICAgICAiYWN0aXZpdHlfeWVhciI6MjIyMiwKICAgICAgInBheW1lbnRfYWdlX2luZGljYXRvciI6IjAxIiwKICAgICAgInBheW1lbnRfYWdlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJzdXNwaWNpb3VzX2FjdGl2aXR5IjoiMDEiLAogICAgICAiYXV0aF9tZXRob2QiOiIwMSIsCiAgICAgICJhdXRoX3RpbWUiOiIwMS0xMC0yMDIyMTM6MTIiLAogICAgICAiYXV0aF9kYXRhIjoibG9naW5fMDEwMiIKICAgIH0KICB9Cn0==

Формат оповещений

Для оповещений о результатах оплат с применением метода Klarna используется типовой формат, описание которого представлено в разделе Работа с оповещениями.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 442 была проведена оплата в размере 10,00 EUR.

{
        "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=="
    }

В следующем примере оповещение свидетельствует об отклонённой оплате.

{
        "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=="
    }

Дополнительные материалы

Для организации работы с разовыми оплатами через Payment Page также могут быть полезны следующие материалы:

• Быстрый старт — инструкция по оперативной организации приёма платежей через Payment Page, с использованием SDK и примеров исходного кода.
• Организация взаимодействия — статья о том, как строится работа с платёжной платформой через Payment Page и как можно организовывать эту работу со стороны веб-сервиса в различных случаях.
• Работа с подписью к данным — статья о порядке создания и проверки подписи, используемой в программных запросах, ответах и оповещениях для обеспечения защищённого обмена данными при взаимодействии с платёжной платформой.
• Проведение платежей — статьи о типах платежей, которые можно проводить через платформу, схемах их проведения и допустимых операциях и статусах.
• Проведение оплат — статья о порядке проведения через Payment Page разовых одностадийных оплат с незамедлительными списаниями.
• Блокировка средств — статья о порядке выполнения через Payment Page предварительных блокировок средств в рамках разовых двухстадийных оплат с последующими списаниями.
• Работа с информацией об операциях — статья о статусах и служебных кодах, которые используются в платформе, чтобы фиксировать состояние операций и причины их отклонения.

Общая информация

Для выполнения возврата через Gate с использованием метода Klarna со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате. Полная схема выполнения возврата выглядит следующим образом.

Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом Klarna через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

Формат запросов

При работе с запросами на возвраты с применением метода Klarna необходимо учитывать следующее:

1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке /v2/payment/refund.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от Ecommpay при интеграции;,
     • payment_id — идентификатор платежа, для которого необходимо выполнить возврат;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее)),
   • payment — объект, содержащий сведения о возврате:
     • description — комментарий к возврату или его описание;
     • amount — сумма возврата в дробных единицах валюты (является обязательной при частичном возврате);,
     • currency — код валюты возврата в формате ISO-4217 alpha-3 (является обязательным при частичном возврате);,
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес пользователя, актуальный для инициируемого возврата.
   • purchase_data — массив с информацией о товарных позициях заказа, возврат по которым необходимо инициировать (в случае полного возврата необходимо указать все позиции, по которым была проведена оплата или блокировка средств). Структура и формат данных для указания в параметре совпадают с описанной в разделе Оплаты через Gate.
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на возврат с применением метода Klarna должен содержать идентификаторы проекта и платежа, описание возврата, IP-адрес пользователя, информацию о товарных позициях, подпись, а также, при необходимости, код валюты и сумму возврата.

{
  "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",
            }
          ]
}

{
  "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",
            }
          ]
}

Формат оповещений

Для оповещений о результатах возвратов с применением метода Klarna используется типовой формат, описание которого представлено в разделе Работа с оповещениями.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 442 был выполнен частичный возврат в размере 3,00 EUR.

{
        "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=="
    }

В следующем примере оповещение свидетельствует о возврате, отклонённом из-за превышения суммы оплаты.

{
        "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=="
    }

Дополнительные материалы

Для организации работы с возвратами через Gate также могут быть полезны следующие материалы:

• Организация взаимодействия — статья о том, как строится работа с платёжной платформой через Gate и как можно организовывать эту работу со стороны веб-сервиса, опираясь на используемые схемы и форматы взаимодействия.
• Работа с подписью к данным — статья о порядке создания и проверки подписи, используемой в программных запросах, ответах и оповещениях для обеспечения защищённого обмена данными при взаимодействии с платёжной платформой.
• Проведение платежей — статьи о типах платежей, которые можно проводить через платформу, схемах их проведения и допустимых операциях и статусах.
• Возвраты средств после оплат — статья о порядке выполнения через Gate возвратов по проведённым ранее оплатам разных типов.
• Работа с информацией об операциях — статья о статусах и служебных кодах, которые используются в платформе, чтобы фиксировать состояние операций и причины их отклонения.