Помощь и поддержка


Назад

Протокол уведомлений 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 уведомлений, указанный продавцом в настройках магазина. Мы рекомендуем вам проверить полученные уведомления:

  1. Проверить, действительно ли данные переданы от сервиса Pokupo (Проверка источника данных)
  2. Проверить, не исказились ли данные в процессе передачи (с помощью проверки хэша)
  3. Проверить сумму платежа
  4. Проверить 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 передается в верхнем регистре (заглавными буквами).

Проверка контрольной подписи

Проверка контрольной подписи выполняется на сайте продавца по следующему алгоритму:

  1. Сформируйте строку путем «склеивания» значений параметров, полученных на URL уведомлений, в том же порядке, что и при формировании контрольной подписи в сервисе Pokupo (см. выше).
  2. Вычислите MD5 полученной строки.
  3. Преобразуйте строку в верхний регистр
  4. Сравните полученное значение с значением параметра «LMI_HASH», полученного через «Форму оповещения о платеже».

Проверка суммы платежа

Несмотря на то, что покупатель не может изменить сумму платежа, продавцу рекомендуется контролировать информацию о сумме платежа, передаваемую через параметр «LMI_PAYMENT_AMOUNT».

Проверка ID магазина

Несмотря на то, что покупатель не может изменить ID магазина, для которого совершается платеж, продавцу рекомендуется контролировать информацию о ID магазина, которая передается через параметр «LMI_PAYEE_PURSE», особенно при использовании нескольких магазинов при работе с Pokupo.

Назад

Другие статьи по теме Техническая документация:

    Knowledgebase is empty

Не нашли, что искали?