Оплата счёта

Оглавление

  1. Общая схема оплаты счета в системе NextPay.ru.
    1. Создание продукта в кабинете продавца.
    2. Расчет стоимости заказа.
    3. Общая схема.
    4. Формирование заказа на сайте NextPay.ru.
    5. Формирование заказа на сайте продавца.
    6. Валидация заказа.
    7. Оплата заказа пользователем на сайте платежной системы.
    8. Доставка заказа через URL доставки заказа на сайте продавца.
  2. Формирование заказа на оплату счета через XML API NextPay.ru на сервере продавца.
    1. Параметры запроса.
    2. Сумма платежа.
    3. Обменные курсы.
    4. Поля формы заказа.
    5. Контрольная сумма.
    6. Проверка данных заказа сервером продавца.
    7. Ответ на запрос.
    8. Коды ошибок.
    9. ID платежных систем.

 

1. Общая схема оплаты счета в системе NextPay.ru

Данный документ описывает общую схему оплаты счета в системе продавца через систему NextPay.ru. Предполагается, что пользователь, зарегистрированный в системе продавца, создает счет в системе продавца на определенную сумму, который можно оплатить, используя сервисы NextPay.ru. При оплате пользователь НЕ вводит количество покупаемого продукта, как это делается в случае обычного продукта.

 

1.1 Создание продукта в кабинете продавца.

«Оплата счета» является продуктом в системе NextPay.ru, который продавец может создать в кабинете продавца, установив форму заказа для продукта в значение «Оплата счета»

 

1.2 Расчет стоимости заказа.

При оплате заказа передается сумма к оплате ext_order_cost в рублях, а пользователь выбирает, с помощью какой системы он хочет оплатить счет (определяется параметром volute). Для пересчета стоимости заказа в единицах платежной системы используется обменный курс E для платежной системы, определяемый сервером NextPay.ru.
То есть, стоимость заказа в единицах платежной системы С определяется по формуле:
С = ext_order_cost * E

 

1.3 Общая схема

Общая схема при оплате заказа такая (в порядке выполнения шагов):
  1. Формирование заказа (на сайте NextPay.ru или сайте продавца)
  2. Валидация заказа сервером продавца (через URL проверки заказа)
  3. Переход пользователя на сайт платежной системы (или показ дальнейших инструкций по оплате)
  4. Оплата пользователем заказа на сайте платежной системы
  5. Получение подтверждения об оплате (отказе оплаты)  сервером NextPay.ru от сервера платежной системы
  6. Доставка заказа через URL доставки заказа на сайте продавца
Ниже коротко описаны все эти пункты.

 

1.4 Формирование заказа на сайте NextPay.ru

Формирование заказа может происходить на сайте NextPay.ru, Для того чтобы сформировать заказ на сервере NextPay.ru достаточно перейти по URL, который прописан в настройках продукта в кабинете продавца на сайте NextPay.ru и оформить заказ, следуя инструкциям системы. При оформлении заказа с сайта продавца передается следующие параметры:
  1. seller_ext_order_id Номер счета, который был сформирован на сайте продавца, и который пользователь оплачивает. Это обязательное поле, оно НЕ отображается в форме заказа.
  2. volute ID платежной системы с помощью, которой он хочет оплатить счет. Необязательный параметр, если он не установлен, то на форме заказа будет выбрана первая платежная система из списка доступных для данного продукта.
  3. auto_submit. Если этот параметр передан, то плательщик сразу перенаправляется на сайт платежной системы для оплаты заказа.
Дальше пользователь следует инструкциям системы NextPay.ru и оплачивает счет. Каждому заказу при формировании назначается ID заказа в системе NextPay.ru order_id – это уникальное целое число, которое позволяет определить заказ в системе NextPay.ru. order_id отображается при формировании заказа, а так же передается в запросах при валидации заказа и доставке заказа (смотри разделы ниже).

 

1.5 Формирование заказа на сайте продавца.

