- Введение
- Форма регистрации платежа
- Фрагмент формы регистрации платежа
- Форма для получения списка доступных пользователю способов оплаты у конкретного магазина
- Форма проверки статуса платежа
- Фрагмент формы регистрации платежа
- Терминальные зачисления без предварительного создания счёта
- Создание счёта по API
- Краткое описание процесса интеграции
- Проверка информации о платеже
- Проверка источника данных
- Приложение №1
- Приложение №2
- Использование тестового стенда
Для передачи информации между веб-сайтом продавца и системой Payin-payout используютcя HTML-формы:
- Форма регистрации платежа - генерируется веб-сайтом продавца для формирования запроса на проведение платежа в системе Payin-payout и передачи его через веб-браузер покупателя.
- Форма проверки статуса платежа - генерируется системой Payin-payout для передачи оповещения о платеже на веб-сайт продавца.
- Используемая кодировка - UTF-8.
Оповещение передается без использования веб-браузера покупателя.
Эта форма передает запрос с веб-сайта продавца в систему Payin-payout через веб-браузер покупателя.
Она должна иметь следующие атрибуты и поля:
Обозначение валюты платежа (подробнее см. Приложение №2)
Action — https://lk.payin-payout.net/api/shop
Method - POST
Fields - поля, передаваемые в форме, описаны в таблице ниже:
| Название поля | Обязательное | Тип поля | Описание |
|---|---|---|---|
| agentId | да | Целое число, от 1 до 999999 | Идентификатор агента (сайта) продавца, на который покупатель должен совершить платеж. |
| orderId | да | Строка до 50 символов | В этом поле продавец задает уникальный номер заказа (счета) в соответствии со своей системой учета. |
| agentName | да | Строка | Торговое название агента,выводится пользователю |
| userName | нет | Строка | Имя (и фамилия) покупателя. Будет показано в счете в качестве покупателя. |
| amount | да | Дробное число,больше нуля, дробная часть отделяется точкой, два знака после точки. | Сумма платежа, которую продавец желает получить от покупателя. |
| goods | да | Строка | Название товара (или счета), которые оплачивает клиент |
| currency | нет | Строка, 3 символа | Обозначение валюты платежа. По умолчанию - RUR. (подробнее см. Приложение №2) |
| да | Строка до 50 символов | Адрес электронной почты покупателя | |
| phone | да | 11 или более цифр, начиная с + | Телефон покупателя в международном формате. Например, для России: +79161234567 |
| preference | нет | Целое число | Способ оплаты, который будет выбран при оплате за товар. см. Приложение №1. Если не будет указан - то будет показана форма со всеми доступными способами оплаты |
| agentTime | да | Строка в формате «HH:mm:SS dd.MM.yyyy» | Дата создания платежа на стороне агента |
| limitTime | нет | Строка в формате «HH:mm:SS dd.MM.yyyy» | Дата, по истечении которой, заказ считается просроченным. По умолчанию 24 часа |
| successUrl | нет | Строка длиной до 1024 символов | Адрес на который будет перенаправлен пользователь в случае успешной оплаты |
| failUrl | нет | Строка длиной до 1024 символов | Адрес на который будет перенаправлен пользователь в случае отмены оплаты |
| shop_url | нет | Строка длиной до 1024 символов | Адрес на который будет перенаправлен пользователь в случае нажатии им на ссылку "Вернуться в магазин" |
| addInfo_N | нет | Строка длиной до 1024 символов | Все поля формы, имеющие в названии префикса "addInfo_N"(где N порядковый номер),обрабатываются системой Payin-payout автоматически и передаются на сайт продавца. (Кодировка UTF-8) |
| clientId | По умолчанию нет, для p2p платежа обязательно. | Строка длиной до 1024 символов | Уникальный идентификатор покупателя в системе учёта продавца |
| firstName | нет | Строка длиной до 1024 символов | Имя покупателя. |
| lastName | нет | Строка длиной до 1024 символов | Фамилия покупателя. |
| addressLine1 | нет | Строка длиной до 1024 символов | Поля, начинающиеся с адресной_строки, содержат наиболее подробную информацию об адресе, например номер улицы, название улицы и название здания. Они не предоставляют менее конкретные сведения, такие как город, штат/провинция или страна (эти сведения указаны в других полях). |
| addressLine2 | нет | Строка длиной до 1024 символов | Вторая строка адреса, если есть. |
| city | нет | Строка длиной до 1024 символов | Название города/населенного пункта. |
| state | нет | Строка длиной до 1024 символов | Название штата/провинции/региона. |
| country | нет | Строка | Двухбуквенный код страны по стандарту ISO 3166-1. |
| token | нет | Строка | Токен для соверешения рекуррентых платежей. Создание токена |
| sign | да | Строка | Контрольная подпись оповещения о создании платежа, которая используется для проверки однозначной идентификации отправителя. |
| purchase | нет | Массив | Данные о покупке. |
purchase' => [
'products' => [
[
'name' => 'Ананас',
'price' => 3,
'quantity' => 3,
'vat' => 0.18,
'unit' => 'kg',
'discount' => [
'type' => 'amount',
'value' => 2
]
],
[
'name' => 'Smartphone',
'price' => 6,
'quantity' => 2,
'vat' => 0.10,
'unit' => 'piece',
'discount' => [
'type' => 'amount',
'value' => 2
]
]
]
| Название поля | Обязательное | Тип поля | Описание |
|---|---|---|---|
| name | Обязательное | string | Наименование позиции |
| price | Обязательное | Дробное число, больше нуля, дробная часть отделяется | Цена за единицу |
| quantity | Обязательное | Дробное число, больше нуля, дробная часть отделяется | Количество товаров в позиции |
| vat | Обязательное | Целое число, больше нуля, дробная часть отделяется | Налог на позицию |
| unit | Обязательное | Строка | piece - штуки (по умолчанию), kg - килограммы, g - граммы, L - литры, ml - миллилитры |
| discount | Обязательное | Массив | Скидка на позицию |
| type | Обязательное | Строка | amount - абсолютное значение, percent - процентное значение (от 0 до 100) |
| value | Обязательное | Дробное число, больше нуля, дробная часть отделяется | Значение скидки |
-
Если в процессе регистрации платежа произошла ошибка и в запросе не указан failUrl то система выводит ошибку 250, иначе к строке переадресация failUrl добавляется query параметр error с описанием ошибки.
-
При правильном запросе в процессе регистрации платежа с использованием токена пользователя перенаправит на промежуточную страницу, на которой есть информация об успешной или неудачной оплате платежа.
-
Если в запросе регистрации платежа с использованием токена, и в случае успешной оплаты, был указан successUrl, то на промежуточной странице будет кнопка "Перейти в магазин", нажав на которую пользователя перенаправит по successUrl.
-
Если в запросе регистрации платежа с использованием токена, и в случае неудачной оплаты, был указан failUrl, то на промежуточной странице будет кнопка "Перейти в магазин", нажав на которую пользователя перенаправит по failUrl.
<form action="URL регистрации платежа" method="POST">
<input type="hidden" name="agentId" value="8686">
<input type="hidden" name="agentName" value="Superstore">
<input type="hidden" name="orderId" value="87876">
<input type="hidden" name="amount" value="166.70">
<input type="hidden" name="email" value="user@example.ru">
<input type="hidden" name="phone" value="79090000001">
<input type="hidden" name="agentTime" value="20:35:67 01.01.2010">
<input type="hidden" name="goods" value="Notebook">
<input type="hidden" name="currency" value="RUR">
<input type="hidden" name="preference" value="1">
<input type="hidden" name="successUrl" value="http://example.ru/success.html">
<input type="hidden" name="failUrl" value="http://example.ru/fail.html">
<input type="hidden" name="sign" value="f849a1c57cccb372ec4a3a2e04d2feba">
<input type="hidden" name="addInfo_1" value="addinf1">
<input type="hidden" name="purchase[products][0][name]" value="Ананас">
<input type="hidden" name="purchase[products][0][price]" value="50">
<input type="hidden" name="purchase[products][0][quantity]" value="1">
<input type="hidden" name="purchase[products][0][vat]" value="0.18">
<input type="hidden" name="purchase[products][0][unit]" value="kg">
<input type="hidden" name="purchase[products][0][discount][type]" value="amount">
<input type="hidden" name="purchase[products][0][discount][value]" value="0">
<input type="hidden" name="purchase[products][1][name]" value="Smartphone">
<input type="hidden" name="purchase[products][1][price]" value="50">
<input type="hidden" name="purchase[products][1][quantity]" value="1">
<input type="hidden" name="purchase[products][1][vat]" value="0.10">
<input type="hidden" name="purchase[products][1][unit]" value="piece">
<input type="hidden" name="purchase[products][1][discount][type]" value="amount">
<input type="hidden" name="purchase[products][1][discount][value]" value="0">
...
...
<input type="submit" value="Оплатить ">
</form>
<form action="URL регистрации платежа" method="POST">
<input type="hidden" name="agentId" value="8686">
<input type="hidden" name="agentName" value="Superstore">
<input type="hidden" name="orderId" value="87876">
<input type="hidden" name="amount" value="166.70">
<input type="hidden" name="email" value="user@example.ru">
<input type="hidden" name="phone" value="79090000001">
<input type="hidden" name="agentTime" value="20:35:67 01.01.2010">
<input type="hidden" name="token" value="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx">
<input type="hidden" name="goods" value="Notebook">
<input type="hidden" name="currency" value="RUR">
<input type="hidden" name="preference" value="1">
<input type="hidden" name="successUrl" value="http://example.ru/success.html">
<input type="hidden" name="failUrl" value="http://example.ru/fail.html">
<input type="hidden" name="sign" value="f849a1c57cccb372ec4a3a2e04d2feba">
<input type="hidden" name="addInfo_1" value="addinf1">
...
...
<input type="submit" value="Оплатить ">
</form>
Action - https://lk.payin-payout.net/shop/get-providers-pay
Method - POST
Fields - поля, передаваемые в форме, описаны в таблице ниже:
| Название поля | Обязательное | Тип поля | Описание |
|---|---|---|---|
| agentId | да | Целое число | Идентификатор агента (сайта) продавца, на который покупатель должен совершить платеж. |
| agentTime | да | Строка в формате «HH:mm:SS dd.MM.yyyy» | Время совершения запроса |
| sign | да | Строка | Контрольная подпись оповещения, которая используется для проверки однозначной идентификации отправителя. |
Контрольная подпись рассчитывается аналогично, как в прочих случаях, для расчёта подписи используются параметры agentId и agentTime.
<form action="https://lk.payin-payout.net/shop/get-providers-pay" method="POST">
<input type="hidden" name="agentId" value="9999">
<input type="hidden" name="agentTime" value="20:35:67 01.01.2019">
<input type="hidden" name="sign" value="sdf4y45yh54j56">
</form>
{
"id": 3,
"slug": "terminals_ru",
"title": "Терминалы РФ",
"name": "service_group.terminals_ru",
"hg_id": 5,
"icon": "/images/services/terminal.jpg",
"big_icon": null,
"preference": 2,
"descr": null,
"special": 0,
"non_interactive": true,
"disabled": false,
"enabled": true,
"enable": false
},
...
| Название поля | Тип поля | Описание |
|---|---|---|
| id | Целое число | Идентификатор сервиса |
| slug | Строка | Слаг |
| title | Строка | Наименовение |
| name | Строка | Языковая метка наименования |
| hg_id | Целое число | Идентификатор гипергруппы |
| icon | Строка | ссылка на иконку с группой |
| big_icon | Строка | Ссылка на большую иконку с группой |
| preference | Целое число | Внешний идентификатор для API входящих платежей |
| descr | Строка | Описание группы |
| special | Целое число | Спецгруппа, которые не выводятся нигде, А показываются только при особых условиях (у юзера тип договора - лидогенерация или массовые выплаты) |
| non_interactive | true/false | Если true, то сервис после выбора способа оплаты редиректит пользователя куда-либо, иначе обрботка платежа происходит непосредственно на сайте системы |
| disabled | true/false | Отключен? |
| enabled | true/false | Включен? |
| enable | true/false | Доступно или нет для магазина |
Эта форма оповещения о платеже, отправляемая продавцу при изменении статуса платежа. Она имеет следующие атрибуты и поля:
Action - URL информирования о статусе платежа (предоставляется клиентом Payin-payout)
Method - POST
Fields - поля, передаваемые в форме, описаны в таблице ниже:
| Название поля | Обязательное | Тип поля | Описание |
|---|---|---|---|
| agentId | да | Целое число, от 1 до 999999 | Идентификатор агента (сайта) продавца, на который покупатель должен совершить платеж. |
| orderId | да | Строка до 50 символов | В этом поле продавец задает уникальный номер заказа (счета) в соответствии со своей системой учета. |
| paymentId | да | Целое число большее нуля (тип данных bigint) | В этом поле передается номер покупки в системе EKO (Номер транзакции). |
| amount | да | Дробное число, больше нуля, дробная часть отделяется | Сумма платежа, которую продавец желает получить от покупателя. точкой, два знака после точки. |
| currency | нет | Строка, 3 символа | Обозначение валюты платежа (подробнее см. Приложение №2) |
| phone | да | 11 или более цифр | Телефон покупателя в международном формате. Например, для России: 79161234567 |
| preference | да | Целое число | Способ оплаты, который будет выбран при оплате за товар. см. Приложение №1. Если в системе не задан, то вернет значение 0 |
| paymentStatus | да | Целое число | Статус платежа может иметь следующие значения : 1 — Прошел успешно 2 — Фатальная ошибка, платеж не прошел 3 — Платеж был частично оплачен |
| paymentDate | да | Строка в формате «HH:mm:SS dd.MM.YYYY» | Дата и время реального прохождения платежа в системе Payin-payout |
| goods | Да | Строка | Описание предоставляемой услуги или товара |
| agentName | Да | Строка | Название агента, понятное плательщику, например брэнд или товарный знак под которым работает агент |
| sign | да | Строка | Контрольная подпись оповещения о выполнении платежа, которая используется для проверки целостности полученной информации и однозначной идентификации отправителя. |
| comment | нет | Строка длиной до 1024 символов | Комментарий к платежу (Например, при оплате по смс — это текст отправленного сообщения), текст закодирован алгоритмом url encoding. |
| addInfo_N | нет | Строка длиной до 1024 символов | Все поля, переданные с веб-сайта продавца в "Форме регистрации платежа" |
ВАЖНО — На странице https://lk.payin-payout.net/app/#/report/get_operations_payin используя фильтр "Статус уведомления" можно посмотреть по каким оплаченным платежам магазин ответил успешно, что запрос уведомления об оплате получен. Так же можно отфильтровать список по платежам, по которым ответ от магазина не получен.
<form action="URL информирования о статусе платежа" method="POST">
<input type="hidden" name="agentId" value="8686">
<input type="hidden" name="paymentId" value="64877777777903">
<input type="hidden" name="orderId" value="87876">
<input type="hidden" name="amount" value="166.70">
<input type="hidden" name="phone" value="79090000001">
<input type="hidden" name="currency" value="RUR">
<input type="hidden" name="preference" value="1">
<input type="hidden" name="goods" value="Рога, 10 кг">
<input type="hidden" name="agentName" value="Рога и Копыта (TM)">
<input type="hidden" name="paymentStatus" value="1">
<input type="hidden" name="paymentDate" value="13:12:03 10.01.2010">
<input type="hidden" name="sign" value="f849a1c57c66b372ec4a3a2e04d2feba">
<input type="hidden" name="addInfo_1" value="addinfoxxxxxxxx">
...
...
</form>
При выполнении платежа система Payin-payout высылает оповещение о платеже через "Форму проверки статуса платежа" на URL информирования о статусе платежа, указанный продавцом. Сообщение считается доставленным, если страница обрабатывающая уведомление, вернет
<?xml version="1.0" encoding="UTF-8"?><response><result>0</result></response>и код HTTP ответа 200, иначе оповещение о выполненном платеже будет повторяться. Коды редиректов (30х) считаются недействительными.
Мы рекомендуем вам проверить данные, полученные через "Форму оповещения о платеже":
- Проверить, действительно ли данные переданы от системы Payin-payout
- Проверить, не исказились ли данные в процессе передачи
- Проверить сумму платежа. (!) Сумма платежа означает на сколько денег уже товар был оплачен и в случае частичной оплаты будет идти по нарастающей. Например пользователь создал счет на 200 руб. При пополнении сначала на 30, потом на 100 и затем на 70 будет выслано три уведомления на сумму 30, 130 и 200 рублей соответственно. Необходимо предусмотреть корректную обработку данного типа оповещений.
- Проверить идентификатор агента (сайта) продавца
При формировании счета в форме регистрации платежа, продавец передает системе Payin-payout реквизиты платежа и контрольную подпись, позволяющую однозначно идентифицировать
агента.
При формировании контрольной подписи, продавец "склеивает" значения полей разделяя их символом “#”, в одну строку в следующем порядке:
- Идентификатор агента (продавца) (agentId);
- Уникальный номер заказа (счета) (orderId)
- Дата создания платежа (agentTime)
- Сумма платежа (amount)
- Телефон покупателя (phone)
- Токен, если используются рекуррентные платежи, иначе не включать этот параметр в подпись. Создание токена
Пример :
MD5(8686#87876#13:12:03 10.01.2010#166.70#+79090000001#MD5(secret))
Пример с токеном :
MD5(8686#87876#13:12:03 10.01.2010#166.70#+79090000001#хххххххххххххххххххххххххххххххх#MD5(secret))
secret — секретная фраза агента, получить её можно из личного кабинета агента. MD5 формируется последовательность из 32-х шестнадцатеричных цифр в соответствии с широко распространенным алгоритмом Message Digest 5 (MD5).
Следует внимательно проверить данные которые используются для формирования подписи и для отправки запроса. В случае если эти данные будут отличаться сгенерируются не совпадающие подписи и проверка безопасности не будет пройдена.
Высылая оповещение о проведении платежа, система Payin-payout передает реквизиты платежа и контрольную подпись, позволяющую проверять неизменность передаваемых данных.
Контрольная подпись данных о платеже позволяет продавцу проверять источник данных, переданных на продавцу.
При формировании контрольной подписи система Payin-payout "склеивает" значения полей разделяя их “#”, передаваемых "Форма проверки статуса платежа", в одну строку в следующем порядке:
- Идентификатор агента (продавца) (agentId);
- Уникальный номер заказа (счета) (orderId)
- Номер покупки в системе EKO (paymentId)
- Сумма платежа (amount)
- Телефон покупателя (phone)
- Статус платежа (paymentStatus)
- Дата и время реального прохождения платежа (paymentDate)
- Секретный ключ (пароль) агента
Пример :
MD5(8686#87876#12345678#166.70#+79090000001#1#13:12:03 10.01.2010#MD5(secret))
MD5 формируется последовательность из 32-х шестнадцатеричных цифр в соответствии с широко распространенным алгоритмом Message Digest 5 (MD5).
| Код типа платежа | Описание | Примечания |
|---|---|---|
| 0 | Сервис не указан | в случае уведомления об ошибке |
| 1 | Со счета Payin-payout | Нужно иметь учетную запись в системе |
| 2 | Терминалы "QIWI" | Отображаются инструкции по оплате |
| 5 | Банковский перевод по РФ | Показывает форму счета |
| 6 | Яндекс.деньги | В настоящий момент может быть недоступно |
| 7 | Банковский перевод SWIFT | Показывает форму счета |
| 8 | Киви-кошелек | В настоящий момент недоступно |
| 13 | RBK Money | В настоящий момент недоступно |
| 14 | Единая касса (WalletOne) | |
| 15 | Paypal | |
| 124 | Терминалы Элекснет | Отображаются инструкции по оплате |
| 125 | Пластиковые карты | Могут быть недоступны. Альтернативно можно использовать 22 |
| 126 | Альфа-клик | В параметре addInfo_1 магазин может передавать идентификатор плательщика в Alfa-Click. Если не будет указан, то на форме счета пользователю будет предложено его ввести |
| 127 | SMS Оплата (МТС, Мегафон, Теле 2) | Отображаются инструкции по оплате. |
| 128 | SMS Оплата (Билайн) | Отображаются инструкции по оплате. В случае, если оператор не Билайн будет ошибка. Только по РФ |
| 129 | Веб мани | |
| 130 | Салоны связи Евросеть и салоны МТС | Отображаются инструкции по оплате |
| 133 | Рекуррентные платежи | Используется при оплате рекуррентным способом |
| 136 | СБП |
| Обозначение валюты | Название |
|---|---|
| RUR | Российский рубль |
| EUR | Евро |
| USD | Доллар США |
| GBP | Фунт стерлингов |
| UAH | Украинская гривна |
| KZT | Тенге |
| MDL | Молдавский лей |
| BYN | Белорусский рубль |
| TRY | Турецкая лира |
| AED | Дирхам ОАЭ |