Использование динамического мерчант-дескриптора

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

При проведении карточных платежей 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 символов, в числе которых могут использоваться буквы латинского алфавита из состава базовой латиницы, цифры и следующие специальные символы.

Если это согласовано, переданные в запросе сведения включаются в состав итоговых оповещений в параметре 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...=="
}