Введение
API Factoring Мокка создано того, чтобы предоставить интернет-магазинам возможность простого и быстрого подключения дополнительного способа оплаты заказов – "Мокка – оплата авансом".
"Мокка – оплата авансом" – это мгновенное предоставление покупателю возможности оплаты покупки равными частями по заранее выбранному графику, в то время как Мокка переведёт вам деньги за покупку сразу.
С помощью методов API Factoring Мокка вы сможете зарегистрировать клиента в Мокка, произвести оплату покупки авансом, оформить отмену или возврат заказа. Использование API Factoring Мокка на сайте потребует минимальных доработок на стороне вашего интернет-магазина. В составе API Factoring Мокка уже присутствует клиентская форма ввода данных iFrame, посредством которой будет производиться взаимодействие с сервисом. Вам останется только реализовать способ оплаты, настроить отображение битой цены, и разместить на сайте маркетинговые материалы в строгом соответствии с гайдлайнами Мокка.
Бизнес-процессы
Использование API Factoring Мокка позволяет автоматизировать следующие бизнес-процессы:
- Получение лимита клиентом;
- Оплата авансом;
- Отмена заказа;
- Возврат товара.
Получение лимита
Процесс инициируется клиентом в момент, когда он регистрируется или авторизуется через баннер на главном экране или через битую цену в карточке товара.
- Клиент щелкает по баннеру Мокка или по битой цене на сайте партнёра;
- Партнёр отправляет в Мокка запрос Registration, передавая в нём все имеющиеся сведения о клиенте;
- Мокка передает партнёру ссылку на подготовленную форму регистрации;
- Партнёр отображает на своём сайте форму регистрации/авторизации Мокка;
- Клиент вводит в форму недостающие данные (текущий пользователь нажимает кнопку Войти и вводит номер телефона) и подтверждает согласие на использование его персональных данных, запуская оформление заявки на получение лимита;
- Клиент подтверждает оформление заявки вводя код, полученный в смс;
- Мокка рассчитывает и возвращает доступный клиенту лимит.
Оплата авансом
Процесс инициируется клиентом в момент, когда он оформляет заказ в интернет-магазине.
- Клиент выбирает способ оплаты "Мокка – Оплата авансом" совершая покупку в интернет-магазине партнёра;
- Партнёр отправляет в Мокка запрос Checkout, передавая в нём все имеющиеся сведения о клиенте;
- Мокка передает партнёру ссылку на подготовленную форму оформления заказа;
- Партнёр отображает на своём сайте форму оформления заказа Мокка;
- Клиент вводит в форму регистрации недостающие данные (текущий пользователь нажимает кнопку "Войти" и вводит номер телефона) и подтверждает согласие на использование его персональных данных, запуская оформление заявки;
- Мокка принимает решение о возможности выдачи клиенту аванса, рассчитывает доступные клиенту графики платежей;
- Клиент выбирает подходящий ему срок погашения аванса, и выражает согласие с предложенным ему графиком платежей, подтверждая покупку;
- Мокка формирует договор купли-продажи с использованием аванса, и информирует о принятом решении партнёра и клиента;
- Партнёр оформляет продажу товара клиенту;
- Клиент получает уведомление об успешной покупке;
- Партнёр осуществляет доставку заказа и отправляет чек покупки;
- Клиент принимает заказ;
- Партнёр отправляет в Мокка запрос Finish, включив в него чек покупки, для передачи договора купли-продажи на обслуживание в Мокка;
- Мокка отправляет реестр операций через API партнёра, и переводит на счёт партнёра денежные средства, за переуступку права требования долга с клиента в пользу Мокка.
Отмена заказа
Процесс инициируется клиентом в момент, когда он отменяет сделанный заказ на сайте партнёра его получения.
- Клиент отменяет оформленный заказ на сайте или через службу поддержки партнёра;
- Партнёр отправляет в Мокка запрос Cancel;
- Мокка производит отмену аванса и восстанавливает лимит клиента;
- Партнёр получает подтверждение отмены аванса и оформляет отмену заказа.
Возврат товара
Процесс инициируется клиентом в момент, когда он оформляет полный или частичный возврат купленного товара.
- Клиент оформляет частичный или полный возврат товара;
- Партнёр отправляет в Мокка запрос Return;
- Мокка подтверждает возможность отмены аванса;
- Партнёр получает подтверждение отмены аванса, и возвращает Мокка оплату за товары;
- Мокка производит действия в зависимости от типа возврата:
- Частичный возврат:
- Частичное восстановление лимита клиента в соответствии с суммой возврата;
- Пересчет графика платежей в соответствии с новой суммой покупки;
- Полный возврат:
- Полное восстановление лимита клиента;
- Возврат клиенту свободного остатка (денежных средств, уже внесенных клиентом в качестве погашения аванса);
- Частичный возврат:
Шаги интеграции
Процесс интеграции c API Factoring Мокка включает в себя следующие шаги:
-
Реализация: первичное ознакомление и тестирование использования API Factoring Мокка (как правило производится на тестовом стенде партнера).
-
Тестовая отладка: поиск и устранение ошибок, которые могут возникнуть в ходе отправки и обработки запросов.
-
Размещение маркетинговых материалов на стороне партнёра (должно соответствовать установленным компанией требованиям к визуализации);
-
Запуск: получение коммерческих настроек от менеджера по интеграции Мокка и старт приёма платежей.
Реализация
На данном шаге необходимо ознакомиться с порядком использования API Factoring Мокка, правилами формирования и отправки запросов к сервису и подготовить тексты запросов для проведения отладочного тестирования.
Тестирование и отладка запросов в ходе интеграции производятся на тестовом сервере
https://backend.demo.revoup.ru
Тестовые параметры
Для формирования тестовых запросов вам необходимо заранее получить от менеджера по интеграции Мокка тестовые параметры: идентификатор магазина – store_id и секретный ключ - secret_key.
Использование API
API Factoring реализовано на протоколе HTTPS на основе json-запросов. Запросы отправляются методом POST.
Объекты и методы API Factoring
Тип | Название | Описание | API URL |
---|---|---|---|
POST | Registration | Получение лимита | factoring/v1/limit/auth |
POST | Checkout | Оплата покупки авансом | factoring/v1/precheck/auth |
POST | Finish | Финализация заказа | factoring/v1/precheck/finish |
POST | Limit | Получение размера одобренного клиенту аванса | api/external/v1/client/limit |
POST | Status | Получение статуса заказа | factoring/v1/status |
POST | Schedule | Получение возможных графиков погашения аванса | factoring/v1/schedule |
POST | Change | Изменение суммы заказа | factoring/v1/precheck/change |
POST | Cancel | Отмена заказа | factoring/v1/precheck/cancel |
POST | Return | Возврат заказа (полный или частичный) | factoring/v1/return |
Авторизация
Каждый запрос к API требует авторизации. Для обработки запроса необходимо сформировать заголовок авторизации, включающий в себя:
https://backend.demo.revoup.ru
- базовый URL сервиса (тестовый);store_id
- уникальный идентификатор магазина, полученного от Мокка;signature
- цифровую подпись, сформированную на основании текста json-запроса и ключа secret_key.
Порядок формирования цифровой подписи
- Подготовить корректный json-запрос;
- Преобразовать текст запроса, добавив перед каждым символом «"» и «\» дополнительно символ «\»;
- К полученному результату добавить секретный ключ secret_key, полученный от Мокка;
- К итоговой строке применить алгоритм шифрования SHA1.
В результате получается цифровая подпись signature, длиной 40 символов, которую необходимо добавить в заголовок запроса.
Пример формирования цифровой подписи на ruby
- В переменную data вводится тело json запроса:
data = { "callback_url": "https://shop.ru/revo/decision", "redirect_url": "https://shop.ru/revo/redirect", "primary_phone": "9267654321", "primary_email": "LOGIN@MAIL.com", "current_order": { "order_id": "R001234" } } {:callback_url=>"https://shop.ru/revo/decision", :redirect_url=>"https://shop.ru/revo/redirect", :primary_phone=>"9267654321", :primary_email=>"LOGIN@MAIL.com", :current_order=>{:order_id=>"R001234"}}
- data переводится в json формат:
data = data.to_json "{"callback_url":"https://shop.ru/revo/decision","redirect_url":"https://shop.ru/revo/redirect","primary_phone":"9267654321","primary_email":"LOGIN@MAIL.com","current_order":{"order_id":"R001234"}}"
- В переменную secret_key вводится наименование ключа:
secret_key = "9fff8c602b08b00323567be0001480f6"
- В переменную signature формируется подпись:
signature = Digest::SHA1.hexdigest(secret_key + data) "347e8cff27d30b5200c8b32def4365ebbf4270d0"
- Тело json запроса выводится через команду puts для отправки запроса через API CLIENT:
puts data {"callback_url":"https://shop.ru/revo/decision","redirect_url":"https://shop.ru/revo/redirect","primary_phone":"9267654321","primary_email":"LOGIN@MAIL.com","current_order":{"order_id":"R001234"}}
Пример отправки запроса через API CLIENT
- В поле Request URL вводится заголовок запроса, с цифровой подписью, полученной на шаге 4 предыдущего раздела:
POST backend.demo.revoup.ru/{URL_API}? store_id=72&signature=347e8cff27d30b5200c8b32def4365ebbf4270d0
- В поле Body вводится текст запроса, полученный на шаге 5 предыдущего раздела:
{ "callback_url": "https://shop.ru/revo/decision", "redirect_url": "https://shop.ru/revo/redirect", "primary_phone": "9267654321", "primary_email": "LOGIN@MAIL.com", "current_order": { "order_id": "R001234" } }
Описание методов API
Описание методов и примеры запросов представлены в разделе API-методы.
Тестирование
На данном шаге необходимо выполнить тестирование методов API в определённой последовательности для поиска и устранения возможных ошибок в формировании и обработке запросов.
Порядок проведения отладочного тестирования:
- Получение лимита клиента;
- Совершение покупки;
- Отмена совершённого заказа;
- Возврат заказа.
При отправке тестовых запросов рекомендуется передавать параметры, предоставленные руководителем проекта со стороны Mokka
Ниже описаны сценарии проведения каждого этапа тестирования.
Получение лимита
Шаги | Ожидаемый результат |
---|---|
1. Отправка запроса Registration | Получение ссылки на iframe |
2. Вызов iframe_url | Отображение iframe |
3. Заполнение формы существующими в базе данными (номер телефона, использовавшийся на шаге ) и нажатие кнопки «Отправить SMS» | Переход на этап подтверждения СМС-кодом |
4. Ввод кода подтверждения: 1111 | Отображение экрана результата с информацией о текущем лимите |
Оформление покупки
Шаги | Ожидаемый результат |
---|---|
1. Отправка запроса Checkout | Получение ссылки на iframe |
2. Вызов iframe_url | Отображение iframe |
3. Нажатие кнопки "Войти", ввод номера предоставленного менеджером со стороны Мокка и нажатие кнопки «Отправить SMS» | Переход на этап подтверждения СМС-кодом |
4. Ввод кода подтверждения: 1111 | Отображение экрана результата с информацией об одобренном авансе и графиком платежей |
5. Отправка запроса Finish с прикрепленным файлом check.pdf или ссылкой на ОФД-1. | Получение положительного ответа (status=0) |
Отмена заказа
Шаги | Ожидаемый результат |
---|---|
1. Отправка запроса Checkout | Получение ссылки на iframe |
2. Вызов iframe_url | Отображение iframe |
3. Нажатие кнопки "Войти", ввод номера телефона предоставленного менеджером со стороны Мокка и нажатие кнопки «Отправить SMS» | Переход на этап подтверждения СМС-кодом |
4. Ввод кода подтверждения: 1111 | Отображение экрана результата с информацией об одобренном авансе и графиком платежей |
5. Отправка запроса Cancel | Получение положительного ответа (status=0) |
6. Отправка запроса Status | Получение ответа: decision = approved status = canceled |
Возврат заказа
Шаги | Ожидаемый результат |
---|---|
1. Отправка запроса Return c order_id=номеру заказа из п.2.1 и amount=стоимость возврата | Получение положительного ответа (status=0) |
2. Отправка запроса Status | Получение ответа: decision = approved status = refunded |
Коды ошибок
Код | Сообщение | Описание |
---|---|---|
0 | Payload valid | Всё ок |
10 | JSON decode error | Некорректный Запрос |
20 | Order order_id missing | Не указан order_id |
21 | Wrong order order_id format | Неверный формат order_id |
22 | Order exists | Заявка с данным order_id уже существует и финализирована |
23 | Order expired | У заявки с данным order_id уже истёк срок действия |
24 | Order with specified id not found | Заявка с указанным order_id не найден |
30 | Wrong order amount format | Значение amount указано в неверном формате (необходимо указать десятичные знаки) |
31 | Wrong order prepayment amount format | Значение prepayment_amount указано в неверном формате (необходимо указать десятичные знаки) |
32 | Order amount is different from the amount specified before | Указанная при финализации сумма заказа отличается от суммы, на которую совершен заказ. Финализация не осуществлена |
33 | Order amount is outside of tariff_limits | Сумма заявки не входит в диапазон, установленный в тарифе партнёра. Заявка не создана |
34 | Order term value is wrong | Указано некорректное значение срока погашения аванса term (не существует такого тарифа) |
35 | Order prepayment amount is wrong | Величина prepayment_amount превосходит amount |
40 | Order callback_url missing | Не указан callback_url |
41 | Order redirect_url missing | Не указан redirect_url |
50 | Store id is missing | Не указан store_id |
51 | Store not found | Не найден магазин с указанным store_id |
60 | Signature missing | Не указана цифровая подпись signature |
61 | Signature wrong | Указанная цифровая подпись signature некорректна |
62 | Error saving file | Ошибка при сохранении файла |
70 | Phone number is different | Номер телефона отличается от указанного в заявке |
71 | Client has not enough limit | У клиента недостаточно средств для осуществления оплаты частями заказа |
80 | Unable to finish - order is already finished/canceled | Не удаётся финализировать заявку - заявка с указанным order_id уже финализирована или отменена |
81 | Unable to cancel - order is already finished/canceled | Не удаётся отменить заявку - заявка с указанным order_id уже финализирована или отменена |
82 | Unable to change - order is already finished/canceled | Не удаётся изменить заявку - заявка с указанным order_id уже финализирована или отменена |
90 | Cart items are missing | Не удаётся изменить заявку - не передана информация о корзине |
100 | At the moment the server cannot process your request | Во всех остальных случаях |
110 | Invalid time format value | Неверный формат срока действия заявки valid_till |
404 | Not found | Подключение должно производиться по протоколу HTTPS |
Маркетинговые материалы
На данном шаге выполняется размещение маркетинговых материалов Мокка на сайте. Существуют определённые требования к визуализации сервиса Мокка на стороне партнёра. В ходе интеграции необходимо:
-
Разместить пункт "Мокка – оплата авансом" среди способов оплаты. Покупатели получают возможность получить аванс от Мокква и сразу рассчитаться.
Настройка: отправка запроса Checkout после оформления заказа.
-
Разместить на главной странице баннер, открывающий форму, заполнив которую клиент может зарегистрироваться и узнать сумму доступного ему аванса, не уходя из магазина.
Настройка: отправка запроса Registration при щелчке по баннеру.
-
Настроить отображение битой цены в карточке каждого товара. Битая цена покажет клиенту размер ежемесячного платежа при покупке товара с использованием аванса.
Настройка: отправка запроса Registration при щелчке по битой цене.
-
Разместить логотип платежной системы Мокка в футере вашего сайта (нижней части страниц).
Настройка: перенаправление на сайт Мокка при щелчке по логотипу.
-
Добавить на сайт лэндинг Мокка. На лэндинге клиент может ознакомиться с подробными условиями, зарегистрироваться и узнать размер доступного его аванса, а также получить ответы на часто задаваемые вопросы. Содержание лэндинга предоставляется в виде iframe.
Настройка: открытие страницы Мокка при щелчке по элементу.
- Добавить информацию о возможности использования сервиса Мокка в разделе «Доставка и оплата» (или аналогичном);
Кроме того, сотрудники партнёра, которые работают с клиентами, должны быть ознакомлены с правилами работы сервиса Мокка, перечисленными на странице https://help.mokka.support/hc/ru.
Внешний вид и работу элементов сервиса Мокка вы можете оценить, открыв демонстрационный сайт demo.mokka.ru.
Запуск
После успешного прохождения всех предыдущих шагов интеграции вы готовы к приёму платежей с помощью Аванса Мокка. Для запуска приема платежей необходимо обратиться к менеджеру по интеграции Мокка, для перевода вашего интернет-магазина в боевой режим и получения от него коммерческих настроек, таких как боевые ключи store_id и secret_key, а также базовый URL сервера для отправки боевых запросов.
Заменив тестовые настройки на коммерческие, вы открываете покупателям доступ к авансу Мокка, что существенно повысит количество продаж вашего интернет-магазина и сократит количество корзин, брошенных на этапе оформления.