API для подключения. Схема Payform - ввод данных на стороне шлюза
URL вызова функций API - https://cpg. money. mail. ru/api/
Про аутентификацию вызовов см. главу Аутентификация вызовов
Параметры, перечисленные после параметра signature, не участвуют в формировании подписи.
Подчеркнутые параметры являются обязательными.
Таким образом, параметры, не являющиеся обязательными, участвуют в формировании подписи только в случае, если они передаются.
Инициализация платежа c произвольной карты
URL запроса: https://cpg. money. mail. ru/api/init/freepay
Параметры POST-запроса:
Параметр | Описание |
merch_id | идентификатор мерчанта, выданный при подключении мерчанта к платёжному шлюзу |
vterm_id | идентификатор виртуального терминала мерчанта, через который проводится платёж |
user_login | логин пользователя, по которому идентифицируются привязки пользователя в платёжном шлюзе |
user_ip | IP-адрес пользователя |
order_id | уникальный номер заказа в системе мерчанта |
order_amount | сумма заказа |
order_message | наименование заказа |
extra | дополнительные данные заказа в формате JSON. Будут переданы в магазин в уведомлении |
use_cvv | флаг, говорящий о том, что платеж должен проводиться с cvv. Допустимые значения (независимо от регистра): - yes - означает, что необходимо проводить платеж с запросом cvv - no - означает, что платеж необходимо проводить без cvv В случае, если придет другое значение (но не более трех символов), то платеж будет проводиться без учета данного флага При этом применение флага определяется тем, разрешена ли такая возможность в конкретном терминале. Если возможность разрешена и значение флага валидно, то оно перекрывает настройки терминала по проведению платежей с/без cvv и сохраненные настройки карты. Значение флага не будет учитываться в случае, если при проведении платежа передано значение cvv - в этом случае, платеж будет проводиться с cvv вне зависимости от всех флагов и настроек. |
use_3ds | флаг, говорящий о том, что платеж должен проводиться с 3ds. Допустимые значения (независимо от регистра): - yes - означает, что необходимо проводить платеж с запросом 3ds - no - означает, что платеж необходимо проводить без 3ds В случае, если придет другое значение (но не более трех символов), то платеж будет проводиться без учета данного флага. При этом применение флага определяется тем, разрешена ли такая возможность в конкретном терминале. Если возможность разрешена и значение флага валидно, то оно перекрывает настройки терминала по проведению платежей с/без 3ds и сохраненные настройки карты. |
skin | идентификатор набора шаблонов |
keep_uniq | проверять уникальность заказа (действует в сочетании с параметром order_id). Может принимать следующие значения: merchant - проверка уникальности в пределах мерчанта terminal - проверка уникальности в пределах терминала (vterm_id) |
language | язык (по умолчанию - русский) |
backurl | URL для возврата в магазин |
currency | трехзначный цифровой код валюты по ISO-4217 список кодов см. http://www. currency-iso. org/en/home/tables/table-a1.html по умолчанию - 643 (российский рубль) |
signature | цифровая подпись параметров запроса |
utf8 | utf8=1 указывается, если параметры переданы в utf-8 |
Формат поля extra:
{
"social_auth": [
{
"login": "217553",
"vterm_id": "VKGolosa"
}
],
"social_auth_vterm_id": "VKGolosa",
"social_auth_login": "217553",
"user_info": {
"reg_date":"31.03.2015",
"reg_time":"16:15:34",
"name":"",
"reg_ip":"127.0.0.1",
"avatar":"1",
"payments":"1",
"reg_agent":"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.101 Safari/537.36",
"prev_agent":"Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/41.0.2272.101 Safari/537.36",
"phone":"79100000000",
"birth_date":"10.01.1980",
"prev_ip":"127.0.0.1"
},
"subsribe_title":"Подписаться на..."
}
Значения полей в extra
Поле | Описание |
social_auth | массив соц. привязок пользователя |
social_auth_vterm_id | терминал соц. привязки пользователя (используется, если не задан массив social_auth), на запросе init/freepay не используется вообще, но будет передан далее на order/pay |
social_auth_login | идентификатор пользователя в соц. сети (используется, если не задан массив social_auth), на запросе init/freepay не используется вообще, но будет передан далее на order/pay |
user_info | данные пользователя, на запросе init/freepay не используется вообще, но будет передан далее на order/pay |
subsribe_title | текст галочки подписки для вывода на форму |
Описание ответа
В случае успеха происходит редирект на форму ввода данных на стороне платёжного шлюза - https://cpg. money. mail. ru/api/page/freepay/
В случае ошибки происходит редирект на страницу с ошибкой - https://cpg. money. mail. ru/api/page/result? request=init_freepay&Success=False, либо на страницу, указанную в параметре backurl (если он был передан) с дописыванием GET-параметров request=init_freepay и Success=False. В случае ошибки ERR_AUTHENTICATION_FAILED редирект будет происходить всегда на URL процессингового центра. Дополнительно в качестве GET-параметров к URL редиректа дописываются параметры code и desc.
Последовательность действий со стороны мерчанта по инициализации платежа c произвольной карты
Последовательность действий по взаимодействию пользователя, мерчанта и карточного шлюза Деньги Mail. Ru по инициализации платежа с произвольной банковской карты указана ниже.
Сервер мерчанта по запросу со стороны пользователя производит отображение в браузере пользователя формы ввода данных оплаты. При этом у пользователя запрашиваются данные, необходимые серверу мерчанта для формирования запроса /api/init/freepay к интерфейсу платежного шлюза Деньги Mail. Ru. Далее, после завершения ввода, данные формы отправляются из браузера пользователя на сервер мерчанта, где производится их проверка и формирование подписи (поле signature) для запроса /api/init/freepay. Данные формы и значение подписи возвращаются в браузер пользователя, откуда затем производится выполнение запроса /api/init/freepay к интерфейсу платежного шлюза, при успешном завершении которого пользователю отображается форма ввода данных банковской карты на стороне шлюза.
Аутентификация вызовов
Аутентификация запросов на стороне платежного шлюза производится путём проверки параметра signature, который содержит подпись нужных параметров запроса.
Для каждого мерчанта/терминала при подключении настраивается хэширующая функции (по умолчанию sha1) и секретный ключ для формирования подписи.
Подпись представляет собой результат хэширующей функции, которая применяется к тексту, сформированному как последовательность значений параметров запроса, участвующих в подписи (кроме самого параметра signature), отсортированных в алфавитном порядке по имени параметра, с добавлением ключа мерчанта/терминала, выданного при подключении.
Для каждого запроса список параметров, участвующих в подписи, определяется отдельно (см. описание запросов api).
Список поддерживаемых алгоритмов хэширования можно уточнить при подключении к шлюзу.
Пример формирования подписи запроса
Например, терминал при запросе передает нам следующие параметры:
Параметр | Значение |
order_amount | 526.04 |
order_id | 123-ABC |
order_message | Тестовая покупка |
user_ip | 127.0.0.1 |
user_login | *****@***com |
vterm_id | MailRuPay3DS |
Пусть секретный ключ мерчанта/терминала будет следующим: Secret_key, а хэширующая функция - sha1
Строка подписи будет выглядеть следующим образом: 526.04123-ABCТестовая покупка*****@***comMailRuPay3DS
Далее строка для подписи конкатенируется с секретным ключом, полученным при регистрации мерчанта/терминала в платёжном шлюзе и хэшируется алгоритмом, настроенным для мерчанта/терминала.
В итоге получаем подпись таким образом:
signature = sha1( '526.04123-ABCТестовая покупка*****@***comMailRuPay3DSSecret_key' );
На выходе в этом примере мы должны получить такое значение: fcdc8a2bd7f7459a9e5e774769d0fb8afcd0da41
Использование привязок соц. сетей
Для возможности оплаты с использованием привязки социальной сети через платежную форму ПЦ (запрос на https://cpg. money. mail. ru/api/init/freepay) нужно подгрузить на форму список привязок этой соц. сети. Для этого после авторизации пользователя в нужной соц. сети формируется запрос на получение формы, в котором нужно передать параметр extra следующего формата:
"extra": {
"social_auth":[
{
"login":"6572732",
"vterm_id":"VKGolosa"
},
]
}
Т. е. в extra передаем параметр social_auth, который является массивом. В элементах массива содержатся параметры:
login - логин пользователя в указанном терминале (id из Вконтакте);
vterm_id - идентификатор терминала, привязки которого необходимо получить (использовать VKGolosa).
Количество передаваемых терминалов не ограничено.
Если параметр social_auth в extra задан, то после перехода на /api/init/freepay, в списке привязок будут все доступные указанным терминалам привязки с учетом области видимости терминалов и их настроек.
Если в указанных терминалах есть карты, которые зарегистрированы и в текущем терминале (в том, с которого производится оплата), то дубликаты исключаются, предпочтение отдается "родным" привязкам терминала. Если передано несколько терминалов, то среди них дубликаты также исключаются, отдавая предпочтение привязкам подтвержденным по 3ds в первую очередь, затем по hold, затем по cvv, далее просто по порядку.
Удалить привязку другого терминала нельзя.
При оплате с привязки другого терминала, процессинговый центр получает из нее данные карты для дальнейшей оплаты по этой карте. В заказе будет сохранено, с какой внешней привязки произведена оплата. Однако при поиске в платежах по этой внешней привязке этот платеж найден не будет.
