Использование динамического мерчант-дескриптора
Общая информация
При проведении карточных платежей ecommpay согласно правилам платёжных систем передаёт другим участвующим в процессе сторонам сведения о мерчантах. В состав этих сведений входят название организации и код её страны, а также информация о городе расположения или иных атрибутах, таких как номер телефона или адрес веб-сервиса, с учётом рекомендаций платёжных систем и предпочтений мерчанта. В результате участвующие в проведении платежей стороны могут использовать эти сведения в своей работе. В частности, эмитенты могут указывать их в уведомлениях и банковских выписках, что позволяет пользователям чётче идентифицировать мерчантов и платежи, а мерчантам — улучшать пользовательский опыт и снижать вероятность опротестования платежей со стороны пользователей.
При проведении карточных платежей ecommpay согласно правилам платёжных систем передаёт другим участвующим в процессе сторонам сведения о мерчантах: название организации и код её страны, а также информацию о городе расположения или иных атрибутах. За счёт этого такие сведения могут указываться эмитентами в уведомлениях и банковских выписках, а также использоваться другими участниками платежей.
Рис.: Уведомление с указанием города
Рис.: Уведомление с указанием адреса веб-сервиса
Рис.: Уведомление с указанием кода
Базовые сведения о каждом мерчанте регистрируются в платёжной платформе при подключении к ней веб-сервиса мерчанта с привязкой к его идентификатору (Merchant ID, MID). Они являются условно постоянными и могут меняться через обращения к курирующему менеджеру ecommpay. Вместе с тем, часть сведений о мерчанте, так называемый динамический дескриптор, может быть переменной и меняться от операции к операции на основе информации, поступающей в запросах. В таких случаях в состав сведений о мерчанте включаются базовые значения для названия организации и кода её страны, а также информация из запросов. Это позволяет использовать более подходящую к каждому конкретному случаю информацию, например адрес страницы управления подпиской при выполнении списаний по ней.
Использовать переменные сведения о мерчанте можно при проведении разовых оплат в одну стадию и повторяемых оплат, а также при выполнении возвратов по таким оплатам. При этом передаваемые данные ограничиваются лишь длиной строки и составом допустимых символов (подробнее далее), что позволяет применять эту возможность достаточно гибко, в том числе для аутентификации пользователей с использованием проверочных кодов (аналогично аутентификации по инициативе мерчанта), передавая такие коды в запросах для их последующего указания пользователями в веб-сервисе.
Базовые сведения о каждом мерчанте регистрируются в платёжной платформе при подключении к ней веб-сервиса мерчанта с привязкой к его идентификатору (Merchant ID, MID). Часть этих сведений может быть переменной и меняться для отдельных операций (оплат в одну стадию, повторяемых оплат и возвратов) на основе информации, поступающей в запросах на выполнение этих операций. В таких случаях в состав сведений о мерчанте включаются базовые значения для названия организации и кода её страны, а также информация из запросов.
Подключение
Регистрация базовых сведений о мерчанте выполняется сотрудниками ecommpay и не требует участия мерчанта. Возможность использования переменных сведений, а также включение указанных сведений о мерчанте в состав итоговых оповещений о выполнении операций можно согласовывать с курирующим менеджером ecommpay. После согласования специалисты ecommpay выполняют необходимые настройки в платёжной платформе и уведомляют о готовности к работе с переменными описаниями.
Возможность использования переменных сведений, а также включение указанных сведений о мерчанте в состав итоговых оповещений о выполнении операций можно согласовывать с курирующим менеджером ecommpay. После согласования специалисты ecommpay выполняют необходимые настройки в платёжной платформе и уведомляют о готовности к работе с переменными описаниями.
Использование
После подключения возможности использования переменных описаний можно указывать необходимую информацию в параметре descriptor
объекта merchant
запроса. Это могут быть запросы к следующим конечным точкам:
- /v2/payment/card/sale — для разовых одностадийных оплат с прямым указанием платёжных данных;
- /v2/payment/card/sale/saved — для разовых одностадийных оплат с указанием платёжных данных через идентификаторы;
- /v2/payment/card/sale/token — для разовых одностадийных оплат с указанием платёжных данных через токены;
- /v2/payment/card/recurring — для повторяемых оплат;
- /v2/payment/card/refund — для возвратов средств по проведённым оплатам.
- /v2/payment/card/sale,
- /v2/payment/card/sale/saved,
- /v2/payment/card/sale/token,
- /v2/payment/card/recurring,
- /v2/payment/card/refund.
Параметр descriptor
может содержать не более 13 символов, в числе которых могут использоваться буквы латинского алфавита из состава базовой латиницы, цифры и следующие специальные символы.
" | U+0022 | двойной штрих |
# | U+0023 | решётка (октоторп) |
$ | U+0024 | знак доллара |
' | U+0027 | штрих |
( | U+0028 | левая круглая скобка |
) | U+0029 | правая круглая скобка |
` | U+0060 | гравис |
* | U+002A | звёздочка (астериск) |
+ | U+002B | знак сложения |
, | U+002C | запятая |
- | U+002D | дефис |
. | U+002E | точка |
/ | U+002F | косая разделительная черта |
: | U+003A | двоеточие |
; | U+003B | точка с запятой |
= | U+003D | знак равенства |
? | U+003F | знак вопроса |
\ | U+005C | косая обратная черта |
^ | U+005E | каре |
_ | U+005F | нижняя линия (подчёркивание) |
" | U+0022 | двойной штрих |
# | U+0023 | решётка (октоторп) |
$ | U+0024 | знак доллара |
' | U+0027 | штрих |
( | U+0028 | левая круглая скобка |
) | U+0029 | правая круглая скобка |
` | U+0060 | гравис |
* | U+002A | звёздочка (астериск) |
+ | U+002B | знак сложения |
, | U+002C | запятая |
- | U+002D | дефис |
. | U+002E | точка |
/ | U+002F | косая разделительная черта |
: | U+003A | двоеточие |
; | U+003B | точка с запятой |
= | U+003D | знак равенства |
? | U+003F | знак вопроса |
\ | U+005C | косая обратная черта |
^ | U+005E | каре |
_ | U+005F | нижняя линия (подчёркивание) |
Если это согласовано, переданные в запросе сведения включаются в состав итоговых оповещений в параметре merchantDescriptor
.
Рис.: Пример данных из оповещения
{ "account": { "number": "431422******0056", "token": "f365bb1729f9b72fd9d18070d15654", "type": "visa", "card_holder": "ALBERT ASTONE", "id": 45678, "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "cosmo_customer_12" }, "payment": { "date": "2022-06-23T09:07:00+0000", "id": "456789", "method": "card", "status": "success", "sum": { "amount": 2990, "currency": "USD" }, "type": "purchase", "description": "Cosmoshop order" }, "project_id": 42, "operation": { "id": 969000002636, "type": "sale", "status": "success", "date": "2022-06-23T09:08:00+0000", "created_date": "2022-06-23T09:07:45+0000", "request_id": "c6eed1e086d...d0413246c", "sum_initial": { "amount": 2990, "currency": "USD" }, "sum_converted": { "amount": 2990, "currency": "USD" }, "merchantDescriptor": "cosmoshop.com", // сведения о мерчанте "code": "0", "message": "Success", }, "signature": "v7KNMpfogAx1ZZ5D/aZAebMdeR+CqGilUwSm...==" }
Рис.: Пример данных из оповещения
{ "account": { "number": "431422******0056", "token": "f365bb1729f9b72fd9d18070d15654", "type": "visa", "card_holder": "ALBERT ASTONE", "id": 45678, "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "cosmo_customer_12" }, "payment": { "date": "2022-06-23T09:07:00+0000", "id": "456789", "method": "card", "status": "success", "sum": { "amount": 2990, "currency": "USD" }, "type": "purchase", "description": "Cosmoshop order" }, "project_id": 42, "operation": { "id": 969000002636, "type": "sale", "status": "success", "date": "2022-06-23T09:08:00+0000", "created_date": "2022-06-23T09:07:45+0000", "request_id": "c6eed1e086d...d0413246c", "sum_initial": { "amount": 2990, "currency": "USD" }, "sum_converted": { "amount": 2990, "currency": "USD" }, "merchantDescriptor": "cosmoshop.com", // сведения о мерчанте "code": "0", "message": "Success", }, "signature": "v7KNMpfogAx1ZZ5D/aZAebMdeR+CqGilUwSm...==" }