Интеграция по API

Введение

API Factoring Мокка создано для того, чтобы предоставить интернет-магазинам возможность простого и быстрого подключения дополнительного способа оплаты заказов – «Мокка – оплата авансом».

Использование API Factoring Мокка на сайте потребует минимальных доработок на стороне вашего интернет-магазина. В составе API уже присутствует клиентская форма ввода данных iFrame, посредством которой будет производиться взаимодействие с сервисом. Вам останется только реализовать способ оплаты, настроить отображение виджета Мокка и разместить на сайте маркетинговые материалы в соответствии с гайдлайнами Мокка.

Бизнес-процессы

Использование API позволяет автоматизировать следующие бизнес-процессы:

Получение лимита клиентом
Создание и завершение заказа
Отмена заказа
Возврат

Получение лимита

Процесс инициируется клиентом в момент, когда он регистрируется/авторизуется через виджет Мокка в карточке товара.

Клиент нажимает на виджет в карточке товара;
Партнёр отправляет в Мокка запрос Registration, передавая в нём все имеющиеся сведения о клиенте;
Мокка передает партнёру ссылку на подготовленную форму регистрации;
Партнёр отображает на своём сайте форму регистрации/авторизации Мокка;
Клиент вводит в форму недостающие данные (текущий пользователь нажимает кнопку Войти и вводит номер телефона) и подтверждает согласие на использование его персональных данных, запуская оформление заявки на получение лимита;
Клиент подтверждает оформление заявки вводя код из СМС;
Мокка рассчитывает и возвращает доступный клиенту лимит.

Создание и завершение заказа

Процесс инициируется клиентом в момент, когда он оформляет заказ в интернет-магазине.

Клиент выбирает способ оплаты «Мокка – Оплата авансом» совершая покупку в интернет-магазине партнёра;
Партнёр отправляет в Мокка запрос Checkout, передавая в нём все имеющиеся сведения о клиенте;
Мокка передает партнёру ссылку на подготовленную форму оформления заказа;
Партнёр отображает на своём сайте форму оформления заказа Мокка;
Клиент вводит в форму регистрации недостающие данные (текущий пользователь нажимает кнопку «Войти» и вводит номер телефона) и подтверждает согласие на использование его персональных данных, запуская оформление заявки;
Мокка принимает решение о возможности выдачи клиенту аванса, рассчитывает доступные клиенту графики платежей;
Клиент выбирает подходящий ему срок погашения аванса, и выражает согласие с предложенным ему графиком платежей, подтверждая покупку;
Мокка формирует договор купли-продажи с использованием аванса, и информирует о принятом решении партнёра и клиента;
Партнёр оформляет продажу товара клиенту;
Клиент получает уведомление об успешной покупке;
Партнёр осуществляет доставку заказа и отправляет чек покупки;
Клиент принимает заказ;
Партнёр отправляет в Мокка запрос Finish, включив в него чек покупки, для передачи договора купли-продажи на обслуживание в Мокка;
Мокка отправляет реестр операций на почту партнёра, и переводит на счёт партнёра денежные средства, за переуступку права требования долга с клиента в пользу Мокка.

Отмена заказа
Процесс инициируется клиентом в момент, когда он отменяет сделанный заказ на сайте партнёра до его получения.

Клиент отменяет оформленный заказ на сайте или через службу поддержки партнёра;
Партнёр отправляет в Мокка запрос Cancel;
Мокка производит отмену аванса и восстанавливает лимит клиента;
Партнёр получает подтверждение отмены аванса и оформляет отмену заказа.

Возврат товара
Процесс инициируется клиентом в момент, когда он оформляет полный или частичный возврат купленного товара.

Клиент оформляет частичный или полный возврат товара;
Партнёр отправляет в Мокка запрос Return;
Мокка подтверждает возможность отмены аванса;
Партнёр получает подтверждение отмены аванса, и возвращает Мокка оплату за товары;
Мокка производит действия в зависимости от типа возврата:
- Частичный возврат:
  - Частичное восстановление лимита клиента в соответствии с суммой возврата;
  - Пересчет графика платежей в соответствии с новой суммой покупки;
- Полный возврат:
  - Полное восстановление лимита клиента;
  - Возврат клиенту свободного остатка (денежных средств, уже внесенных клиентом в качестве погашения аванса);

Шаги интеграции

