Отправка уведомлений пользователям

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

В платёжной платформе ecommpay поддерживается возможность уведомлять пользователей о различных событиях, связанных с проведением платежей. Как правило, это уведомления о результатах выполнения операций, однако в зависимости от индивидуальных потребностей мерчанта могут использоваться уведомления и о других событиях, например о регистрации электронного кошелька в рамках проведения платежа или обновлении условий повторяемой оплаты.

Уведомления отправляются при соблюдении следующих условий:

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

К событиям, для которых настраивается отправка уведомлений, могут относиться как результаты выполнения операций в рамках проведения платежей (например, операций sale, auth, capture, cancel, payout и refund), так и результаты отдельных действий, выполненных в рамках операций (например, обновление условий повторяемой оплаты).

В уведомления о результатах проведения оплат можно добавлять информацию о товарных позициях с указанием списка приобретённых товаров и их сопутствующих характеристик (стоимости, количества товарных единиц, описания и суммы включённого в стоимость налога на добавленную стоимость (НДС).

При необходимости можно выполнять повторную отправку опредёленных уведомлений. Для этого следует обращаться к специалистам технической поддержки support@ecommpay.com.

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

Подключение

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

  • перечень операций и других событий, для которых настраивается отправка;
  • статусы операций, при которых выполняется отправка уведомлений (возможно как для итогового статуса success, так и для итогового статуса decline) ;
  • тема письма, в котором приходит уведомление (например, Receipt или «Уведомление о проведённой оплате»);
  • адрес электронной почты отправителя (домен ecommpay или домен, принадлежащий веб-сервису мерчанта);
  • возможность отправлять скрытые копии уведомлений на адрес электронной почты, предоставленный мерчантом.

Оформление уведомлений

Стандартное оформление

Стандартный шаблон может использоваться только при отправке уведомлений о результатах выполнения операций в рамках проведения разовых оплат (purchase) и выплат (payout), а также о результатах выполнения возвратов средств пользователям (refund).

Шаблон содержит следующие поля:

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

Индивидуальное оформление

Шаблон с индивидуальной вёрсткой может использоваться для отправки уведомлений как о результатах операций, так и о других событиях, связанных с проведением платежей. Индивидуальная вёрстка таких уведомлений реализуется на стороне ecommpay на основе макетов, предоставленных мерчантом. В шаблонах с индивидуальной вёрсткой могут использоваться те же элементы, что и в стандартных шаблонах, с возможностью изменения их порядка или могут быть добавлены другие элементы, например блоки с информацией о товарных позициях, о регистрации электронного кошелька, о превышении лимита общей суммы операций за сутки или об обновлении условий повторяемой оплаты. Также мерчантам следует учитывать, что в случае нестандартного текста уведомлений и для уведомлений на всех языках, кроме английского (применяемого по умолчанию), необходимо предоставить текст уведомления специалистам технической поддержки.

Далее представлены примеры уведомлений с индивидуальной вёрсткой:

  • Уведомление с информацией об окончании бесплатного пробного периода, которое не содержит поля, включаемые в стандартный шаблон (за исключением логотипа мерчанта).
  • Уведомление с информацией о товарных позициях, которое содержит все поля, включаемые в стандартный шаблон.
Рис. 2. Пример уведомления об окончании бесплатного пробного периода
Рис. 3. Пример уведомления с информацией о товарных позициях

Формат данных

Для отправки уведомления кроме обязательных параметров в запросе необходимо передать:

  • адрес электронной почты пользователя в параметре email объекта customer;
  • код языка пользователя в параметре language объекта customer в случае отправки уведомлений на любых языках, кроме английского.

Для включения в уведомление информации о товарных позициях необходимо дополнительно передать данные для формирования такого уведомления в объекте receipt_data. Объект receipt_data содержит массив positions, в котором можно перечислить до 300 товарных позиций. Для каждой товарной позиции указывается следующее:

  • amount — обязательный параметр для указания стоимости товара;
  • quantity — дополнительный параметр для указания количества товарных единиц;
  • tax — дополнительный параметр для указания ставки налога на добавленную стоимость (НДС);
  • tax_amount — дополнительный параметр для указания суммы налога на добавленную стоимость (НДС);
  • description — дополнительный параметр с описанием товара.

Как правило, в объекте receipt_data также указывается общая сумма НДС за всю покупку в параметре total_tax_amount. Если ставка НДС является одинаковой для всех позиций, то она указывается в параметре common_tax после общей суммы. Если ставка отличается для позиций в списке, то её значение указывается в параметре tax для каждой позиции отдельно.

Структура JSON-объекта приведена в модели receiptdata в спецификации Gate API.

В представленном далее примере запроса на проведение оплаты в объекте receipt_data содержится список из трёх товарных позиций в массиве positions. Так как ставки НДС для отдельных товаров в списке различаются, они указываются с помощью параметра tax для каждой товарной позиции. Соответственно, параметр common_tax с общей ставкой НДС в данном случае указывать не нужно.

Рис. 4. Пример запроса на оплату с информацией о товарных позициях
{
  "general":{
    "project_id":92724,
    "payment_id":"7654321-777",
    "signature":"5fgsjhgfgFxO9UaFLYGsBaisdffddgYuezUf+6VWlrsdfsH+LysUfdQM+w=="
  },
  "customer":{
    "ip_address":"128.112.0.16",
    "email":"relativeal@princeton.com"
  },
  "payment":{
    "amount":131971,
    "currency":"USD",
    "description":"Cosmoshop order"
  },
  "receipt_data":{
    "positions":[             //массив с перечислением товарных позиций
      {
        "quantity":1,
        "amount":5990,
        "tax":20,            //основная ставка НДС 
        "tax_amount":1198,
        "description":"How to communicate with aliens, a book"
      },
      {
        "quantity":3,
        "amount":2990,
        "tax":10,            //льготная ставка НДС
        "tax_amount":299,
        "description":"Astronaut space food, 1-week supply"
      },
      {
        "quantity":1,
        "amount":122990,
        "tax":20,            //основная ставка НДС
        "tax_amount":24598,
        "description":"Radio-controlled flying saucer, full size"
      }
    ],
    "total_tax_amount":26095           //общая сумма НДС за всю покупку
  },
  "card":{
    "pan":"4314220000000056",
    "year":2025,
    "month":11,
    "card_holder":"Albert Astone"
  }
}