Если же продавец по каким-либо причинам не хочет, чтобы пользователи оформляли заказ на сайте NextPay.ru, то он может воспользоваться XML API NextPay.ru для того чтобы сформировать заказ на своем сайте. NextPay.ru поставляет XML API клиент на php для формирования заказа через XML API. Этот клиент можно встроить в сайт продавца и формировать заказ на сайте продавца. Описание клиента и сам клиент находится в файле xml_client.zip.

 

1.6 Валидация заказа.

Во время формирования заказа происходит валидация данных заказа. Это делается вызовом URL валидации заказа и передачи в запросе данных заказа. URL валидации задается в настройках продукта в кабинете продавца на сайте NextPay.ru. Следующие параметры передаются в запросе при валидации заказа:
  1. currency ID выбранной пользователем для оплаты заказа платежной системы(целоe число), совпадает с параметром volute
  2. cost_general стоимость заказа в рублях, например 1.20
  3. cost стоимость заказа в единицах платежной системы, например 5.67 (смотри так же раздел Расчет стоимости заказа).
  4. seller_ext_order_id номер счета, который был сформирован на сайте продавца, и который пользователь оплачивает.
При валидации данных заказа скрипт валидации должен вернуть код возврата. На данный момент можно использовать такие коды (в дальнейшем этот список может быть расширен):
  1. ok  Все в порядке, валидация прошла успешно, можно переходить к оплате заказа
  2. invalid_order_id Счета с таким номером не существует
Т.е для того чтобы перейти к следующему шагу (оплате заказа на сайте платежной системы) скрипт валидации заказа должен вернут код возврата ok, в случае же ошибки скрипт может вернуть код invalid_order_id, и пользователю будет показано сообщение, соответствующие этому коду возврата. Любой другой код будет проигнорирован системой NextPay.ru, и пользователю будет показано сообщение об ошибке: «Произошла ошибка при обработке запроса сервером продавца», В любом случае оплата заказа будет возможна только после получения кода ok.
URL валидации заказа настраивается в настройках продукта в кабинете продавца на сервере NextPay.ru. NextPay.ru поставляет стандартный php шаблон для скрипта валидации заказа. Это файл validate.php, который находится в архиве mysql.zip (для mysql версии). Используя этот шаблон, продавец может разработать собственный скрипт валидации заказа.

 

1.7 Оплата заказа пользователем на сайте платежной системы

После перехода пользователя на сайт платежной системы статус заказа устанавливается в значение «Не оплачен». Перейдя на сайт платежной системы, пользователь должен следовать инструкциям платежной системы и оплатить заказ. В некоторых случаях, например при оплате с помощью систем Мобильный Платеж, пользователь остается на сайте NextPay.ru (или сайте продавца, если формирование заказа происходит на сайте продавца), и ему показывается инструкция о том, как оплатить заказ.

 

1.8 Доставка заказа через URL доставки заказа на сайте продавца

