Trustly

Обзор

Введение

Trustly — метод, позволяющий проводить платежи в разных валютах с использованием банковских счетов и платёжных карт в разных странах. Для этого метода в платёжной платформе ecommpay поддерживаются разовые и повторяемые оплаты, возвраты и выплаты.

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

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

Тип платёжного метода	банковские платежи
Платёжные инструменты	банковские счета платёжные карты
Регионы использования	AT, BE, BG, CY, CZ, DE, DK, EE, ES, FI, FR, GB, GR, HR, HU, IE, IT, LT, LU, LV, MT, NL, NO, PL, PT*, RO, SE, SI, SK
Валюты платежей	BGN, CZK, DKK, EUR, GBP, HUF, NOK, PLN, RON, SEK
Конвертация валют	на стороне Trustly
Разовые оплаты	+
Повторяемые оплаты	+ **
Полные возвраты	+
Частичные возвраты	+
Выплаты	+
Опротестования	–
Особенности	Для проведения платежей через Gate рекомендуется использовать Дополнение информации о платеже Для проведения платежей через Gate необходимо разместить логотип Trustly на вашей платёжной форме. Подробные требования к размещению можно узнать здесь. Скачать логотипы можно Время обработки выплаты зависит от банка получателя и может достигать трёх дней
Организация и стоимость подключения	по согласованию с курирующим менеджером ecommpay; дополнительную информацию можно получить в ecommshop

* Для данных стран доступно только проведение выплат.

** Повторяемые оплаты доступны только для пользователей, которые являются клиентами некоторых шведских банков.

Схема работы

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

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

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

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

	Суммы, EUR (или эквивалент)		Время ¹ ²
	минимум	максимум	базовое	предельное
Оплаты	1,00	–	*	*
Повторяемые оплаты	–	–	*	*
Возвраты	–	–	*	*
Выплаты	–	–	*	*

Прим.:

Как правило, проведение платежей с использованием сервиса Trustly укладывается в несколько минут, но в некоторых случаях оно может занимать большее время — вплоть до двух банковских дней и, при пересечении с выходными и праздничными днями, даже более. Подробную информацию при необходимости можно получить у курирующего менеджера ecommpay.
Базовое и предельное время определяются следующим образом:
- Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа (подробнее).
- Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус decline. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.

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

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

Рис.: Оплата через Payment Page

Рис.: Оплата через Gate

Рис.: Возврат через Gate

Рис.: Выплата через Gate

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

Оплаты через Payment Page

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

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

Рис.: Проведение оплаты через Payment Page. Описание шагов

Пользователь на стороне веб-сервиса инициирует оплату.
От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
Запрос на проведение оплаты поступает в платёжную платформу.
В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
Пользователю отображается платёжная форма.
Пользователь выбирает для оплаты метод Trustly.
В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Trustly.
В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис Trustly.
В сервисе Trustly выполняется обработка запроса на оплату.
От сервиса Trustly к платёжной платформе передаются данные для перенаправления пользователя к сервису Trustly.
Данные для перенаправления пользователя передаются к Payment Page.
Пользователь перенаправляется к сервису Trustly.
Пользователь выполняет необходимые действия для оплаты.
В сервисе Trustly выполняется обработка платежа.
От сервиса Trustly к платёжной платформе направляется информация о результате оплаты.
От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
От платёжной платформы к Payment Page направляется информация о результате оплаты.
Информация о результате оплаты отображается пользователю на Payment Page.

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

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

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

Должен использоваться базовый минимум параметров, обязательный для любого платежа:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
- payment_amount — сумма платежа в дробных единицах валюты;
- customer_id — идентификатор пользователя в рамках проекта.
Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
Валютой платежа может быть любая, указанная в разделе Характеристика.
Для проведения оплаты необходимы дополнительные параметры. Они не являются обязательными для открытия Payment Page, но всегда запрашиваются у пользователя, если не были переданы в запросе. Дополнительные (обязательные) параметры для проведения оплаты:
- customer_first_name — имя пользователя,
- customer_last_name — фамилия пользователя,
- customer_email — адрес электронной почты пользователя,
- customer_country — код страны в формате ISO 3166-1 alpha-2,
- language_code — язык платёжной формы в формате ISO 639-1 alpha-2.
Для предварительного выбора метода Trustly необходимо указывать код этого метода в параметре force_payment_method — online-banking-trustly.
Также могут быть запрошены дополнительные параметры, которые зависят от типа бизнеса мерчанта. Эти параметры можно передать в запросе на открытие платёжной формы или оставить их для заполнения пользователем на Payment Page.

Список возможных параметров:
- identify_doc_number — номер документа, подтверждающего личность пользователя;
- payment_extra_param — объект с дополнительными данными:
  - beneficiary — информация о получателе перевода денежных средств:
    - party_type — тип получателя (PERSON или ORGANISATION),
    - first_name — имя получателя (для организации значение параметра может быть пустым),
    - last_name — фамилия пользователя или наименование организации-получателя,
    - country — код страны в формате ISO 3166-1 alpha-2.
Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Рис.: Пример достаточного набора данных для запроса на оплату

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Корректный запрос на открытие платёжной формы для проведения оплат (с передачей дополнительных параметров) может выглядеть следующим образом.

"project_id": 100, 
"payment_id": "X03936",
"payment_amount": 1000,
"payment_currency": "EUR",
"signature": "kUi2x9dKHAVNU0FYldJrxh4yoJrOcZzUCwX6R\/ekpZhkIQg==",
"customer_id": "1234567",
"customer_first_name": "John",
"customer_last_name": "Smith",
"customer_email": "john.smith@example.com"
"customer_country": "SE",
"language_code": "en",
"identify_doc_number": "SE987546-654",
"payment_extra_param": {
    "beneficiary": {
        "party_type": "PERSON",
        "first_name": "Eddy",
        "last_name": "Stockmann",
        "country": "SE"
        }
    }    
}

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

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

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

