API (документация по интеграции мобильной коммерции)
1. Инициация мобильного платежа через интернет
2. Инициация мобильного платежа через отправку SMS сообщения на короткий номер
1. Инициация мобильного платежа через интернет
- Находясь на сайте «продавца», абонент желает оплатить покупку с мобильного телефона. Он выбирает товар и вводит свой номер телефона.
- Система «продавца» генерирует код товара и совершает инициацию платежа путём отправки HTTP GET запроса на скрипт Electronic Vostok. Код товара - строка, не содержащая пробелов, длиной желательно до 50 символов.
- Запрос на платёж передаётся оператору связи, за которым закреплён данный абонент. Далее платформа оператора связи выполняет двухшаговый алгоритм проведения платежа.
- Cистема Electronic Vostok, получая первый шаг от оператора, делает HTTP GET запрос на скрипт «продавца», в параметрах передавая уникальный идентификатор платежа, номер абонента и код товара. Этот первый шаг - не сам платёж, а проверка, возможен ли такой платёж.
- Скрипт «продавца», глядя на номер абонента и код товара, пытается определить, что хочет купить абонент. Если скрипту удаётся понять, что хочет абонент, скрипт должен вернуть стоимость товара и его краткое описание. Если скрипту не удаётся понять, что именно хочет купить абонент - скрипт возвращает сообщение об этом.
- Абонент получает описание товара и стоимость. У него запрашивается согласие приобрести указанный товар по указанной цене.
- Если абонент соглашается совершить покупку, на скрипт «продавца» приходит ещё один HTTP GET запрос, как в пункте 2), но с ещё одним дополнительным GET-параметром, указывающим, что это уже не проверка возможности платежа, а именно подтверждение покупки. На этом шаге «продавец» должен оказать абоненту услугу, а скрипт должен вернуть подтверждение успешности операции.
ТЕХНИЧЕСКОЕ ОПИСАНИЕ:
Запрос-инициация совершается системой "продавца" на скрипт Electronic Vostok и содержит два GET-параметра:
- subno - номер абонента, в формате 7xxxxxxxxxx
- text - код товара, кодировка UTF8
В запросе-проверке на скрипт «продавца» передаются четыре HTTP GET параметра:
- subno - номер абонента, в формате 7xxxxxxxxxx
- keyword - ключевое слово, выделенное "продавцу" при подключении, кодировка UTF8
- text - код товара, кодировка UTF8
- paymentid - уникальный идентификатор платежа, BIGINT
В ответ на запрос-проверку скрипт «продавца» должен в теле ответа вернуть строку, состоящую из стоимости товара и краткого описания. Разделитель между ними - точка с запятой. Если скрипт не может понять, что хочет приобрести абонент, то вместо стоимости должен быть 0, а вместо описания товара - описание ошибки.
В запросе-подтверждении на скрипт «продавца» передаются пять HTTP GET параметров:
- subno - номер абонента, в формате 7xxxxxxxxxx
- keyword - ключевое слово, выделенное "продавцу" при подключении, кодировка UTF8
- text - код товара, кодировка UTF8
- paymentid - уникальный идентификатор платежа (такой же, как и в запросе-проверке)
- confirm - признак того, что это запрос-подтверждение, а не запрос-проверка.
В ответ на запрос-подтверждение скрипт «продавца» должен в теле ответа вернуть строку, состоящую из флага успешной операции (0 - неудача, 1 - успех) и текстового описания операции. Разделитель между ними - точка с запятой.
Важно: в случае проблем со связью запросы-проверки и запросы-подтверждения могут приходить повторно на скрипт «продавца». На такие повторные запросы скрипт должен выдавать корректные ответы, но при повторном получении запроса-подтверждения с уже оплаченным paymentid второй раз оказывать услугу не нужно, нужно лишь продублировать ответ об успешном выполнении платежа.
ПРИМЕР ПЛАТЕЖА:
Запрос-инициация:
http://electronic.vostok.url/our_script?subno=79260000000&text=fff%2B100
Запрос-проверка:
http://your.server/your_script?subno=79260000000&keyword=KW&text=fff%2B100&paymentid=1234567890123456789
Ответ скрипта:
40;Пополнение баланса аккаунта fff на 100 баллов
(абонент после этого получает на свой телефон вопрос "Для подтверждения операции "Пополнение баланса аккаунта fff на 100 баллов", стоимость 40 рублей, отправьте 1 в ответ на это сообщение", формулировка примерная, у каждого оператора связи она своя).
Если абонент даёт своё согласие, выполняя запрошенные оператором связи действия (в данном примере, ответив на смс-ку единицей), то двигаемся дальше.
Запрос-подтверждение:
http://your.server/your_script?subno=79260000000&keyword=KW&text=fff%2B100&paymentid=1234567890123456789&confirm=1
Ответ скрипта:
1;Баланс успешно пополнен
2. Инициация мобильного платежа через отправку SMS сообщения на короткий номер
- «Продавец» размещает рекламу сервиса, содержащую инструкцию по отправке смс согласованного с Electronic Vostok формата на согласованный номер.
- Абонент видит рекламу, решает совершить платёж и отправляет смс сообщение.
- Electronic Vostok получает смс и исходя из текста формирует запрос на платёж. Запрос на платёж передаётся оператору связи, за которым закреплён данный абонент. Далее платформа оператора связи выполняет двухшаговый алгоритм проведения платежа.
- Cистема Electronic Vostok, получая первый шаг от оператора, делает HTTP GET запрос на скрипт «продавца», в параметрах передавая уникальный идентификатор платежа, номер абонента и код товара. Этот первый шаг - не сам платёж, а проверка, возможен ли такой платёж.
- Скрипт «продавца», глядя на номер абонента и код товара, пытается определить, что хочет купить абонент. Если скрипту удаётся понять, что хочет абонент, скрипт должен вернуть стоимость товара и его краткое описание. Если скрипту не удаётся понять, что именно хочет купить абонент - скрипт возвращает сообщение об этом.
- Абонент получает описание товара и стоимость. У него запрашивается согласие приобрести указанный товар по указанной цене.
- Если абонент соглашается совершить покупку, на скрипт «продавца» приходит ещё один HTTP GET запрос, как в пункте 2), но с ещё одним дополнительным GET-параметром, указывающим, что это уже не проверка возможности платежа, а именно подтверждение покупки. На этом шаге «продавец» должен оказать абоненту услугу, а скрипт должен вернуть подтверждение успешности операции.
ТЕХНИЧЕСКОЕ ОПИСАНИЕ:
В запросе-проверке на скрипт «продавца» передаются четыре HTTP GET параметра:
- subno - номер абонента, в формате 7xxxxxxxxxx
- keyword - ключевое слово, выделенное "продавцу" при подключении, кодировка UTF8
- text - код товара, кодировка UTF8
- paymentid - уникальный идентификатор платежа, BIGINT
В ответ на запрос-проверку скрипт «продавца» должен в теле ответа вернуть строку, состоящую из стоимости товара и краткого описания. Разделитель между ними - точка с запятой. Если скрипт не может понять, что хочет приобрести абонент, то вместо стоимости должен быть 0, а вместо описания товара - описание ошибки.
В запросе-подтверждении на скрипт «продавца» передаются пять HTTP GET параметров:
- subno - номер абонента, в формате 7xxxxxxxxxx
- keyword - ключевое слово, выделенное "продавцу" при подключении, кодировка UTF8
- text - код товара, кодировка UTF8
- paymentid - уникальный идентификатор платежа (такой же, как и в запросе-проверке)
- confirm - признак того, что это запрос-подтверждение, а не запрос-проверка.
В ответ на запрос-подтверждение скрипт «продавца» должен в теле ответа вернуть строку, состоящую из флага успешной операции (0 - неудача, 1 - успех) и текстового описания операции. Разделитель между ними - точка с запятой.
Важно: в случае проблем со связью запросы-проверки и запросы-подтверждения могут приходить повторно на скрипт «продавца». На такие повторные запросы скрипт должен выдавать корректные ответы, но при повторном получении запроса-подтверждения с уже оплаченным paymentid второй раз оказывать услугу не нужно, нужно лишь продублировать ответ об успешном выполнении платежа.
ПРИМЕР ПЛАТЕЖА:
Запрос-проверка:
http://your.server/your_script?subno=79260000000&keyword=KW&text=fff%2B100&paymentid=1234567890123456789
Ответ скрипта:
40;Пополнение баланса аккаунта fff на 100 баллов
(абонент после этого получает на свой телефон вопрос "Для подтверждения операции "Пополнение баланса аккаунта fff на 100 баллов", стоимость 40 рублей, отправьте 1 в ответ на это сообщение", формулировка примерная, у каждого оператора связи она своя).
Если абонент даёт своё согласие, выполняя запрошенные оператором связи действия (в данном примере, ответив на смс-ку единицей), то двигаемся дальше.
Запрос-подтверждение:
http://your.server/your_script?subno=79260000000&keyword=KW&text=fff%2B100&paymentid=1234567890123456789&confirm=1
Ответ скрипта:
1;Баланс успешно пополнен