После получения подтверждения об оплате заказа сервером NextPay.ru от сервера платежной системы происходит доставка заказа через вызов URL доставки заказа. При этом в запросе на URL передаются следующие параметры заказа:
  1. test Тестовый заказ (1) или нет (0). Тестовые заказы не записываются на баланс продавца и могут быть созданы из кабинета продавца на сервере NextPay.ru.
  2. order_id ID заказа в системе NextPay.ru (цело число). Устанавливается автоматически системой NextPay.ru при формировании заказа (целое число).
  3. product_id ID продукта в системе NextPay.ru. Отображается в настройках продукта продавца кабинета продавца на сервере NextPay.ru (целое число).
  4. currency ID платежной системы, с помощью которой оплачивался заказ (целое число).
  5. cost_general Стоимость заказа в RUR (например, 3.67).
  6. cost Стоимость заказа в единицах платежной системы (например, 1.12)
  7. profit Прибыль продавца с заказа в рублях (например, 2.49).
  8. commission Комиссия NextPay.ru c прибыли продавца (например, 0.12)
  9. seller_ext_order_id номер счета, который был сформирован на сайте продавца, и который пользователь оплачивает (строка)
  10. payer_data Данные плательщика
  11. hash Контрольная сумма (строка). Считается по формуле:
    hash=sha1(test+product_id+order_id+currency+cost_general+cost+profit+commission+SECRET_KEY)
    Здесь знак «+» означает сложение строк, SECRET_KEY это секретный ключ продавца, настраиваемый в кабинете продавца на сервере NextPay.ru, а sha1 это хэш функция (смотри http://ru2.php.net/sha1). Так как секретный ключ продавца SECRET_KEY знает только NextPay.ru и сам продавец, то параметр hash может быть использован скриптом доставки для проверки того, что запрос пришел именно от сервера NextPay.ru. Для этого достаточно считать параметры, которые, входя в формулу контрольной суммы, посчитать контрольную сумму и сравнить ее с параметром hash, который передается в запросе, значения должны совпадать.
При доставке заказа скрипт доставки заказа должен вернуть код возврата ok, что будет означать успешную доставку заказа, при этом статус заказа будет установлен как «Оплачен и доставлен». Любой другой ответ отличный от ok, будет воспринят системой NextPay.ru как неудачную доставку заказа, ответ будет записан в журнал заказа, а статус заказа будет установлен как «Оплачен, но не доставлен». Оплаченный, но не доставленный заказ можно доставить повторно из кабинета продавца на сайте NextPay.ru. Оплаченный и доставленный заказ доставить повторно невозможно.
URL доставки заказа настраивается в настройках продукта в кабинете продавца на сервере NextPay.ru.
NextPay.ru поставляет стандартный набор php шаблонов скриптов доставки заказа. Это архив mysql.zip (для mysql версии). Используя эти  шаблоны, продавец  может разработать собственный скрипт доставки  заказа.

 

2. Формирование заказа на оплату счета через XML API NextPay.ru на сервере продавца

Данный раздел описывает XML API NextPay.ru. Используя  это API,  продавец  может формировать заказ на оплату счета на своем сайте, а не на сайте NextPay.ru. Для этого достаточно послать GET или POST запрос на URL http://nextpay.ru/shop/shop/index.php, и в запросе передать необходимые параметры (смотри раздел Параметры запроса).
После получения запроса сервер NextPay.ru анализирует данные запроса и проверяет данные заказа с помощью отправки запроса на сервер продавца (смотри раздел Проверка данных заказа сервером продавца). Если все в порядке, то формируется заказ. Формулу для расчета стоимости заказа смотри в разделе Сумма платежа.
В ответе на запрос отсылается ссылка для перехода на выбранную в запросе платежную систему, перейдя по которой можно оплатить сформированный заказ, либо информация о том, как оплатить заказ. Более детально ответ на запрос описан в разделе Ответ на запрос.

 

2.1 Параметры запроса

Название параметра Обязательный Тип Пояснение
command Да string Всегда нужно передавать значение xml_api_ext
product_id Да  int ID продукта продавца в системе NextPay.ru. Устанавливается  в NextPay.ru при создании продукта. Можно посмотреть в настройках продукта в кабинете продавца на  сервере NextPay.ru
volute Да int ID платежной системы. Смотри раздел «ID платежных систем»
ext_order_cost Да float (например, 2.72) Сумма счета в RUR
seller_ext_order_id Да string Номер счета, который был сформирован на сайте продавца, и который пользователь оплачивает (строка)
termua_bill_to_account Только при оплате с помощью «Терминалы Украины через webmoney.ua» String 12 символов Номер мобильного телефона в международном формате, например, 380501234567, 12 цифр, с кодом страны и без пробелов
mc_bill_to_account Только при оплате с помощью систем «Мобильный Платеж», «Связной», «Евросеть» String Номер абонента в международном формате, 11 цифр, первая цифра 7, например 79030000000
validate_only Нет Boolean Если установлен этот флаг, то будут проверены все параметры заказа, но сам заказ создан не будет
email Обязательный, если заказ оплачивается с помощью платежных систем Банковские карты[93], Visa/MasterCard (EUR)[96], Visa/MasterCard (USD)[97], Sofort (EUR)[98] String Email покупателя
fio Обязательный, используется только если заказ оплачивается с помощью платежных систем Банковские карты[93], Visa/MasterCard (EUR)[96], Visa/MasterCard (USD)[97], Sofort (EUR)[98] String ФИО покупателя
phone Не обязательный, используется только если заказ оплачивается с помощью платежных систем Банковские карты[93], Visa/MasterCard (EUR)[96], Visa/MasterCard (USD)[97], Sofort (EUR)[98] String Телефон покупателя
ip Обязательный, используется только если заказ оплачивается с помощью платежных систем Банковские карты[93], Visa/MasterCard (EUR)[96], Visa/MasterCard (USD)[97], Sofort (EUR)[98] String IP адрес покупателя
hash Да String Контрольная сумма. Смотри раздел «Контрольная сумма».

 

2.2 Сумма платежа

Передается сумма к оплате ext_order_cost в руб. Для пересчета стоимости заказа в единицах платежной системы используется обменный курс E (смотри раздел Обменные курсы) для платежной системы, определяемый сервером NextPay.ru. То есть, стоимость заказа в единицах платежной системы С определяется по формуле:
С = ext_order_cost * E

 

2.3 Обменные курсы

Список доступных платежных систем для продукта с ID product_id и обменные курсы для этих систем доступны c сервера NextPay.ru в виде XML в кодировке UTF-8 по запросу:
http://nextpay.ru/shop/shop/index.php?command=rates_product_xml&product_id=product_id
product_id – ID продукта в системе NextPay.ru: можно посмотреть в настройках продукта в кабинете продавца в системе NextPay.ru.
Ответ на запрос обменных курсов приходит в кодировке UTF-8  в формате XML в следующем виде:
<rates>
  <currency>
    <name>WMR</name>
    <rate>1.0000</rate>
    <description>WMR</description>
    <id>2</id>
  </currency>
  <currency>
    <name>WMZ</name>
    <rate>0.0364</rate>
    <description>WMZ</description>
    <id>3</id>
  </currency>
</rates>
<name>WMZ</name> – Название платежной системы (смотри раздел «ID платежных систем»).
<id>2</id> – ID платежной системы (смотри раздел «ID платежных систем»).
<description>WMZ</description> Описание платежной системы
<rate>0.0364</rate> – Обменный курс по отношению к рублю (число с 4-мя знаками после запятой). То есть, сколько рублей стоит единица платежной системы.
Список доступных платежных систем для продукта настраивается в кабинете продавца на сервере NextPay.ru.

 

2.4 Поля формы заказа

Список полей формы заказа продукта с ID product_id  доступен c сервера NextPay.ru в виде XML в кодировке UTF-8 по запросу:
http://nextpay.ru/shop/shop/index.php/?command=product_xml&product_id=product_id
product_id – ID продукта в системе NextPay.ru: можно посмотреть в настройках продукта в кабинете продавца в системе NextPay.ru.
Ответ на этот запрос приходит в кодировке UTF-8 в формате XML в следующем виде:
Аттрибут/Тэг Описание
product/name Название продукта
product/id ID продукта в системе NextPay.ru, целое число
product/form_id ID формы заказа в системе NextPay.ru, целое число
product/form-attribute@id ID поля, целое число
product/form-attribute@hidden Отображается или нет поле в форме (0 или 1)
product/form-attribute@type Тип поля: 1 – целое число, 2 – строка, 3 - список
product/form-attribute@required Поле обязательное или нет к заполнению (0 или 1)
product/form-attribute@name Название поля. Именно это название передается в URL валидации заказа
product/form-attribute/form-attribute-label Ярлык поля (для отображения)
form-attribute/form-attribute-default-value Значение поля по умолчанию
product/form-attribute/form-attribute-values-array Только для поля, тип которого список (type=3): список значений поля в виде строки, элементы списка разделяются символом “;”. Например, 1;2;3;4;5. Число элементов в списке должно соответствовать числу элементов в строке form-attribute-values-array
product/form-attribute/form-attribute-labels-array Только для поля, тип которого список (type=3): список ярлыков поля в виде строки, элементы списка разделяются символом “;”. Например, значение1;значение2;значение3;значение4;значение5. Число элементов в списке должно соответствовать числу элементов в строке form-attribute-values-array

 

2.5 Контрольная сумма

В запросе нужно передать параметр hash (Контрольная сумма). Он устанавливается так:
hash == sha1(product_id+ext_order_cost+secret_key)
product_id ID продукта – можно посмотреть в настройках продукта в кабинете продавца на сервере NextPay.ru.
ext_order_cost Сумма счета.
secret_key Секретный ключ продавца – можно посмотреть в настройках продавца в кабинете продавца в системе NextPay.ru.
sha1 Функция для вычисления хэш по алгоритму sh1 (смотри http://ru2.php.net/sha1), знак «+» подразумевает сложение строк.
Значение контрольной суммы зависит от параметра secret_key, который известен только продавцу и серверу NextPay.ru, что позволяет серверу NextPay.ru определить,  что запрос на формирования заказа происходит именно с сайта продавца. При неверном значении параметра hash в запросе ответ на запрос будет содержать ошибку с кодом 11 (смотри раздел Коды ошибок):
<response>
  <result>11</result>
  <comment>Ошибка проверки контрольной суммы</comment>
</response>

 

2.6 Проверка данных заказа сервером продавца

После получения запроса сервер NextPay.ru проверяет параметры запроса и дополнительно может произвести проверку параметров самим сервером продавца. Это делается посылкой http запроса на URL валидации заказа, который настраивается в свойствах продукта в кабинете продавца в системе NextPay.ru. Если этот URL, не задан, то дополнительная проверка не производится. В случае неуспешной проверки параметров сервером продавца высылается код ошибки 8.  Смотри раздел Коды ошибок. Комментарий к результату проверки в случае ошибки пишется в ответе в теге <comment>. При отправке запроса на  URL валидации заказа передаются поля формы заказа, которые указаны в форме заказа продукта в свойствах продукта в кабинете продавца на сервере NextPay.ru.

 

2.7 Ответ на запрос

Ответ всегда приходит в виде XML в кодировке UTF-8 в следующем формате:
<response>
  <result>$result</result>
  <order_id>$orderId</order_id>
  <data>$data</data>
  <comment>$comment</comment>
</response>
<result>$result</result> – Код ошибки. Смотри раздел «Коды ошибок». В случае успеха $result равен 0.
<order_id>$orderId</order_id> ID созданного заказа в системе NextPay.ru (целое положительное число). Если произошла ошибка, то $orderId пустой.
<data>$data</data> – Данные ответа. Передаются ТОЛЬКО В случае успешного создания заказа (то есть если все параметры заказа были переданы корректно, и прошла проверка данных заказа на сервере продавца). $data  принимает одно из следующих значений:

  1. URL, по которому необходимо перейти, чтобы попасть на сайт соответствующей платежной системы для оплаты заказа.
  2. В случае оплаты с помощью систем «Мобильный платеж». Инструкция в виде HTML кода, поясняющая как оплатить заказ.
  3. В случае оплаты с помощью «Терминалы Украины через webmoney.ua». Инструкция в виде HTML кода, поясняющая как оплатить заказ.

<comment>$comment</comment> Дополнительная информация, поясняющая код ошибки. Смотри раздел Коды ошибок.

 

2.8 Коды ошибок

Код Объяснение
0 Код успешного выполнения
-1 Внутренняя ошибка
1 Параметр product_id не передан
2 Продукт не найден по product_id
3 Цена на продукт не определена. Обратитесь к NextPay.ru
4 Для данного продукта эта платежная система (параметр volute) не включена
5 Ошибка при расчете стоимости заказа
6 Сумма платежа меньше минимального значения установленного для выбранной платежной системы
7 Не передано одно из обязательных полей формы заказа  
8 Неудачная проверка запроса сервером продавца
9 Платежная система (параметр volute) не поддерживается
10 Параметр volute не передан
11 Ошибка проверки контрольной суммы
12 Неверная сумма заказа (в рублях) при формировании заказа. Ожидалось значение > 0
13 Неверное значение параметра quantity. Ожидалось целое значение > 0
14 Неверное значение параметра kiwi_bill_to_account. Должно быть 10 цифр

 

2.9 ID платежных систем

Актуальные ID платежных систем доступны в кабинете продавца в разделе "Настройки" или в настройках самих продуктов.