Рис.: Пример данных из оповещения о проведении оплаты

 {
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_1561994171758",
            "type": "purchase",
            "status": "success",
            "date": "2019-07-01T15:26:40+0000",
            "method": "trustly",
            "sum": {
                "amount": 2000,
                "currency": "EUR"
            },
            "description": "ECT_TEST_1561994171752"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 28970000003316,
            "type": "sale",
            "status": "decline",
            "date": "2019-07-01T15:26:40+0000",
            "created_date": "2019-07-01T15:26:08+0000",
            "request_id": "63088b14f83a0bb48882dedfe2cc7fa6aaff",
            "sum_initial": {
                "amount": 2000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 2000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1246,
                "payment_id": "1076832",
                "date": "2019-07-01T15:26:39+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "GLZgBiriazPCzp3Kj+Pso7V1FNJvNc0Wssyl14X4HYxNwZJ94Q=="
    }
}

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

Рис.: Пример данных из оповещения об отклонении оплаты

 {
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_1561994171758",
            "type": "purchase",
            "status": "decline",
            "date": "2019-07-01T15:26:40+0000",
            "method": "trustly",
            "sum": {
                "amount": 2000,
                "currency": "EUR"
            },
            "description": "ECT_TEST_1561994171752"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 28970000003316,
            "type": "sale",
            "status": "decline",
            "date": "2019-07-01T15:26:40+0000",
            "created_date": "2019-07-01T15:26:08+0000",
            "request_id": "63088b14f83a0bb48882dedfe2cc7fa6aaff",
            "sum_initial": {
                "amount": 2000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 2000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1246,
                "payment_id": "1076832",
                "date": "2019-07-01T15:26:39+0000",
                "auth_code": ""
            },
            "code": "20301",
            "message": "Account owner cancelled operation"
        },
        "signature": "GLZgBiriazPCzp3Kj+Pso7V1FNJvNc0Wsl14X4HYxNwZJ94Q=="
    }
}

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

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

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

Оплаты через Gate

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

Для проведения оплаты через Gate с использованием метода Trustly со стороны веб-сервиса необходимо:

Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису Trustly.
Принять итоговое оповещение от платёжной платформы.

Полная схема проведения оплаты выглядит следующим образом.

Рис.: Проведение оплаты через Gate. Описание шагов

Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Trustly.
От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров) и его оправка в сервис Trustly.
В сервисе Trustly выполняется обработка запроса на оплату.
От сервиса Trustly к платёжной платформе передаются данные для перенаправления пользователя к сервису Trustly.
От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису Trustly.
Пользователь перенаправляется к сервису Trustly.
Пользователь выполняет необходимые действия для оплаты.
В сервисе Trustly выполняется обработка платежа.
От сервиса Trustly к платёжной платформе направляется информация о результате оплаты.
От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.

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

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

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

Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/online-banking/trustly/sale. Эта точка относится к группе /v2/payment/online-banking/{payment_method}/sale.
В каждом запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
  - project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
  - payment_id — идентификатор платежа, уникальный в рамках проекта;,
  - signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
- payment — объект, содержащий сведения о платеже:
  - amount — сумма платежа в дробных единицах валюты;,
  - currency — код валюты платежа в формате ISO-4217 alpha-3;,
- customer — объект, содержащий сведения о пользователе:
  - id — идентификатор пользователя, уникальный в рамках проекта;,
  - ip_address — IP-адрес пользователя, актуальный для инициируемого платежа;,
  - first_name — имя пользователя;,
  - last_name — фамилия пользователя;,
  - email — адрес электронной почты пользователя;,
  - country — код страны пользователя в формате ISO 3166-1 alpha-2;,
  - language — код языка пользователя в формате ISO 639-1;,
- return_url — объект, содержащий URL для перенаправления пользователя в веб-сервис:
  - success — URL для перенаправления пользователя после проведения оплаты;,
  - decline — URL для перенаправления пользователя после отклонения оплаты.
Валютой платежа может быть любая, указанная в разделе Характеристика.
Дополнительно может потребоваться передавать некоторые из следующих параметров:
- additional_data.beneficiary — информация о получателе перевода денежных средств:
  - party_type — тип получателя (PERSON или ORGANISATION);
  - first_name — имя получателя (для организации значение параметра может быть пустым);
  - last_name — фамилия пользователя или наименование организации-получателя;
  - country — код страны в формате ISO 3166-1 alpha-2.
Список дополнительных параметров для проведения платежа зависит от типа бизнеса мерчанта. Если веб-сервис мерчанта поддерживает уточнение дополнительных параметров, то после отправки запроса, содержащего только обязательные параметры, придёт оповещение со списком дополнительных параметров, необходимых для проведения платежа.

В противном случае все указанные в пунктах 2 и 4 параметры необходимо передавать в запросе на оплату.
Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
  "general": {
    "project_id": 200,
    "payment_id": "ECT_TEST_1561994171758",
    "signature": "+e6gss++zs/St78SnjY7M13MAerP3eTOLViNkA=="
  },
  "customer": {
    "id": "123",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Johnson"
  },
  "payment": {
    "amount": 2000,
    "currency": "EUR"
  },
  "return_url: {
    "success": "http://example.com/success",
    "decline": "http://example.com/decline"
  }
}

Рис.: Пример достаточного набора данных для запроса на оплату (при поддержке запросов на уточнение параметров)

{
  "general": {
    "project_id": 200,
    "payment_id": "ECT_TEST_1561994171758",
    "signature": "+e6gss++zs/St78SnjY7M13MAerP3eTOLViNkA=="
  },
  "customer": {
    "id": "123",
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Johnson"
  },
  "payment": {
    "amount": 2000,
    "currency": "EUR"
  },
  "return_url: {
    "success": "http://example.com/success",
    "decline": "http://example.com/decline"
  }
}