Процесс интеграции c Мокка включает в себя следующие шаги:

Реализация: первичное знакомство и интеграция с Мокка.
Виджет Мокка: разместить виджет на карточках товаров.
Размещение маркетинговых материалов: разместить маркетинговые материалы Мокка согласно гайдлайнам.
Тестирование: поиск и устранение ошибок, которые могут возникнуть в ходе отправки и обработки запросов.
Запуск: получение боевых настроек от менеджера по интеграции Мокка и старт приёма платежей.

Реализация

На данном шаге необходимо ознакомиться с порядком использования API Factoring Мокка, правилами формирования и отправки запросов к сервису и подготовить тексты запросов для проведения отладочного тестирования.

Тестирование и отладка запросов в ходе интеграции производятся на тестовом сервере:

https://demo.revoup.ru

Тестовые параметры
Для формирования тестовых запросов вам необходимо заранее получить от менеджера по интеграции Мокка тестовые параметры: идентификатор магазина – store_id и секретный ключ — secret_key.

Методы API
API Factoring реализовано на протоколе HTTPS на основе json-запросов. Запросы отправляются методом POST.

Тип	Название	Описание	API URL
POST	Registration	Получение лимита	factoring/v1/limit/auth
POST	Limit	Получение размера одобренного клиенту аванса	api/external/v1/client/limit
POST	Checkout	Оплата покупки авансом	factoring/v1/precheck/auth
POST	Status	Получение статуса заказа	factoring/v1/status
POST	Cancel	Отмена заказа	factoring/v1/precheck/cancel
POST	Finish	Финализация заказа	factoring/v1/precheck/finish
POST	Return	Возврат заказа (полный или частичный)	factoring/v1/return

Авторизация
Каждый запрос к API требует авторизации. Для обработки запроса необходимо сформировать заголовок авторизации, включающий в себя:

https://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", ...}

data переводится в json формат:

data = data.to_json
# "{"callback_url":"https://shop.ru/revo/decision", ...}"

В переменную secret_key вводится наименование ключа:
```
secret_key = "wkeo0iNv8iZHXCFLEzu2NQzz97nLn0"
```

В переменную signature формируется подпись:

signature = Digest::SHA1.hexdigest(secret_key + data)
# "347e8cff27d30b5200c8b32def4365ebbf4270d0"

Тело json запроса выводится через команду puts для отправки запроса через API CLIENT:
```
puts data
# {"callback_url":"https://shop.ru/revo/decision", ...}
```

Пример отправки запроса через API CLIENT

