Skip to content

payin-payout/payin-api

BranchesTags

Repository files navigation

Описание интерфейса сервиса приема платежей через систему Payin-payout

Введение

Для передачи информации между веб-сайтом продавца и системой Payin-payout используютcя HTML-формы:

  1. Форма регистрации платежа - генерируется веб-сайтом продавца для формирования запроса на проведение платежа в системе Payin-payout и передачи его через веб-браузер покупателя.
  2. Форма проверки статуса платежа - генерируется системой Payin-payout для передачи оповещения о платеже на веб-сайт продавца.
  3. Используемая кодировка - 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)
email да Строка до 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

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
                ]
            ]
        ]

Описание полей массива purchase

Название поля Обязательное Тип поля Описание
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х) считаются недействительными. Мы рекомендуем вам проверить данные, полученные через "Форму оповещения о платеже":

  1. Проверить, действительно ли данные переданы от системы Payin-payout
  2. Проверить, не исказились ли данные в процессе передачи
  3. Проверить сумму платежа. (!) Сумма платежа означает на сколько денег уже товар был оплачен и в случае частичной оплаты будет идти по нарастающей. Например пользователь создал счет на 200 руб. При пополнении сначала на 30, потом на 100 и затем на 70 будет выслано три уведомления на сумму 30, 130 и 200 рублей соответственно. Необходимо предусмотреть корректную обработку данного типа оповещений.
  4. Проверить идентификатор агента (сайта) продавца

Проверка источника данных

При формировании счета

При формировании счета в форме регистрации платежа, продавец передает системе Payin-payout реквизиты платежа и контрольную подпись, позволяющую однозначно идентифицировать агента.
При формировании контрольной подписи, продавец "склеивает" значения полей разделяя их символом “#”, в одну строку в следующем порядке:

  1. Идентификатор агента (продавца) (agentId);
  2. Уникальный номер заказа (счета) (orderId)
  3. Дата создания платежа (agentTime)
  4. Сумма платежа (amount)
  5. Телефон покупателя (phone)
  6. Токен, если используются рекуррентные платежи, иначе не включать этот параметр в подпись. Создание токена

Пример :

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).

Следует внимательно проверить данные которые используются для формирования подписи и для отправки запроса. В случае если эти данные будут отличаться сгенерируются не совпадающие подписи и проверка безопасности не будет пройдена.

secret

При отправке оповещения о статусе платежа

Высылая оповещение о проведении платежа, система Payin-payout передает реквизиты платежа и контрольную подпись, позволяющую проверять неизменность передаваемых данных.
Контрольная подпись данных о платеже позволяет продавцу проверять источник данных, переданных на продавцу.
При формировании контрольной подписи система Payin-payout "склеивает" значения полей разделяя их “#”, передаваемых "Форма проверки статуса платежа", в одну строку в следующем порядке:

  1. Идентификатор агента (продавца) (agentId);
  2. Уникальный номер заказа (счета) (orderId)
  3. Номер покупки в системе EKO (paymentId)
  4. Сумма платежа (amount)
  5. Телефон покупателя (phone)
  6. Статус платежа (paymentStatus)
  7. Дата и время реального прохождения платежа (paymentDate)
  8. Секретный ключ (пароль) агента

Пример :

MD5(8686#87876#12345678#166.70#+79090000001#1#13:12:03 10.01.2010#MD5(secret))

MD5 формируется последовательность из 32-х шестнадцатеричных цифр в соответствии с широко распространенным алгоритмом Message Digest 5 (MD5).

Приложение №1

Коды типов платежей

Код типа платежа Описание Примечания
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 СБП

Приложение №2

Обозначения доступных валют для платежей

Обозначение валюты Название
RUR Российский рубль
EUR Евро
USD Доллар США
GBP Фунт стерлингов
UAH Украинская гривна
KZT Тенге
MDL Молдавский лей
BYN Белорусский рубль
TRY Турецкая лира
AED Дирхам ОАЭ

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

4 forks
Report repository

Releases

No releases published

Packages

No packages published

Contributors 6