Формат промежуточных оповещений для перенаправления пользователей

Для перенаправления пользователей от веб-сервиса мерчанта к сервису Trustly при проведении каждого платежа с использованием метода Trustly необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data включаются следующие объекты и параметры:

body — объект с данными для отправки в теле запроса;
method — параметр с указанием HTTP-метода отправки запроса (GET или POST);
url — параметр со ссылкой для перенаправления.

Рис.: Пример объекта redirect_data

"redirect_data": {
       "body": [],
       "method": "GET",
       "url": "https://example.com/en/v1.1/payment/903d8cd4-b8e9-066727d8826c"
   }

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

Рис.: Пример данных из оповещения о проведении оплаты

 {
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_1561994171758",
            "type": "purchase",
            "status": "success",
            "date": "2019-07-01T15:26:40+0000",
            "method": "trustly",
            "sum": {
                "amount": 2000,
                "currency": "EUR"
            },
            "description": "ECT_TEST_1561994171752"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 28970000003316,
            "type": "sale",
            "status": "decline",
            "date": "2019-07-01T15:26:40+0000",
            "created_date": "2019-07-01T15:26:08+0000",
            "request_id": "63088b14f83a0bb48882dedfe2cc7fa6aaff",
            "sum_initial": {
                "amount": 2000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 2000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1246,
                "payment_id": "1076832",
                "date": "2019-07-01T15:26:39+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "GLZgBiriazPCzp3Kj+Pso7V1FNJvNc0Wssyl14X4HYxNwZJ94Q=="
    }
}

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

Рис.: Пример данных из оповещения об отклонении оплаты

 {
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_1561994171758",
            "type": "purchase",
            "status": "decline",
            "date": "2019-07-01T15:26:40+0000",
            "method": "trustly",
            "sum": {
                "amount": 2000,
                "currency": "EUR"
            },
            "description": "ECT_TEST_1561994171752"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 28970000003316,
            "type": "sale",
            "status": "decline",
            "date": "2019-07-01T15:26:40+0000",
            "created_date": "2019-07-01T15:26:08+0000",
            "request_id": "63088b14f83a0bb48882dedfe2cc7fa6aaff",
            "sum_initial": {
                "amount": 2000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 2000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1246,
                "payment_id": "1076832",
                "date": "2019-07-01T15:26:39+0000",
                "auth_code": ""
            },
            "code": "20301",
            "message": "Account owner cancelled operation"
        },
        "signature": "GLZgBiriazPCzp3Kj+Pso7V1FNJvNc0Wsl14X4HYxNwZJ94Q=="
    }
}

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

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

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

Повторяемые оплаты через Payment Page

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

Метод Trustly поддерживает проведение повторяемых оплат трёх типов: экспресс-оплаты, регулярные оплаты и автооплаты. Более подробная информация о типах повторяемых оплат представлена в разделе Регистрация повторяемых оплат.

Прим.: Повторяемые оплаты доступны только для пользователей, которые являются клиентами банков Швеции. Не все банки, доступные в рамках метода Trustly поддерживают проведение повторяемых оплат или некоторые их типы.

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

Регистрация повторяемых оплат

Для регистрации повторяемых оплат в момент проведения оплаты пользователь на платёжной форме Trustly должен согласиться на проведение повторяемых оплат с использованием сервиса Trustly. После успешного проведения оплаты по стандартной схеме, описанной в разделе Оплаты через Payment Page, в веб-сервис мерчанта должны прийти два оповещения:

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

Информация о зарегистрированном повторяемом платеже содержится в объекте recurring.

Рис.: Пример данных из оповещения о регистрации повторяемой оплаты