В поле Request URL вводится заголовок запроса, с цифровой подписью, полученной на шаге 4 предыдущего раздела:
```
POST https://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"
    }
}

Виджет Мокка

Виджет представляет собой встраиваемый код. После его установки появится возможность отображать на вашем сайте в карточке товара информацию о визуальных элементах Мокка и взаимодействовать с покупателем.

Для интеграции виджета Мокка на ваш сайт, выполните следующие шаги:

Добавление контейнера для кнопки
Вставьте следующий HTML-код в футер вашего сайта или в другое подходящее место на странице, где должна появиться кнопка:

<!-- Контейнер, в который будет добавлена кнопка -->
<div id="container-id"></div>

Обратите внимание на следующие параметры:

containerId — Укажите id контейнера, в который будет добавлена кнопка.

Подключение и инициализация
Добавьте следующий скрипт на страницу после контейнера:

<!-- Подключаем виджет Мокка -->
<script src="https://storage.yandexcloud.net/mb-prod-ru-public/data/attachment/file/split_price_widget_code/451770d6494e5511750a5081b1e037bfd31b466a.js"></script>
<script>
document.addEventListener("DOMContentLoaded", () => {
// После загрузки скрипта вызываем метод init с параметрами
revoPriceWidget.init({
    months: [X, XX], // Период
    overpaymentAmount: xxx, // Сумма переплаты
    orderAmount: XXX, // Минимальная сумма заказа
    button: {
        containerId: "container-id", // ID элемента, в который добавляется кнопка
        payment: XXX, // Минимальный размер платежа
        theme: "orange", // Тема кнопки: "white" | "black" | "orange"
        onClick: () => { // Обработчик клика по кнопке
            console.log('click');
        }
    }
});
});
</script>

Обратите внимание на следующие параметры:

containerId — Укажите id контейнера, в который будет добавлена кнопка.
months — Задайте период, в течение которого применяются условия (например, [1, 10]).
overpaymentAmount — Укажите сумму переплаты.
orderAmount — Укажите минимальную сумму заказа.
payment — Укажите минимальный размер платежа.
theme — Выберите тему кнопки (возможные значения: «white», «black», «orange»).

Реализация события onClick
В обработчике события onClick вам необходимо реализовать вызов метода Registration через бекенд вашего сайта. Это обеспечит открытие iframe после нажатия на кнопку.
Пример обработчика:

onClick: () => {
// Вызов метода Registration через бекенд вашего сайта
// Пример кода вызова API
fetch('/your-backend-endpoint',
{
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
    },
    body: JSON.stringify({
        // Параметры для метода Registration
    }),
})
.then(response => response.json())
.then(data => {
    // Открываем iframe с данными
    console.log(data);
})
.catch(error => console.error('Ошибка:', error));
}

Маркетинговые материалы

На данном шаге выполняется размещение маркетинговых материалов Мокка на сайте. Существуют определённые требования к визуализации сервиса Мокка на стороне партнёра. В ходе интеграции необходимо:

Разместить на главной странице баннер, при нажатии на который клиент будет перенаправлен на лендинг Мокка. На лендинге клиент может зарегистрироваться и узнать сумму доступного ему аванса.

Настройка: отправка запроса Registration при щелчке по баннеру.
Настроить отображение виджета Мокка в карточке каждого товара. Виджет покажет клиенту размер ежемесячного платежа при покупке товара с использованием аванса.

Настройка: отправка запроса Registration при нажатии по виджету Мокка.
Разместить способ оплаты «Мокка – оплата авансом» в корзине. Покупатели получают возможность моментально получить аванс Мокка и оформить заказ.

Настройка: отправка запроса Checkout после оформления заказа.
Добавить на поддомен вашего сайта лендинг Мокка. На лендинге клиент может ознакомиться с подробными условиями, зарегистрироваться и узнать размер доступного его аванса, а также получить ответы на часто задаваемые вопросы. Содержание лендинга предоставляется в виде iframe.
Добавить информацию о возможности использования сервиса Мокка в разделе «Способы оплаты»

Тестирование

На данном шаге необходимо выполнить тестирование методов 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 или ссылкой чек.	Получение положительного ответа (status=0)

Отмена заказа

Шаги	Ожидаемый результат
1. Отправка запроса Checkout	Получение ссылки на iframe
2. Открытие iframe_url	Отображение iframe
3. Нажатие кнопки «Войти», ввод номера телефона предоставленного менеджером со стороны Мокка и нажатие кнопки «Отправить SMS»	Переход на этап подтверждения СМС-кодом
4. Ввод кода подтверждения: 1111	Отображение экрана результата с информацией об одобренном авансе и графиком платежей
5. Отправка запроса Cancel	Получение положительного ответа (status=0)

Возврат заказа

Шаги	Ожидаемый результат
1. Отправка запроса Return c order_id=номеру заказа из п.2.1 и amount= сумма возврата	Получение положительного ответа (status=0)
2. Отправка запроса Status	Получение ответа: decision = approved status = refunded

Запуск

После тестирования и настройки методов можно перейти к созданию реальных заявок.
Для создания реальных заявок используйте метод Checkout.
Для работы с методом Checkout, используйте боевые ключи store_id и secret_key, а также боевой URL, полученные от персонального менеджера.
Расскажите своим клиентам о новом способе оплаты Мокка, используя маркетинговые материалы.

Помогла ли вам эта статья?

Да

Нет

Спасибо за обратную связь!

Остались вопросы?

ОТПРАВИТЬ ЗАПРОС

Акции

Документы, отчеты и сверка

Кабинет консультанта

Кабинет партнера Мокка

Как потратить аванс

Как стать партнером Мокка

Личный кабинет и настройки

Маркетинговые материалы

Моя карта Мокка

Переводы и снятие наличных

Платежи и способы погашения

Подключение онлайн-магазинов

Подключение оффлайн-магазинов

Регистрация в сервисе

Частые вопросы

Интеграция по API

Введение

Бизнес-процессы

Шаги интеграции

Реализация

Виджет Мокка

Маркетинговые материалы

Тестирование

Запуск

Помогла ли вам эта статья?

Остались вопросы?