Протокол уведомлений Pokupo - Платежное АПИ, API
Если вы уже разрабатывали прием платежей через WebMoney или Z-Payment, то для подключения вашего магазина к системе Pokupo вам достаточно настроить его параметры и внести незначительные поправки в HTML коды.
Параметры магазина Pokupo
Перейдите в меню магазины и выберите настройки для нужного магазина. Список параметров, которые необходимы вам для настройки приема платежей:
Название параметра | Формат | Описание |
---|---|---|
Идентификатор магазина для CMS | Целое число | Уникальный идентификатор магазина |
Статус | - | Режим работы (включен/выключен/заблокирован). Магазин для приема платежей должен быть включен |
Секция `Уведомления` | ||
URL для уведомлений | 255 символов | URL (на веб-сайте магазина), на который сервис Pokupo посылает HTTP POST или GET-оповещение о совершении платежа с его детальными реквизитами. URL должен начинаться с префикса "http://", "https://" и должен быть доступен для проверки на существование. При использовании префикса "http://" или "https://" сервис посылает оповещение по портам 80 и 443 соответственно. Если параметр `Подтверждать заказ запросом к сайту` установлен `Да`, то вызов URL уведомления выполняется два раза. Первый раз непосредственно перед выполнением платежа (для проверки работоспособности веб-сайт продавца), второй раз сразу после успешного выполнения платежа (для передачи параметров платежа). Если флаг не установлен – предварительное оповещение не проводится. |
Метод | - | Метод (POST, GET), который будет использоваться для оповещения сайта магазина. |
Подтверждать заказ запросом к сайту | - | Флаг, сообщающий сервису Pokupo о том, что перед выполнением заказа нужно выслать предворительное оповещения для проверки работоспособности сайта. Если флаг передачи параметров установлен, веб-сайт продавца должен вернуть строку "YES" в ответе для того, чтобы сервис Pokupo смог продолжить выполнение платежа. Если веб-сайт продавца вернет что-либо другое - платеж выполнен не будет а ответ будет показан покупателю в сообщении об ошибке. |
Email уведомления | - | E-mail продавца для высылки уведомлений об успешной оплате в магазине. |
SMS уведомления | - | СМС продавца для высылки уведомлений об успешной оплате в магазине. |
Пароль уведомления | 128 символов | Строка символов, добавляемая к реквизитам платежа, высылаемым продавцу вместе с оповещением. Эта строка используется для повышения надежности идентификации высылаемого оповещения. Содержание строки известно только сервису Pokupo и продавцу! |
Отправлять пароль уведомления | - | Флаг, сообщающий сервису Pokupo о том, что Пароль уведомления должен быть добавлен к высылаемому на веб-сайт продавца оповещению о платежах в открытом виде. В противном случае будет высылаться только хэш с солью из пароля уведомлений. Пароль уведомления высылается только в том случае, если канал обеспечивает безопасную передачу Url уведомлений (используется протокол SSL, то есть Url уведомлений имеет префикс "https://"). Если Url уведомлений не использует SSL, то пароль уведомлений высылаться не будет, даже если флаг установлен. |
Форма запроса платежа
Для передачи информации между веб-сайтом продавца и сервисом Pokupo может использоваться форма или ссылка, с помощью которых на адрес мерчанта способом GET или POST передаются параметры.
Адрес мерчанта:
- https://seller.pokupo.ru/api/ru/payment/merchant - русскоязычный мерчант
- https://seller.pokupo.ru/api/en/payment/merchant - англоязычный мерчант
Поля, одидаемые на мерчант от продавца описаны в таблице ниже:
Название | Название передаваемого поля | Обязательный? | Описание |
---|---|---|---|
Идентификатор магазина для CMS | LMI_PAYEE_PURSE | Да | Идентификатор магазина для CMS в системе Pokupo из настроек магазина, целое число |
Сумма платежа | LMI_PAYMENT_AMOUNT | Да | Сумма платежа, которую продавец желает получить от покупателя. Сумма должна быть больше нуля, дробная часть отделяется точкой. |
Назначение платежа | LMI_PAYMENT_DESC | Да | Описание товара или услуги. Формируется продавцом. Максимальная длина - 255 символов. |
Внутренний номер счета магазина | LMI_PAYMENT_NO | Да | В этом поле продавец задает номер покупки в соответствии со своей системой учета. Желательно использовать уникальный номер для каждого платежа, что позволит быстро получить относящуюся к нему информацию. |
Email клиента | CLIENT_MAIL | нет | E-mail покупателя, служит для уведомления покупателя об оплате и возможных ошибках. |
Url перенаправления при успешной оплате | LMI_SUCCESS_URL | нет | Url, на который перенаправляется пользователь после успешной оплаты |
Url перенаправления при неуспешной оплате | LMI_FAIL_URL | нет | Url, на который перенаправляется пользователь после неуспешной оплаты |
Url перенаправления в других случаях | LMI_BACK_URL | нет | Url, на который перенаправляется пользователь во всех других случаях (отказался от оплаты, или зачисление по выбранному покупателем способу не является мгновенным) |
Дополнительные параметры продавца | Определяются магазином | нет | Другие поля формы, обрабатываются сервисом Pokupo автоматически и передаются на веб-сайт магазина после выполнения платежа. |
Пример формы для оплаты
Параметры, отправляемые при предварительном запросе
Следующие данные передаются на URL уведомлений непосредственно перед выполнением платежа если установлен соответствующий флаг в настройках магазина:
Название | Название передаваемого поля | Описание |
---|---|---|
Индикатор предварительного запроса | LMI_PREREQUEST | Для предварительного запроса равен 1 (единице) |
Идентификатор магазина для CMS | LMI_PAYEE_PURSE | Идентификатор магазина для CMS в системе Pokupo из настроек магазина, целое число |
Сумма платежа в валюте магазина | LMI_PAYMENT_AMOUNT | Сумма счета, которую продавец выставил для оплаты покупателю. |
Счет покупателя | LMI_PAYER_WM | Email покупателя |
Внутренний номер счета магазина | LMI_PAYMENT_NO | В этом поле передается номер покупки в соответствии с системой учета продавца, полученный сервисом с веб-сайта магазина. |
Флаг тестового режима | LMI_MODE |
Всегда равен 0 (нулю) |
Код платежной системы | PKP_METHOD_PAYMENT |
Внутренний учетный код метода оплаты в системе Pokupo |
Комиссия платежной системы | PKP_COST_PAYMENT |
Комиссия, которая взимается платежным провайдером с покупателя |
Стоимость доставки | PKP_COST_SHIPPING |
Стоимость доставки заказа, которую оплачивает покупатель |
Внутренний номер счета в системе Pokupo | PKP_ID_ORDER |
Номер счета в системе Pokupo, выставленный покупателю от магазина в процессе обработки запроса на выполнение платежа сервисом Pokupo. Является уникальным в системе Pokupo. |
Список товаров в заказе | PKP_LIST_ITEM_ORDER |
Информация о товарах в заказе в формате JSON [{"numberGoods":"Артикул товара;","nameGoods":"Наименование товара","countGoods":количество,"priceGoods":цена},{...}] |
Дополнительные параметры продавца | Определяются магазином | Все поля, переданные с веб-сайта магазина в "Форме запроса платежа" |
Параметры, отправляемые при оповещении о платеже на URL уведомлений магазина:
Название | Название передаваемого поля | Описание |
---|---|---|
Идентификатор магазина для CMS | LMI_PAYEE_PURSE | Идентификатор магазина для CMS в системе Pokupo из настроек магазина, целое число |
Сумма счета в валюте магазина | LMI_PAYMENT_AMOUNT | Сумма счета, который был выставлен покупателю в валюте магазина. |
Счет покупателя | LMI_PAYER_PURSE | Email покупателя |
Счет покупателя | LMI_PAYER_WM | Email покупателя |
Внутренний номер счета магазина | LMI_PAYMENT_NO | В этом поле передается номер покупки в соответствии с системой учета магазина, полученный сервисом с веб-сайта магазина. |
Внутренний номер счета в системе Pokupo | LMI_SYS_TRANS_NO | Номер счета в системе Pokupo, выставленный покупателю от магазина в процессе обработки запроса на выполнение платежа сервисом Pokupo. Является уникальным в системе Pokupo. |
Внутренний номер платежа в системе | LMI_SYS_INVS_NO | Номер платежа в выбранной пользователем платежной системе. |
Флаг тестового режима | LMI_MODE |
Всегда равен 0 (нулю) |
Дата и время выполнения платежа | LMI_SYS_TRANS_DATE | Дата и время реального прохождения платежа в системе Pokupo в формате "YYYYMMDD HH:MM:SS". |
Контрольная подпись | LMI_HASH | Контрольная подпись оповещения о выполнении платежа, которая используется для проверки целостности полученной информации и однозначной идентификации отправителя. Алгоритм формирования описан ниже в разделе "Контрольная подпись данных о платеже". |
Пароль уведомлений магазина | LMI_SECRET_KEY | Значение Пароль уведомлений магазина, известное только продавцу и сервису Pokupo. Это поле будет пустым, если параметр "URL уведомлений" не обеспечивает секретность или не установлен флаг "Отправлять ключ магазина". |
Код платежной системы | PKP_METHOD_PAYMENT |
Внутренний учетный код метода оплаты в системе Pokupo |
Комиссия платежной системы | PKP_COST_PAYMENT |
Комиссия, которая взимается платежным провайдером с покупателя |
Стоимость доставки | PKP_COST_SHIPPING |
Стоимость доставки заказа, которую оплачивает покупатель |
Внутренний номер счета в системе Pokupo | PKP_ID_ORDER |
Номер счета в системе Pokupo, выставленный покупателю от магазина в процессе обработки запроса на выполнение платежа сервисом Pokupo. Является уникальным в системе Pokupo. |
Список товаров в заказе | PKP_LIST_ITEM_ORDER |
Информация о товарах в заказе в формате JSON [{"numberGoods":"Артикул товара;","nameGoods":"Наименование товара","countGoods":количество,"priceGoods":цена},{...}] |
Дополнительные параметры продавца | Определяются магазином | Все поля, переданные с веб-сайта магазина в "Форме запроса платежа" |
В ответ на оповещение о платеже ваш сайт должен вернуть HTTP заголовок с кодом "200 OK" и строку YES, иначе оповещение о выполненном платеже будет повторяться в пределах 24 часов.
Внимание!
Название передаваемого поля>Сайт магазина обязательно должен предусмотреть проверку информации, присланной в "Форме оповещения о платеже" в соответствии с рекомендациями раздела "Алгоритм формирования и проверки контрольной подписи".
Параметры, передаваемые на LMI_SUCCESS_URL
Данные параметры передаются на указанный адрес в случае успешной оплаты счета
Название | Название передаваемого поля | Описание |
Внутренний номер счета магазина | LMI_PAYMENT_NO | В этом поле передается номер покупки в соответствии с системой учета магазина, полученный сервисом с веб-сайта магазина. |
Внутренний номер счета в системе Pokupo | LMI_SYS_TRANS_NO | Номер счета в системе Pokupo, выставленный покупателю от магазина в процессе обработки запроса на выполнение платежа сервисом Pokupo. Является уникальным в системе Pokupo. |
Внутренний номер платежа в ПС | LMI_SYS_INVS_NO | Номер платежа в выбранной пользователем платежной системе. |
Дата и время выполнения платежа | LMI_SYS_TRANS_DATE | Дата и время выставления счета в системе Pokupo в формате "YYYYMMDD HH:MM:SS". |
Дополнительные параметры продавца | Определяются магазином | Все поля, переданные с веб-сайта магазина в "Форме запроса платежа" |
Параметры, передаваемые на LMI_FAIL_URL
Данные параметры передаются на указанный адрес в случае неуспешной оплаты счета
Название | Название передаваемого поля | Описание |
Внутренний номер счета магазина | LMI_PAYMENT_NO | В этом поле передается номер покупки в соответствии с системой учета магазина, полученный сервисом с веб-сайта магазина. |
Внутренний номер счета в системе Pokupo | LMI_SYS_TRANS_NO | Номер счета в системе Pokupo, выставленный покупателю от магазина в процессе обработки запроса на выполнение платежа сервисом Pokupo Является уникальным в системе Pokupo. |
Внутренний номер платежа в ПС | LMI_SYS_INVS_NO | Номер платежа в выбранной пользователем платежной системе. |
Дата и время выполнения платежа | LMI_SYS_TRANS_DATE | Дата и время выставления счета в системе Pokupo в формате "YYYYMMDD HH:MM:SS". |
Дополнительные параметры продавца | Определяются магазином | Все поля, переданные с веб-сайта магазина в "Форме запроса платежа" |
ПРОВЕРКА ИНФОРМАЦИИ
При выполнении платежа Pokupo высылает оповещение о платеже на URL уведомлений, указанный продавцом в настройках магазина. Мы рекомендуем вам проверить полученные уведомления:
- Проверить, действительно ли данные переданы от сервиса Pokupo (Проверка источника данных)
- Проверить, не исказились ли данные в процессе передачи (с помощью проверки хэша)
- Проверить сумму платежа
- Проверить ID магазина
Если URL уведомлений обеспечивает секретность и не переопределяется и если продавец не желает проверять контрольную подпись, он должен установить флаг "Отправлять пароль уведомления". В этом случае Pokupo будет высылать Пароль уведомления на веб-сервер продавца в поле "LMI_SECRET_KEY" при отправке уведомлений об оплате. Продавец должен проверять его каждый раз, когда получает оповещение о выполнении платежа.
Проверка подписи является более трудоемким методом, но он не требует передачи Merchant Key через интернет и является более безопасной.
Контрольная подпись данных о платеже
Контрольная подпись данных о платеже позволяет продавцу проверять как источник данных, так и целостность данных, переданных на URL уведомлений.
При формировании контрольной подписи сервис Pokupo "склеивает" значения полей, передаваемых "Формой оповещения о платеже", в одну строку в следующем порядке:
- ID магазинадля CMS (LMI_PAYEE_PURSE);
- Сумма платежа (LMI_PAYMENT_AMOUNT);
- Внутренний номер покупки продавца (LMI_PAYMENT_NO);
- Флаг тестового режима (LMI_MODE);
- Внутренний номер счета ввыбранной платежной системе (LMI_SYS_INVS_NO);
- Внутренний номер платежа в системе Pokupo (LMI_SYS_TRANS_NO);
- Дата и время выполнения платежа (LMI_SYS_TRANS_DATE);
- Пароль уведомлений продавца;
- E-mail покупателя (LMI_PAYER_PURSE);
- E-mail покупателя (LMI_PAYER_WM).
Формируется последовательность из 32-х шестнадцатеричных цифр в соответствии с широко распространенным алгоритмом Message Digest 5 (MD5). Контрольная подпись LMI_HASH передается в верхнем регистре (заглавными буквами).
Проверка контрольной подписи
Проверка контрольной подписи выполняется на сайте продавца по следующему алгоритму:
- Сформируйте строку путем "склеивания" значений параметров, полученных на URL уведомлений, в том же порядке, что и при формировании контрольной подписи в сервисе Pokupo (см. выше).
- Вычислите MD5 полученной строки.
- Преобразуйте строку в верхний регистр
- Сравните полученное значение с значением параметра "LMI_HASH", полученного через "Форму оповещения о платеже".
Проверка суммы платежа
Несмотря на то, что покупатель не может изменить сумму платежа, продавцу рекомендуется контролировать информацию о сумме платежа, передаваемую через параметр "LMI_PAYMENT_AMOUNT".
Проверка ID магазина
Несмотря на то, что покупатель не может изменить ID магазина, для которого совершается платеж, продавцу рекомендуется контролировать информацию о ID магазина, которая передается через параметр "LMI_PAYEE_PURSE", особенно при использовании нескольких магазинов при работе с Pokupo.
Детали статьи
Идентификатор статьи: | 20 |
Категория: | Техническая документация |
Дата добавления: | 2017-01-27 09:39:40 |
Просмотры: | 3038 |
Рейтинг (Голоса): |
|