{
        "project_id": 1625,
        "payment": {
            "id": "ID_1234567890000",
            "type": "purchase",
            "status": "success",
            "date": "2019-09-16T15:18:02+0000",
            "method": "trustly",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "Trustly sale transaction"
        },
        "account": {
            "number": "1902377919"
        },
        "customer": {
            "id": "123"
        },
        "recurring": {
            "id": 1007592570,
            "currency": "EUR",
            "valid_thru": "2020-01-31T00:00:00+0000"
        },
        "operation": {
            "id": 6841000003665,
            "type": "sale",
            "status": "success",
            "date": "2019-09-16T15:18:03+0000",
            "created_date": "2019-09-16T15:15:13+0000",
            "request_id": "==request id==",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "provider": {
                "id": 1322,
                "payment_id": "1784257774",
                "date": "2019-09-16T15:18:02+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "ajfgtBiriazPCzp3Kj+PsoTBEyl14X4HYxNwZJ94Q=="
    }

Проведение экспресс-оплат

После успешной регистрации экспресс-оплаты могут проходить без авторизации пользователя с использованием сохранённых данных. В таком случае они проходят по следующей схеме:

Рис.: Проведение экспресс-оплаты через Payment Page. Описание шагов

Пользователь на стороне веб-сервиса инициирует оплату.
От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
Запрос на проведение оплаты поступает в платёжную платформу.
В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
Осуществляется подготовка Payment Page согласно параметрам проекта и вызова.
Пользователю отображается платёжная форма.
Пользователь выбирает для оплаты метод Trustly.
Пользователю отображается список сохранённых платёжных инструментов.
Пользователь выбирает сохранённый платёжный инструмент.
В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Trustly.
В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис Trustly.
В сервисе Trustly выполняется обработка запроса на оплату.
От сервиса Trustly к платёжной платформе направляется информация о результате оплаты.
От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
От платёжной платформы к Payment Page направляется информация о результате оплаты.
Информация о результате оплаты отображается пользователю на Payment Page.

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

Для оповещений о результатах экспресс-оплат с применением метода Trustly используется типовой формат, описание которого представлено в разделе Оповещения.

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

Рис.: Пример данных из оповещения о проведении повторяемой оплаты

{
        "project_id": 1625,
        "payment": {
            "id": "ID_1568639174831",
            "type": "recurring",
            "status": "success",
            "date": "2019-09-17T07:12:03+0000",
            "method": "trustly",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "Trustly COF purchase"
        },
        "customer": {
            "id": "123"
        },
        "recurring": {
            "id": 1007592570,
            "currency": "EUR"
        },
        "operation": {
            "id": 2110000003671,
            "type": "recurring",
            "status": "success",
            "date": "2019-09-17T07:12:03+0000",
            "created_date": "2019-09-17T07:10:02+0000",
            "request_id": "63088b14f83a0bb48882dedfe2cc7fa6aaff",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "provider": {
                "id": 1322,
                "payment_id": "1562050323",
                "date": "2019-09-17T07:12:01+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "khgsuyriazPCzp3Kj+Pso7V1FNJvNcTBEyl14X4HYxNwZJ94Q=="
    }

Повторяемые оплаты через Gate

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

Регистрация повторяемых оплат может быть выполнена двумя способами: при проведении первоначальной оплаты и во время проверки действительности платёжного инструмента. В обоих случаях пользователь даёт согласие на проведение повторяемых оплат на платёжной форме Trustly. Далее экспресс-оплаты могут проводиться без повторной авторизации пользователя на платёжной форме Trustly через Payment Page и Gate. Регулярные и автооплаты проводятся без участия пользователя через Gate.

Регистрация с помощью проверки действительности счёта

Схема регистрации повторяемых оплат с помощью запроса на проверку действительности счёта представлена далее.

Рис.: Схема регистрации повторяемых оплат с помощью проверки действительности счёта. Описание шагов

Пользователь на стороне веб-сервиса инициирует проверку счёта с использованием метода Trustly.
От веб-сервиса на заданный URL ecommpay передаётся запрос на проверку счёта через Gate.
Запрос на проверку счёта поступает в платёжную платформу ecommpay.
В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров) и его оправка в сервис Trustly.
В сервисе Trustly выполняется обработка запроса на проверку счёта.
От сервиса Trustly к платёжной платформе передаются данные для перенаправления пользователя к сервису Trustly.
От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису Trustly.
Пользователь перенаправляется к сервису Trustly.
Пользователь выполняет необходимые действия для проверки счёта и соглашается на регистрацию повторяемых оплат.
В сервисе Trustly выполняется проверка счёта пользователя.
От сервиса Trustly к платёжной платформе направляется информация о результате проверки.
От платёжной платформы к веб-сервису направляется оповещение о результате проверки.
На стороне веб-сервиса обеспечивается информирование пользователя о результате проверки.
От платёжной платформы к веб-сервису направляется повторное оповещение о результатах проверки с информацией о зарегистрированных повторяемых оплатах.

Формат запросов на проверку действительности счёта пользователя

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

Для инициирования каждой проверки должен использоваться отдельный POST-запрос к конечной точке /v2/payment/online-banking/trustly/account_verification. Эта точка относится к группе /v2/payment/online-banking/{payment_method}/account_verification.
В каждом запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
  - project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
  - payment_id — идентификатор платежа, уникальный в рамках проекта;,
  - signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
- payment — объект, содержащий сведения о платеже:
  - amount — сумма (всегда должно указываться значение 0) ;,
  - currency — код валюты платежа в формате ISO-4217 alpha-3;,
- customer — объект, содержащий сведения о пользователе:
  - id — идентификатор пользователя, уникальный в рамках проекта;,
  - ip_address — IP-адрес пользователя, актуальный для инициируемого платежа;,
- return_url — объект, содержащий URL для перенаправления пользователя в веб-сервис:
  - success — URL для перенаправления пользователя после проведения оплаты;,
  - decline — URL для перенаправления пользователя после отклонения оплаты;,
- recurring_register — признак необходимости регистрации повторяемых оплат. Значение параметра должно быть true.
- recurring — сведения о регистрации повторяемых оплат:
  - type — тип регистрируемых повторяемых оплат (экспресс-оплаты — C, регулярные оплаты — R, автооплаты — U),
  - Параметры, обязательные только для регулярных оплат:
    - time — время проведения повторяемой оплаты;,
    - expiry_year — год окончания действия подписки;,
    - expiry_month — месяц окончания действия подписки;,
    - expiry_day — день окончания действия подписки;,
    - interval — интервал между платежами в единицах выбранного периода,
    - amount — сумма повторяемой оплаты;,
    - period — периодичность проведения повторяемых оплат (D — каждый день, W — каждую неделю, M — каждый месяц, Q — каждый квартал или Y — каждый год);,
    - scheduled_payment_id — идентификатор следующей повторяемой оплаты;,
    - start_date — дата и время следующей повторяемой оплаты.
Валютой платежа может быть любая, указанная в разделе Характеристика.

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

{
    "general": {
        "project_id": 1625,
        "payment_id": "ID_1234567890001"
    },
    "customer": {
        "id": "123",
        "ip_address": "192.0.2.0"
    },
    "payment": {
        "amount": 0,
        "currency": "EUR"
    },
    "recurring_register": true,
    "recurring": {
        "type": "U",
        "expiry_year": 2020,
        "expiry_month": 1
    },
   "return_url: {
        "success": "http://example.com/success",
        "decline": "http://example.com/decline"
  }
}

Рис.: Пример достаточного набора данных для запроса на проверку действительности счёта пользователя для регистрации повторяемых оплат

{
    "general": {
        "project_id": 1625,
        "payment_id": "ID_1234567890001"
    },
    "customer": {
        "id": "123",
        "ip_address": "192.0.2.0"
    },
    "payment": {
        "amount": 0,
        "currency": "EUR"
    },
    "recurring_register": true,
    "recurring": {
        "type": "U",
        "expiry_year": 2020,
        "expiry_month": 1
    },
   "return_url: {
        "success": "http://example.com/success",
        "decline": "http://example.com/decline"
  }
}

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

Рис.: Пример данных из оповещения о действительности счёта пользователя в Trustly

{
        "project_id": 1625,
        "payment": {
            "id": "ID_1234567890001852",
            "type": "account_verification",
            "status": "success",
            "date": "2019-09-17T07:19:03+0000",
            "method": "trustly",
            "sum": {
                "amount": 0,
                "currency": "EUR"
            },
            "description": "Trustly account verification"
        },
        "account": {
            "number": "1902377919"
        },
        "customer": {
            "id": "123",
            "phone": "123456789"
        },
        "operation": {
            "id": 4311000003631,
            "type": "account verification",
            "status": "success",
            "date": "2019-09-17T07:19:03+0000",
            "created_date": "2019-09-17T07:16:47+0000",
            "request_id": "482f8f5649984daa9e09a4e0dfa03170947b5fd842",
            "sum_initial": {
                "amount": 0,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 0,
                "currency": "EUR"
            },
            "provider": {
                "id": 1322,
                "payment_id": "1212450138",
                "date": "2019-09-17T07:19:02+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "SkqaFkJww6bqUnh+4qslJyIRKnwlwKNGQqROpCrpOCNw=="
    }

Рис.: Пример данных из оповещения о регистрации повторяемых оплат

{
        "project_id": 1625,
        "payment": {
            "id": "ID_1234567890001",
            "type": "account_verification",
            "status": "success",
            "date": "2019-09-09T11:28:25+0000",
            "method": "trustly",
            "sum": {
                "amount": 0,
                "currency": "EUR"
            },
            "description": "Trustly account verification"
        },
        "account": {
            "number": "7840142519"
        },
        "customer": {
            "id": "123",
            "phone": "40000000361"
        },
        "recurring": {
            "id": 63374,
            "currency": "EUR",
            "valid_thru": "2035-01-31T00:00:00+0000"
        },
        "operation": {
            "id": 6517218122349,
            "type": "account verification",
            "status": "success",
            "date": "2019-09-09T11:28:27+0000",
            "created_date": "2019-09-09T11:28:20+0000",
            "request_id": "482f8f5649984daa9e09a4e0dfa03170947b5fd842",
            "sum_initial": {
                "amount": 0,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 0,
                "currency": "EUR"
            },
            "provider": {
                "id": 1407,
                "payment_id": "15680285012",
                "date": "2019-09-09T11:28:25+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "SkqaFkJww6bqUnh+4qsltDRmnwlwKNGQqROpCrpOCNw=="
    }

Регистрация с помощью первоначального платежа

Для регистрации повторяемых оплат в момент проведения оплаты пользователь на платёжной форме должен согласиться на регистрацию повторяемых оплат на платёжной форме Trustly. После успешного проведения оплаты по стандартной схеме, описанной в разделе Оплаты через Gate, в веб-сервис мерчанта должны прийти два оповещения:

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

Рис.: Пример данных из оповещения о регистрации повторяемых оплат

{
        "project_id": 1625,
        "payment": {
            "id": "ID_1234567890000",
            "type": "purchase",
            "status": "success",
            "date": "2019-09-16T15:18:02+0000",
            "method": "trustly",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "Trustly sale"
        },
        "account": {
            "number": "1902377919"
        },
        "customer": {
            "id": "123"
        },
        "recurring": {
            "id": 1007592570,
            "currency": "EUR",
            "valid_thru": "2020-01-31T00:00:00+0000"
        },
        "operation": {
            "id": 6841000003665,
            "type": "sale",
            "status": "success",
            "date": "2019-09-16T15:18:03+0000",
            "created_date": "2019-09-16T15:15:13+0000",
            "request_id": "khafkuasf575akhafykhaj0cd7absw",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "provider": {
                "id": 1322,
                "payment_id": "1784257774",
                "date": "2019-09-16T15:18:02+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "ajfgtBiriazPCzp3Kj+Pso7V1FX4HYxNwZJ94Q=="
    }

Проведение экспресс-оплат

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

Рис.: Проведение оплаты через Gate. Описание шагов

Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Trustly.
От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
Запрос на проведение оплаты поступает в платёжную платформу ecommpay.
В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
В платёжной платформе выполняются дальнейшая обработка запроса (с проверкой согласованности параметров) и его оправка в сервис Trustly.
В сервисе Trustly выполняется обработка запроса на оплату.
От сервиса Trustly к платёжной платформе направляется информация о результате оплаты.
От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты.

Формат запросов для экспресс-оплат

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

Для инициирования каждой экспресс-оплаты должен использоваться отдельный POST-запрос к конечной точке v2/payment/online-banking/trustly/sale/saved. Эта точка относится к группе /v2/payment/online-banking/{payment_method}/sale/saved.
В каждом запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
  - project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
  - payment_id — идентификатор платежа, уникальный в рамках проекта;,
  - signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
- payment — объект, содержащий сведения о платеже:
  - amount — сумма платежа в дробных единицах валюты;,
  - currency — код валюты платежа в формате ISO-4217 alpha-3;,
- customer — объект, содержащий сведения о пользователе:
  - id — идентификатор пользователя, уникальный в рамках проекта;,
  - ip_address — IP-адрес пользователя, актуальный для инициируемого платежа.
- return_url — объект, содержащий URL для перенаправления пользователя в веб-сервис:
  - success — URL для перенаправления пользователя после проведения оплаты;,
  - decline — URL для перенаправления пользователя после отклонения оплаты;,
- recurring_id — идентификатор повторяемой оплаты.
Валютой платежа может быть любая, указанная в разделе Характеристика.

Таким образом, корректный запрос на проведение экспресс-оплаты с применением метода Trustly должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), идентификатор и IP-адрес пользователя, URL для перенаправлния, идентификатор повторяемой оплаты, а также подпись.

{
  "general": {
    "project_id": 1625,
    "payment_id": "ID_1568639174831"
  },
  "customer": {
    "id": "123",
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 100,
    "currency": "EUR",
    "description": "Trustly one-click"
  },
  "recurring": {
    "id": 62944
  }
}

Рис.: Пример достаточного набора данных для запроса на проведение экспресс-оплаты

{
  "general": {
    "project_id": 1625,
    "payment_id": "ID_1568639174831"
  },
  "customer": {
    "id": "123",
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 100,
    "currency": "EUR",
    "description": "Trustly one-click"
  },
  "recurring": {
    "id": 62944
  }
}

Формат запросов для регулярных оплат и автооплат

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

Для инициирования каждой повторяемой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/online-banking/trustly/recurring. Эта точка относится к группе /v2/payment/online-banking/{payment_method}/recurring.
В каждом запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
  - project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
  - payment_id — идентификатор платежа, уникальный в рамках проекта;,
  - signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
- payment — объект, содержащий сведения о платеже:
  - amount — сумма платежа в дробных единицах валюты;,
  - currency — код валюты платежа в формате ISO-4217 alpha-3;,
- customer — объект, содержащий сведения о пользователе:
  - id — идентификатор пользователя, уникальный в рамках проекта;,
  - ip_address — IP-адрес пользователя, актуальный для инициируемого платежа.
- recurring_id — идентификатор зарегистрированной повторяемой оплаты.
Валютой платежа может быть любая, указанная в разделе Характеристика.

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

{
  "general": {
    "project_id": 1625,
    "payment_id": "ID_1568639174831"
  },
  "customer": {
    "id": "123",
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 100,
    "currency": "EUR",
    "description": "Trustly recurring"
  },
  "recurring": {
    "id": 1007592570
  }
}

Рис.: Пример достаточного набора данных для запроса на повторяемую оплату

{
  "general": {
    "project_id": 1625,
    "payment_id": "ID_1568639174831"
  },
  "customer": {
    "id": "123",
    "ip_address": "192.0.2.0"
  },
  "payment": {
    "amount": 100,
    "currency": "EUR",
    "description": "Trustly recurring"
  },
  "recurring": {
    "id": 1007592570
  }
}

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

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

Рис.: Пример данных из оповещения о проведении повторяемой оплаты

{
        "project_id": 1625,
        "payment": {
            "id": "ID_1568639174831",
            "type": "recurring",
            "status": "success",
            "date": "2019-09-17T07:12:03+0000",
            "method": "trustly",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "Trustly COF purchase"
        },
        "customer": {
            "id": "123"
        },
        "recurring": {
            "id": 1007592570,
            "currency": "EUR"
        },
        "operation": {
            "id": 2110000003671,
            "type": "recurring",
            "status": "success",
            "date": "2019-09-17T07:12:03+0000",
            "created_date": "2019-09-17T07:10:02+0000",
            "request_id": "63088b14f83a0bb48882dedfe2cc7fa6aaff",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "provider": {
                "id": 1322,
                "payment_id": "1562050323",
                "date": "2019-09-17T07:12:01+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "khgsuyriazPCzp3Kj+Pso7V1FNJvN9eTBEyl14X4HYxNwZJ94Q=="
    }

Возвраты через Gate

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

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

Рис.: Выполнение возврата через Gate. Описание шагов

Пользователь инициирует возврат.
От веб-сервиса на заданный URL ecommpay передаётся запрос на выполнение возврата.
Запрос на выполнение возврата поступает в платёжную платформу ecommpay.
В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности (подробнее).
В платёжной платформе обеспечиваются дальнейшая обработка запроса (с проверкой согласованности параметров) и его отправка в сервис Trustly.
В сервисе Trustly выполняется обработка возврата.
От сервиса Trustly к платёжной платформе направляется информация о результате возврата.
От платёжной платформы к веб-сервису направляется оповещение о результате возврата.
На стороне веб-сервиса обеспечивается информирование пользователя о результате возврата.

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

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

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

Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке /v2/payment/online-banking/trustly/refund. Эта точка относится к группе /v2/payment/online-banking/{payment_method}/refund.
В каждом запросе должны использоваться следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
  - project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
  - payment_id — идентификатор платежа, для которого необходимо выполнить возврат;,
  - signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее)),
- payment — объект, содержащий сведения о возврате:
  - description — комментарий к возврату или его описание;,
  - amount — сумма возврата в дробных единицах валюты (является обязательной при частичном возврате);,
  - currency — код валюты возврата в формате ISO-4217 alpha-3 (является обязательным при частичном возврате);,
- customer — объект, содержащий сведения о пользователе:
  - ip_address — IP-адрес пользователя, актуальный для инициируемого возврата.
Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на возврат с применением метода Trustly должен содержать идентификаторы проекта и платежа, описание возврата, 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"
  }
}

Рис.: Пример достаточного набора данных для запроса на возврат

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

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 1625 для пользователя 125 был выполнен возврат в на счёт № 1902377919.

Рис.: Пример данных из оповещения о выполнении возврата

{
        "project_id": 1625,
        "payment": {
            "id": "ID_1234567890000",
            "type": "purchase",
            "status": "partially refunded",
            "date": "2019-09-18T12:25:39+0000",
            "method": "trustly",
            "sum": {
                "amount": 500,
                "currency": "EUR"
            },
            "description": "test payment"
        },
        "account": {
            "number": "1902377919"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 6841000003971,
            "type": "refund",
            "status": "success",
            "date": "2019-09-18T12:25:39+0000",
            "created_date": "2019-09-18T12:25:36+0000",
            "request_id": "719ecb2f23f3d482fabb0c5994700fb36b020735ba3c2ae",
            "sum_initial": {
                "amount": 500,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 500,
                "currency": "EUR"
            },
            "provider": {
                "id": 1322,
                "payment_id": "1784257774",
                "date": "2019-09-18T12:25:37+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "xCafDfCf+h8/5+SB+o6vUQDVS7+C11AtFi+nDhLMcYMzA=="
    }

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

Рис.: Пример данных из оповещения об отклонении возврата

{
        "project_id": 1625,
        "payment": {
            "id": "ID_1234567890000",
            "type": "purchase",
            "status": "success",
            "date": "2019-09-18T12:25:39+0000",
            "method": "trustly",
            "sum": {
                "amount": 500,
                "currency": "EUR"
            },
            "description": "test payment"
        },
        "account": {
            "number": "1902377919"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 6841000003971,
            "type": "refund",
            "status": "decline",
            "date": "2019-09-18T12:25:39+0000",
            "created_date": "2019-09-18T12:25:36+0000",
            "request_id": "719ecb2f23f3d482fabb0c5994700fb36b020735ba3c2ae",
            "sum_initial": {
                "amount": 500,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 500,
                "currency": "EUR"
            },
            "provider": {
                "id": 1322,
                "payment_id": "1784257774",
                "date": "2019-09-18T12:25:37+0000",
                "auth_code": ""
            },
            "code": "20106",
            "message": "Customer account is no longer available"
        },
        "signature": "xCafDfCf+h8/5+SB+o6vUQDVS7hOTwnZxttFi+nDhLMcYMzA=="
    }

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

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

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

Выплаты через Gate

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

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

Рис.: Проведение выплаты через Gate. Описание шагов

Пользователь на стороне веб-сервиса инициирует выплату через Trustly.
От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение выплаты через Gate.
Запрос на проведение выплаты поступает в платёжную платформу.
В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи.
От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее — в разделе Формат ответа.
В платёжной платформе обеспечиваются дальнейшая обработка запроса (с проверкой согласованности параметров) и его отправка в сервис Trustly.
В сервисе Trustly выполняется обработка выплаты.
От сервиса Trustly к платёжной платформе направляется информация о результате выплаты.
От платёжной платформы к веб-сервису направляется оповещение о результате выплаты.
На стороне веб-сервиса обеспечивается информирование пользователя о результате выплаты.

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

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

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

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

Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/online-banking/trustly/payout. Эта точка относится к группе /v2/payment/online-banking/{payment_method}/payout.

В каждом запросе должны использоваться следующие объекты и параметры:

general — объект, содержащий основные идентификационные сведения запроса:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
- payment_id — идентификатор платежа, уникальный в рамках проекта;,
- signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
payment — объект, содержащий сведения о платеже:
- amount — сумма выплаты в дробных единицах валюты;,
- currency — код валюты платежа в формате ISO-4217 alpha-3;,
customer — объект, содержащий сведения о пользователе:
- id — идентификатор пользователя, уникальный в рамках проекта;,
- ip_address — IP-адрес пользователя, актуальный для инициируемой выплаты;,
- first_name — имя пользователя;,
- last_name — фамилия пользователя;,

account — объект, содержащий сведения о банковском счёте получателя:

number — номер счёта;,
clearinghouse — страна, в которой зарегистрирован межбанковский расчётный центр, с которым сотрудничает банк получателя. Допустимые значения параметра указаны в таблице Соответствие значений параметров;,
bank_code — международный банковский идентификационный код (БИК или SWIFT) или код, специфичный для межбанковских расчётных центров некоторых стран, указанных в таблице Соответствие значений параметров (в таких случаях значение параметра определяется регулярным выражением);,

Допустимые значения параметров number и bank_code зависят от значения параметра clearinghouse. Значение параметра number определяется регулярными выражениями, соответствующими указанному значению параметра clearinghouse. Значение параметра bank_code определятся регулярными выражениями только когда в значении этого параметра не требуется указать БИК или SWIFT-код, в остальных случаях значение не определяется регулярным выражением (соответствующие ячейки таблицы не заполнены). В следующей таблице указаны соответствия значений параметра clearinghouse и регулярных выражений.

Табл. 1. Соответствие значений параметров
`clearinghouse`	`bank_code`	`number`
AUSTRIA		^AT[0-9]{18}$
BELGIUM		^BE[0-9]{14}$
BULGARIA		^BG[0-9]{2}[A-Z]{4}[0-9]{4}[0-9]{2}[A-Z0-9]{8}$
CROATIA		^HR[0-9]{2}[0-9]{7}[0-9]{10}$
CYPRUS		^CY[0-9]{10}[0-9A-Z]{16}$
CZECH_REPUBLIC	^[0-9]{4}$	^[0-9]{16}$
DENMARK	^[0-9]{4}$	^[0-9]{4,10}$
ESTONIA	^[0-9]{2}$	^[0-9]{4,14}$
FINLAND		^FI[0-9]{16}$
FRANCE		^FR[0-9]{12}[0-9A-Z]{11}[0-9]{2}$
GERMANY		^DE[0-9]{20}$
GREECE		^GR[0-9]{25}$
HUNGARY	^[0-9]{8}$	^[0-9]{24}$
IRELAND		^IE[0-9]{2}[A-Z]{4}[0-9]{14}$
ITALY		^IT[0-9]{2}[A-Z][0-9]{10}[0-9A-Z]{12}$
LATVIA		^LV[0-9]{2}[A-Z]{4}[0-9A-Z]{13}$
LITHUANIA		^LT[0-9]{18}$
LUXEMBOURG		^LU[0-9]{18}$
MALTA		^MT[0-9]{2}[A-Z]{4}[0-9]{5}[0-9A-Z]{18}$
NETHERLANDS		^NL[0-9]{2}[A-Z]{4}[0-9]{10}$
NORWAY	^[0-9]{4}$	^[0-9]{7}$
POLAND		^PL[0-9]{26}$
PORTUGAL	^[0-9]{8}$	^[0-9]{13}$
ROMANIA		^RO[0-9]{2}[A-Z]{4}[0-9A-Z]{16}$
SLOVAKIA		^SK[0-9]{22}$
SLOVENIA		^SI56[0-9]{15}$
SPAIN		^ES[0-9]{22}$
SWEDEN	^[0-9]{4,5}$	^[0-9]{1,15}$
UNITED_KINGDOM	^[0-9]{6}$	^[0-9]{8}$

Мерчантам, оказывающим услуги, связанные с переводами денежных средств на электронные кошельки или в другие кредитные организации, когда отправителем является не мерчант, но третья сторона, необходимо указать данные отправителя в объекте additional_data.sender:
- party_type — тип отправителя: "PERSON" или "ORGANISATION",
- first_name — имя отправителя или название организации,
- last_name — фамилия отправителя или null для организации,
- address — адрес отправителя (за исключением страны),
- country — страна отправителя в формате ISO 3166-1 alpha-2.
Валютой платежа может быть любая, указанная в разделе Характеристика.
Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
  "general": {
    "project_id": 112,
    "payment_id": "ECT_TEST_156"
  },
  "payment": {
    "amount": 100,
    "currency": "EUR",
    "description": "Trustly account payout"
  },
  "customer": {
    "id": "123",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "ip_address": "192.0.2.0"
  },
  "account": {
    "clearinghouse": "SWEDEN",
    "bank_code": "1234",
    "number": "21312"
  }
 }

Рис.: Пример достаточного набора данных для запроса на выплату

{
  "general": {
    "project_id": 112,
    "payment_id": "ECT_TEST_156"
  },
  "payment": {
    "amount": 100,
    "currency": "EUR",
    "description": "Trustly account payout"
  },
  "customer": {
    "id": "123",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "ip_address": "192.0.2.0"
  },
  "account": {
    "clearinghouse": "SWEDEN",
    "bank_code": "1234",
    "number": "21312"
  }
 }

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

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

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

Рис.: Пример данных из оповещения о проведении выплаты

 {
        "project_id": 1625,
        "payment": {
            "id": "ECT_TEST_1568711984262232",
            "type": "payout",
            "status": "success",
            "date": "2019-09-18T07:18:03+0000",
            "method": "trustly",
            "sum": {
                "amount": 5000,
                "currency": "EUR"
            },
            "description": "Trustly payout"
        },
        "account": {
            "number": "1902377919"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 20988000004401,
            "type": "payout",
            "status": "success",
            "date": "2019-09-18T07:18:03+0000",
            "created_date": "2019-09-18T07:12:38+0000",
            "request_id": "821d7c5b4d08587252da9834ab50590d8d4d976d26801a",
            "sum_initial": {
                "amount": 5000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 5000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1322,
                "payment_id": "3063307773",
                "date": "2019-09-18T07:13:03+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "fKyx/vYDhDNxQ0myVETvkXfj7r+4Z1lcEp/7dbL4ip+=="
    }

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

Рис.: Пример данных из оповещения об отклонении выплаты

 {
        "project_id": 1625,
        "payment": {
            "id": "ECT_TEST_1568711984262232",
            "type": "payout",
            "status": "decline",
            "date": "2019-09-18T07:18:03+0000",
            "method": "trustly",
            "sum": {
                "amount": 5000,
                "currency": "EUR"
            },
            "description": "Trustly payout"
        },
        "account": {
            "number": "1902377919"
        },
        "customer": {
            "id": "123"
        },
        "operation": {
            "id": 20988000004401,
            "type": "payout",
            "status": "decline",
            "date": "2019-09-18T07:18:03+0000",
            "created_date": "2019-09-18T07:12:38+0000",
            "request_id": "821d7c5b4d08587252da9834ab50590d8d4d976d26801a",
            "sum_initial": {
                "amount": 5000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 5000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1322,
                "payment_id": "3063307773",
                "date": "2019-09-18T07:13:03+0000",
                "auth_code": ""
            },
            "code": "3028",
            "message": "Insufficient funds on merchant balance"
        },
        "signature": "jfhgfvYDhDNxQ0myVETvkXfj7r+4Z1lcEp/7dbOSgr5CXprwe8LPw=="
    }

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

Рис.: Пример данных из оповещения об отклонении выплаты

{
        "customer": {
            "id": "123999"
        },
        "account": {
            "number": "20227678"
        },
        "project_id": 10801,
        "payment": {
            "id": "16042021_002",
            "type": "payout",
            "status": "reversed",
            "date": "2021-04-16T14:41:57+0000",
            "method": "trustly",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "Trustly Payout"
        },
        "operation": {
            "id": 13858010014811,
            "type": "payout reversal",
            "status": "success",
            "date": "2021-04-16T14:41:57+0000",
            "created_date": "2021-04-16T14:41:57+0000",
            "request_id": "153cb9c8b675-9c397f2dbec1bc-00013859",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1322,
                "payment_id": "6777981238"
            }
        },
        "signature": "S3Hc3cND9GVS1zITz/UVEE8ZEVWqEw=="
    }
}

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

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

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

Анализ результатов проведения платежей

Для анализа информации о платежах и операциях, как в отдельности по методу Trustly, так и в совокупности с другими методами, можно использовать:

инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
данные в формате JSON, получаемые по программным запросам через интерфейс Data API.

С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.