Введение

API Factoring реализовано на протоколе HTTPS на основе JSON запросов.

Документация состоит из следующих основных частей:

• Авторизация.
• Методы API.
• Коды ошибок.
• Описание iFrame.
• Представление сервиса Мокка на сайте.
• Тестирование и отладка.

Авторизация

Базовые URL адреса

BASE_URL = "https://r.revo.ru"
BASE_URL = "https://backend.demo.revoup.ru"

1. Для взаимодействия с сервисами Мокка используются 2 базовых адреса:
   • https://r.revo.ru - адрес production сервиса.
   • https://backend.demo.revoup.ru - адрес demo сервиса.
2. BASE_URL - переменная обозначающая базовый адрес.

Параметры авторизации

Пример параметров

secret_key = "098f6bcd4621d373cade4e832627b4f6"
STORE_ID = 123

1. На стороне Мокка формируются уникальный идентификатор магазина и секретный ключ, которые передаются партнеру:
   • store_id - уникальный идентификатор магазина. Для одного партнера может быть сформировано несколько уникальных идентификаторов.
   • secret_key - секретный ключ, который используется при формировании электронно-цифровой подписи для аутентификации (проверки подлинности) параметров запроса с целью защиты формы от запуска сторонними лицами. Длина ключа от 8 байт. Алгоритм шифрования SHA1.
2. Для авторизации партнер отправляет POST запрос, используя цифровую подпись signature и уникальный идентификатор магазина store_id.
3. Примеры URL запросов можно посмотреть в разделе Методы API.

Формирования цифровой подписи

Алгоритм формирования цифровой подписи

require 'digest/sha1'
secret_key = '9fff8c602b08b00323567be0001480f6'
data = "{\"order_id\": \"FACTPRECHR152632\", \"amount\": \"8300.00\"}"
SIGNATURE = Digest::SHA1.hexdigest(data + secret_key)

Результатом шифрования в примере выше будет являться строка "cbfb21630cd585f59c3a50fc3365d8c26b97cd4e".

import java.io.UnsupportedEncodingException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Formatter;

public class Main {

    static String secret_key = "098f6bcd4621d373cade4e832627b4f6"; // Это пример
    static String data = "{\"callback_url\":\"https://shop.ru/revo/decision\",
      \"redirect_url\":\"https://shop.ru/revo/redirect\",
      \"current_order\":
        {\"amount\":\"7500.00\",
          \"order_id\":\"R001233\"},
           \"primary_phone\":\"9268180621\"}";

    public static void main(String[] args) {

        String signature = encryptPassword(data + secret_key); // Тут всегда будет 40 символов по SHA1
        System.out.println(signature);
    }

    private static String encryptPassword(String password) {
        String sha1 = "";
        try {
            MessageDigest crypt = MessageDigest.getInstance("SHA-1");
            crypt.reset();
            crypt.update(password.getBytes("UTF-8"));
            sha1 = byteToHex(crypt.digest());
        } catch(NoSuchAlgorithmException e) {
            e.printStackTrace();
        } catch(UnsupportedEncodingException e) {
            e.printStackTrace();
        }
        return sha1;
    }

    private static String byteToHex(final byte[] hash) {
        Formatter formatter = new Formatter();
        for (byte b : hash) {
            formatter.format("%02x", b);
        }
        String result = formatter.toString();
        formatter.close();
        return result;
    }
}

Тело json запроса экранируется (ставится \ перед символами " и \) и к строке data добавляется секретный ключ secret_key. К получившейся строке применяется алгоритм SHA1, в результате формируется цифровая подпись signature.

Схема взаимодействия

Расчёт доступной клиенту для оплаты частями суммы производится с помощью метода Registration, который возвращает ссылку на iFrame Мокка. Клиент проходит процедуру регистрации в iFrame Мокка, после чего в callback передаётся информация о результате: одобрение или отказ в лимите (доступной для оплаты частями сумме).

Оформление покупки совершается аналогичным образом с помощью метода Checkout, который возвращает ссылку на iFrame Мокка, но уже с большим числом шагов. После регистрации (или авторизации) клиента, появляется шаг с выбором графика платежей. После оформления клиентом заказа денежные средства блокируются на счете клиента, заявка переводится в статус hold, решение по клиенту и сумма также возвращается в callback.

Для окончательного оформления и подтверждения заявки необходимо ее финализировать с помощью метода Finish. Принципиальная схема процесса представлена на диаграмме справа.

Методы API

Registration

POST BASE_URL/factoring/v1/limit/auth?store_id=STORE_ID&signature=SIGNATURE

Метод возвращает ссылку на iFrame для получения лимита. По завершению формы на адрес указанный в callback_url отправляется json ответ с результатом решения по лимиту клиента.

В зависимости от информации, которая есть о пользователе в системе Мокка, форма будет иметь различное число шагов (для этого нужно передавать primary_phone) - см. подробнее Описание iFrame Мокка.

Parameters

Пример запроса в формате json

{
  "callback_url": "https://shop.ru/revo/decision",
  "redirect_url": "https://shop.ru/revo/redirect",
  "autorized_client": true,
  "primary_phone": "9998887766",
  "primary_email": "user@example.com",
  "skip_result_page": "user@true.com",
  "current_order":
  {
    "order_id": "119R"
  },
  "person":
  {
    "first_name": "Иван",
    "surname": "Иванов",
    "patronymic": "Иванович",
    "birth_date": "15.01.1975"
  },
    "additional_data":
  {
    "previous_url": "https://revo.ru/where-to-buy",
    "returning_customer": true,
    "bank_card": true,
    "last_orders": 2,
    "sum_orders": 61000.00,    
    "client":
    {
        "client_id": "541USR",
        "registration_date": "11.11.2021",
        "data_change_date": "15.11.2021",
        "purchases_value": 2,
        "purchases_sum": 61000.00,
        "first_purchase_date": "11.11.2021",
        "last_purchase_date": "11.11.2021",
        "uniq_user_phone": 1
    },
    "purchase":
        [{
          "product_name": "Смартфон Honor x39",
          "number": 1,
          "product_price": 10000.00
        }]
  }
}

	callback_url string		URL для ответа от Мокка по решению для клиента.
	redirect_url string		URL для редиректа после нажатия на кнопку/ссылку в форме Мокка "Вернуться в интернет магазин".
	authorized_client string		Флаг, который отображает статус авторизации клиента в личном кабинете партнера.
	primary_phone string		Номер телефона клиента из личного кабинета партнера (Без кода страны).
	primary_email string		Почта клиента из личного кабинета партнера.
	current_order object		Объект, содержащий информацию о текущем заказе.
	order_id string			Уникальный ID. Для создания заявки.
	person object		Объект, содержащий информацию о клиенте из личного кабинета партнера.
	first_name string			Имя клиента.
	surname string			Фамилия клиента.
	patronymic string, optional			Отчество клиента.
	birth_date string, optional			Дата рождения клиента в формате dd.mm.yyyy.
	additional_data object		Объект, содержащий дополнительную информацию.
	previous_url string			Адрес, откуда клиент зашёл на сайт партнёра.
	returning_customer bool			Является ли клиент повторным для партнёра.
	bank_card bool			Флаг показывающий была ли оплата банковской картой у клиента за последние 24 мес.
	last_orders integer			Количество всех заказов клиента за последние 24 мес.
	sum_orders float			Сумма всех заказов клиента за последние 24 мес.
	client object		Объект, содержащий дополнительную информацию о клиенте.
	client_id string			Идентификатор клиента.
	registration_date string			Дата регистрации клиента в формате дд.мм.гггг.
	data_change_date string			Дата последнего изменения данных клиента (ФИО, дата рождения, документ) в формате дд.мм.гггг.
	purchases_value integer			Количество завершенных заказов клиента за последние 24 мес.
	purchases_sum float			Сумма завершенных заказов клиента за последние 24 мес.
	first_purchase_date string			Дата первой покупки клиента в формате дд.мм.гггг.
	last_purchase_date string			Дата последней покупки клиента в формате дд.мм.гггг.
	uniq_user_phone string			Кол-во пользователей зарегистрированных с primary_phone на сайте партнера.
	purchase array		Объект, содержащий массив с информацией о 5 последних заказах клиента.
	product_name string			Наименование позиции.
	number integer			Количество.
	product_price float			Стоимость единицы товара.

Response Parameters

Пример ответа для успешной аутентификации.

{
  "status": 0,
  "message": "Payload valid",
  "iframe_url": "https://r.revoup.ru/form/v1/af45ef12f4233f"
}

status integer	Код ответа.
message string	Короткое текстовое описание ответа.
iframe_url string	Cсылка на сгенерированный iFrame.

callback parameters

Пример callback-а при успешном завершении формы:

{
  "order_id": "32423",
  "decision": "approved",
  "amount": 5000.00,
  "mobile_phone": "89262341793",
  "email": "ivan@gmail.com"
}

order_id string	Уникальный номер заказа. Не более 255 символов.
decision string	Решение по выдаче рассрочки. При положительном решении - значение approved (заявка ожидает финализации). При отрицательном решении - declined.
amount float	Сумма в рублях.
mobile_phone string	Номер телефона клиента (Без кода страны).
email string	Email клиента.

Упрощенный вызов формы регистрации клиента

Данный способ позволяет напрямую по ссылке вызывать iframe для регистрации клиента.

Ссылка для вызова формы: https://{BASE_URL}/iframe/v2/limit_form/{uid}

• BASE_URL можно посмотреть в разделе Авторизация > Базовые URL адреса
• В разделе Представление на сайте > Вызов iframe можно посмотреть, как вызывать форму в pop-up
• В UID указывается идентификатор партнера, который предоставляет Мокка

Limit

POST BASE_URL/api/external/v1/client/limit?store_id=STORE_ID&signature=SIGNATURE

Метод для получения суммы лимита клиента по номеру его телефона. Для новых клиентов получить информацию о лимите только по номеру телефона нельзя.

Parameters

Пример запроса в формате json

{
  "client":
  {
    "mobile_phone": "9031234567"
  }
}

client object	Объект, содержащий информацию о клиенте.
mobile_phone string	Номер телефона клиента (Без кода страны).

Response Parameters

Пример ответа, когда клиент найден в базе

{
  "meta":
  {
    "status": 0,
    "message": "Payload valid"
  },
  "client":
  {
    "mobile_phone": "9031234567",
    "limit_amount": "9500.00",
    "status": "active"
  }
}

Пример ответа, когда клиент найден в базе, но выдача займа невозможна

{
  "meta":
  {
    "status": 0,
    "message": "Payload valid"
  },
  "client":
  {
    "mobile_phone": "9031234567",
    "limit_amount": "6700.00",
    "status": "inactive"
  }
}

Пример ответа, когда клиент не найден в базе

{
  "meta":
  {
    "status": 0,
    "message": "Payload valid"
  },
  "client":
  {
    "mobile_phone": "9031234567",
    "limit_amount": "0.00",
    "status": "new"
  }
}

	status integer		Код ответа.
	message string		Короткое текстовое описание ответа.
	client object		Объект, содержащий информацию о клиенте.
	mobile_phone string			Номер телефона клиента (Без кода страны).
	limit_amount string			Лимит средств, доступных клиенту, в рублях.
	status string			Статус пользователя. Возможные значения: active - пользователю доступна услуга оплаты частями на сумму limit_amount; inactive - пользователю не доступна услуга оплаты частями; new - новый пользователь, которому доступна услуга оплаты частями на сумму limit_amount.

Checkout

POST BASE_URL/factoring/v1/precheck/auth?store_id=STORE_ID&signature=SIGNATURE

Метод возвращает ссылку на iFrame для оформления заказа клиента. По завершению формы на адрес указанный в callback_url отправляется json ответ с результатом оформления. В случае успешного оформления, средства в размере amount холдируются на счёте клиента в системе Мокка.

В зависимости от информации, которая есть о пользователе в системе Мокка, форма будет иметь различное число шагов (для этого нужно передавать primary_phone) - см. Описание iFrame Мокка.

Для бизнес-моделей, где клиенту необходимо осуществлять предоплату, метод поддерживает 2 способа предоплаты:

• Если предоплата осуществлена до вызова iFrame, то информацию о ней необходимо передавать в prepayment_amount.

• Если предоплата должна быть осуществлена после вызова iFrame, то производится соответствующая настройка на стороне Мокка. При этом следует параметр skip_result_page выставлять как true и передавать в redirect_url адрес страницы предоплаты, на которую будет перенаправлен клиент по завершению оформления в iFrame.

Parameters

Пример запроса в формате json

{
  "callback_url": "https://shop.ru/revo/decision",
  "checkout_url": "https://shop.example.com/revo/checkout",
  "redirect_url": "https://shop.ru/revo/redirect",
  "autorized_client": true,
  "primary_phone": "9998887766",
  "primary_email": "user@example.com",
  "skip_result_page": true,
  "current_order":
  {
    "order_id": "120R",
    "tax_amount": 0.00,
    "discount_amount": 0.00,
    "amount": 51000.00,
    "prepayment_amount": 1000.00,
    "term": 2,
    "valid_till": "21.07.2024 12:08:01+03:00"
  },
  "person":
  {
    "first_name": "Иван",
    "surname": "Иванов",
    "patronymic": "Иванович",
    "birth_date": "15.01.1975"
  },
  "cart_items":
  [{
    "SKU": "540R",
    "name": "Samsung Note 8",
    "price": 48000.00,
    "tax_price": 0.00,
    "quantity": 1,
    "quantity_unit": "pcs",
    "category": "Phone"
  },
  {
    "SKU": "440C",
    "name": "Чехол фирменный",
    "price": 3000.00,
    "tax_price": 0.00,
    "quantity": 1,
    "quantity_unit": "pcs",
    "category": "Accessories"
  }],
  "delivery_info":
  {
    "first_name": "Юрий",
    "surname": "Гагарин",
    "patronymic": "Алексеевич",
    "phone": "9651045566",
    "email": "receiver@example.com",    
    "type": "Pickpoint",
    "address": "ул. Ленина, д.1"
  },
  "additional_data":
  {
    "previous_url": "https://revo.ru/where-to-buy",
    "returning_customer": true,
    "bank_card": true,
    "last_orders": 2,
    "sum_orders": 61000.00,
    "same_address": true,    
    "client":
    {
        "first_name": "Иван",
        "surname": "Иванов",
        "patronymic": "Иванович",
        "phone": "9998887766",
        "email": "user@example.com",
        "client_id": "541USR",
        "registration_date": "11.11.2021",
        "data_change_date": "15.11.2021",
        "purchases_value": 2,
        "purchases_sum": 61000.00,
        "first_purchase_date": "11.11.2021",
        "last_purchase_date": "11.11.2021",
        "uniq_user_phone": 1
    },
    "purchase":
        [{
          "product_name": "Смартфон Honor x39",
          "number": 1,
          "product_price": 10000.00
        }]
  }
}

	callback_url string		URL для ответа от Мокка по решению для клиента.
	checkout_url string		URL для редиректа в случае если клиенту было отказано.
	redirect_url string		URL для редиректа после нажатия на кнопку/ссылку в форме Мокка "Вернуться в интернет магазин".
	authorized_client bool		Флаг, который отображает статус авторизации клиента в личном кабинете партнера.
	primary_phone string		Номер телефона клиента из личного кабинета партнера (Без кода страны).
	primary_email string		Почта клиента из личного кабинета партнера.
	skip_result_page bool, optional		Флаг, который отображает требуется ли клиенту отобразить результат прохождения оформления.
	current_order object		Объект, содержащий информацию о текущем заказе.
	order_id string			Уникальный номер заказа. Не более 255 символов.
	amount float			Сумма заказа в рублях.
	tax_amount float			Сумма налогов по заказу в рублях.
	discount_amount float			Скидка по заказу в рублях.
	prepayment_amount float, optional			Сумма внесённой клиентом предоплаты в рублях.
	term integer, optional			Срок рассрочки в месяцах.
	valid_till String, optional			Срок, в течении которого заказ считается актуальным -срок холдирования средств. По истечении срока заказ отменяется. Формат: dd.mm.yyyy hh:mm:ss+hh:mm, где после "+" указывается часовой пояс относительно GMT. По умолчанию - 24 часа.
	person object		Объект, содержащий информацию о клиенте из личного кабинета партнера.
	first_name string			Имя клиента.
	surname string			Фамилия клиента.
	patronymic string, optional			Отчество клиента.
	birth_date string, optional			Дата рождения клиента в формате dd.mm.yyyy.
	cart_items object		Объект, содержащий массив с информацией о текущем заказе.
	sku string			Уникальный идентификатор товара.
	name string			Наименование товара.
	price float			Цена товара.
	tax_price float			Сумма налогов по товару.
	quantity integer			Количество товара.
	quantity_unit string			В чем измеряются единицы товара.
	category string			Категория товара.
	delivery_info object		Объект, содержащий информацию о доставке текущего заказа.
	first_name string			Имя получателя.
	surname string			Фамилия получателя.
	patronymic string, optional			Отчество получателя.
	phone string			Номер телефона клиента (без кода страны).
	email string, optional			Email клиента.
	type string			Способ доставки.
	address string			Адрес доставки.
	additional_data object		Объект, содержащий дополнительную информацию.
	previous_url string			Адрес, откуда клиент зашёл на сайт партнёра.
	returning_customer bool			Является ли клиент повторным для партнёра.
	bank_card bool			Флаг показывающий была ли оплата банковской картой у клиента за последние 24 мес.
	last_orders integer			Количество всех заказов клиента за последние 24 мес.
	sum_orders float			Сумма всех заказов клиента за последние 24 мес.
	same_address bool			Совпадает ли текущий адрес доставки с предыдущим адресом доставки.
	client object		Объект, содержащий дополнительную информацию о клиенте.
	first_name string			Имя клиента на этапе оформления заказа.
	surname sring			Фамилия клиента на этапе оформления заказа.
	patronymic string, optional			Отчество клиента на этапе оформления заказа.
	phone string			Номер телефона клиента на этапе оформления заказа (Без кода страны).
	email string			Email клиента на этапе оформления заказа.
	client_id string			Идентификатор клиента.
	registration_date string			Дата регистрации клиента в формате дд.мм.гггг.
	data_change_date string			Дата последнего изменения данных клиента (ФИО, дата рождения, документ) в формате дд.мм.гггг.
	purchases_value integer			Количество завершенных заказов клиента за последние 24 мес.
	purchases_sum float			Сумма завершенных заказов клиента за последние 24 мес.
	first_purchase_date string			Дата первой покупки клиента в формате дд.мм.гггг.
	last_purchase_date string			Дата последней покупки клиента в формате дд.мм.гггг.
	uniq_user_phone string			Кол-во пользователей зарегистрированных с primary_phone на сайте партнера.
	purchase array		Объект, содержащий массив с информацией о 5 последних заказах клиента.
	product_name string			Наименование позиции.
	number integer			Количество.
	product_price float			Стоимость единицы товара.

Response Parameters

Пример ответа при успешной аутентификации.

{
  "status": 0,
  "message": "Payload valid",
  "iframe_url": "https://revo.ru/factoring/v1/form/6976174c5b6a1bb089d15b80e0a6afc62d4283fe"
}

status integer	Код ответа.
message string	Короткое текстовое описание ответа.
iframe_url string	Cсылка на сгенерированный iFrame.

Callback parameters

Пример callback-а при успешном оформлении товара:

{
  "order_id": "R107356",
  "decision": "approved",
  "amount": 6700.00,
  "prepayment_amount": 1000.00,
  "total_amount": 7700.00,
  "term": 3,
  "client":
  {
    "primary_phone": "8880010203"
    "email": "ivan@gmail.com",
    "full_name": "Иванов Иван Иванович",
    "first_name": "Иван",
    "surname": "Иванов",
    "patronymic": "Иванович"
  },
  "schedule":
  [{
    "date": "01.01.2018",
    "amount": 2933.33
  },
  {
    "date": "01.02.2018",
    "amount": 2933.33
  },
  {
    "date": "01.03.2018",
    "amount": 2933.33
  }]
}

	order_id string		Уникальный номер заказа. Не более 255 символов.
	decision string		Решение по выдаче рассрочки. При положительном решении - значение approved. При отрицательном решении - declined.
	amount float		Сумма к оплате частями в рублях.
	prepayment_amount float, optional		Сумма предоплаты в рублях.
	total_amount float, optional		Полная сумма заказа, с учётом предоплаты.
	term integer		Срок рассрочки в месяцах.
	client object		Объект, содержащий информацию о клиенте.
	primary_phone string			Номер телефона клиента (без кода страны).
	primary_email string, optional			Email клиента.
	full_name string, optional			ФИО через пробел.
	first_name string, optional			Имя клиента.
	surname string, optional			Фамилия клиента.
	patronymic string, optional			Отчество клиента.
	schedule object		Объект, содержащий информацию о графике платежей.
	date string			Дата платежа в формате dd.mm.yyyy.
	amount float			Сумма платежа в рублях.
	monthly_overpayment float		Величина ежемесячной переплаты в рублях.

Schedule

POST BASE_URL/factoring/v1/schedule?store_id=STORE_ID&signature=SIGNATURE

Метод возвращает информацию о доступных графиках платежей для заданной суммы корзины amount. Если для указанной суммы нет ни одного подходящего тарифа, возвращается пустой массив.

Parameters

Пример запроса в формате json

{
  "amount": 5000.00
}

amount float	Сумма к оплате частями в рублях.

Response Parameters

Пример ответа, когда доступны два графика платежей: на 3 и 6 месяцев.

{
  "status": 0,
  "message": "Payload valid",
  "payment_schedule":
  [{
    "total": 7000.01,
    "monthly_payment": 2334,
    "monthly_overpayment": 666.67,
    "term": 3,
    "payment_dates":
    [{
      "date": "11.06.2018",
      "amount": 2334.00
    },
    {
      "date": "09.07.2018",
      "amount": 2334.00
    },
    {
      "date": "09.08.2018",
      "amount": 2332.01
    }]
  },
  {
    "total": 6500,
    "monthly_payment": 1100,
    "monthly_overpayment": 250,
    "term": 6,
    "payment_dates":
    [{
      "date": "11.06.2018",
      "amount": 1100.00
    },
    {
      "date": "09.07.2018",
      "amount": 1100.00
    },
    {
      "date": "09.08.2018",
      "amount": 1100.00
    },
    {
      "date": "10.09.2018",
      "amount": 1100.00
    },
    {
      "date": "09.10.2018",
      "amount": 1100.00
    },
    {
      "date": "09.11.2018",
      "amount": 1000.00
    }]
  }]
}

	message string			Короткое текстовое описание ответа.
	payment_schedule object			Массив объектов, содержащий информацию о предварительных графиках платежей.
	total float				Полная сумма рассрочки с учётом переплаты.
	monthly_payment float				Приблизительная величина ежемесячного платежа с учётом переплаты.
	monthly_overpayment float				Величина ежемесячной переплаты в рублях.
	term int				Срок рассрочки в месяцах.
	payment_dates object				Объект, содержащий информацию о графике платежей.
	date string					Дата платежа в формате dd.mm.yyyy.
	amount float					Сумма платежа в рублях.

Status

 POST BASE_URL/factoring/v1/status?store_id=STORE_ID&signature=SIGNATURE

Метод возвращает информацию по статусу заказа.

Parameters

Пример запроса в формате json

 {
   "order_id": "R107356"
 }

order_id string	Уникальный номер заказа. Не более 255 символов.

Response Parameters

Пример ответа, когда клиент прошел до конца оформление в Iframe и ожидает ответа по заказу от Партнера

{
  "status": 0,
  "message": "Payload valid",
  "current_order":
  {
    "order_id": "FACTPRECHR00004768",
    "expired": false,
    "status": "hold",
    "decision": "approved",
    "amount": 4999.00,
    "term": 3
  }
}

Пример ответа, когда клиент прошел до конца оформления в Iframe, но партнер отменил заказ

{
  "status": 0,
  "message": "Payload valid",
  "current_order":
  {
    "order_id": "FACTPRECHR00004768",
    "expired": true,
    "status": "canceled",
    "decision": "approved",
    "amount": 4999.00,
    "term": 3
  }
}

Пример ответа, когда клиент прошел до конца оформления в Iframe, партнер подтвердил заказ.

{
  "status": 0,
  "message": "Payload valid",
  "current_order":
  {
    "order_id": "FACTR00004755",
    "expired": false,
    "status": "finished",
    "decision": "approved",
    "amount": 1000.00,
    "term": 3
  }
}

Пример ответа, когда произошел отказ по политикам Мокка

{
  "status": 0,
  "message": "Payload valid",
  "current_order":
  {
    "order_id": "FACTPRECHR00004721",
    "expired": true,
    "status": "declined",
    "decision": "declined",
    "amount": 6498.00,
    "term": null
  }
}

Пример ответа, когда срок холдирования по заявке истёк. Заявка отменена.

{
  "status": 0,
  "message": "Payload valid",
  "current_order":
  {
    "order_id": "FACTPRECHR141531",
    "expired": true,
    "status": "expired",
    "decision": "approved",
    "amount": 9000.00,
    "term": 3
  }
}

Пример ответа, когда клиент успешно прошел оформление в iframe, партнер подтвердил заказ. Был произведен полный возврат.

{
  "status": 0,
  "message": "Payload valid",
  "current_order":
  {
    "order_id": "FACTPRECHR00004714",
    "expired": true,
    "status": "refunded",
    "decision": "approved",
    "amount": 734.51,
    "term": 3
  }
}

	status integer		Код ответа.
	message string		Короткое текстовое описание ответа.
	current_order object		Объект, содержащий информацию о заказе.
	order_id string			Уникальный номер заказа. Не более 255 символов.
	expired bool			Флаг, отображающий статус актуальности заказа (холдирования средств). Для актуальных заказов - false. Становится true при наступлении срока valid_till.
	status string			Информация по статусу заказа. Возможные значения: pending, hold, finished, canceled, declined, refunded.
	decision string			Информация по статусу лимита. Если лимит одобрен - approved. Если в лимите отказано - declined.
	amount float			Сумма, оформленная клиентом для оплаты частями, в рублях.
	term integer			Срок рассрочки в месяцах.

Status and Decision values

Decision	Status	Description
null	pending	Клиент не авторизовался в процессе оформления в форме. Решения о лимите не принято.
approved	pending	Клиент ввел персональные данные и подтвердил номер, но не выбрал срок и не закончил процесс оформления.
approved	hold	Лимит одобрен, средства захолдированы, ожидается финализация заказа.
approved	finished	Заказ финализирован. При последующем изменении expired, либо при частичном возврате значение status не поменяется.
approved	canceled	Заказ отменен. При последующем изменении expired значение status не поменяется.
approved	expired	Лимит одобрен, срок холдирования по заказу истёк.
approved	refunded	Был произведен полный возврат средств по заказу. При частичном возврате status останется finished.
approved	declined	Лимит одобрен, услуга оплаты частями не доступна клиенту (например, сумма заказа превышает лимит).
declined	declined	В лимите отказано по политикам Мокка.

Change

POST BASE_URL/factoring/v1/precheck/change?store_id=STORE_ID&signature=SIGNATURE

Метод для изменения суммы уже созданного заказа.

Parameters

Пример запроса в формате json

{
  "order_id": "120R",
  "amount": "45000.00",
  "valid_till": "29.07.2018 12:08:01+03:00",
  "cart_items":
  [{
    "sku": "540R",
    "name": "Samsung Note 8",
    "price": 45000.00,
    "quantity": 1
  }]
}

	order_id string		Уникальный номер заказа. Не более 255 символов.
	sku string			Уникальный идентификатор товара.
	amount float		Сумма в рублях.
	valid_till String, optional		Срок, в течении которого заказ считается актуальным (срок холдирования средств). По истечении срока заказ отменяется. Формат: dd.mm.yyyy hh:mm:ss+hh:mm, где после "+" указывается часовой пояс относительно GMT. По умолчанию - 24 часа.
	cart_items object		Объект, содержащий массив с информацией о заказе.
	name string			Наименование товара.
	price float			Цена товара.
	quantity integer			Количество товара.

Response parameters

Пример ответа при успешном изменении заказа:

{
  "status": 0,
  "message": "Payload valid",
  "schedule":
  [{
    "date": "01.01.2018",
    "amount": 2933.33
  },
  {
    "date": "01.02.2018",
    "amount": 2933.33
  },
  {
    "date": "01.03.2018",
    "amount": 2933.33
  }]
}

	status integer		Код ответа.
	message string		Короткое текстовое описание ответа.
	schedule object		Объект, содержащий информацию о графике платежей.
	date string			Дата платежа в формате dd.mm.yyyy.
	amount float			Сумма платежа в рублях.

Cancel

POST BASE_URL/factoring/v1/precheck/cancel?store_id=STORE_ID&signature=SIGNATURE

Метод для отмены заказа. При отмене у клиента разблокируются ранее захолдированные средства.

Parameters

Пример запроса в формате json

{
  "order_id": "R107356"
}

order_id string	Уникальный номер заказа. Не более 255 символов.

Response Parameters

Пример ответа, когда заявка успешно отменена

{
  "status": 0,
  "message": "Payload valid"
}

status integer	Код ответа.
message string	Короткое текстовое описание ответа.

Finish

POST BASE_URL/factoring/v1/precheck/finish?store_id=STORE_ID&signature=SIGNATURE

Метод для финализации заказа путём передачи договора купли-продажи на обслуживание в Мокка. Запрос должен быть отправлен c типом содержимого multipart/form-data. В запросе должны быть указаны два ключа. Первый ключ с названием body, в котором должно быть указано тело json запроса. Второй ключ с названием check, где прикладывается файл(фискальный документ). Signature формируется по основному принципу, без второго ключа.

Parameters

Пример запроса в формате json

{
  "order_id": "R107356",
  "amount": 6700.00,
  "check_number": "ZDDS3123F"
  "check_link": "https://consumer.1-ofd.ru/example_link"
}

order_id string	Уникальный номер заказа. Не более 255 символов.
amount float	Сумма в рублях.
check_number string	Номер фискального документа в системе партнёра (например, номер чека).
check_link string	Ссылка на чек на платформе ОФД

Response Parameters

Пример ответа, когда файл успешно подгружен

{
  "status": 0,
  "message": "Payload valid"
}

status integer	Код ответа.
message string	Короткое текстовое описание ответа.

Return

POST BASE_URL/factoring/v1/return?store_id=STORE_ID&signature=SIGNATURE

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

Parameters

Пример запроса в формате json

{
  "order_id": "R001233",
  "amount": 2010.00
}

order_id string	Уникальный номер заказа. Не более 255 символов.
amount float	Сумма возврата в рублях. Возврат может быть как полным, так и частичным.

Response Parameters

Пример ответа при успешной обработке запроса на возврат

{
  "status": 0,
  "message": "Payload valid"
}

Пример ответа при неуспешной обработке запроса на возврат

{
  "status": 10,
  "message": "JSON decode error"
}

status integer	Код ответа.
message string	Короткое текстовое описание ответа.

Коды ошибок

Код	Сообщение	Комментарии
0	Payload valid	Всё ок.
10	JSON decode error	Некорректный json запрос.
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.

Тестирование и отладка

Тестирование и отладка интеграции производятся на demo сервере (https://backend.demo.revoup.ru). При заполнении номера телефона в анкете рекомендуется использовать несуществующий префикс оператора 888, чтобы sms сообщения не отправлялись реальным людям. На production сервере использовать такой префикс нельзя.

Все коды подтверждения и пин-коды 1111.

• Для получения отказ при использовании Registration необходимо указать телефон, начинающийся с 88821.

• Для получения одобрения при использовании Registration необходимо указать телефон, начинающийся с 888, кроме 88821.

• Для тестирования на production сервере код задаётся в настройках магазина партнёра. Например, это может быть 7777, вместо 1111.

• В анкете идет проверка по ФИО + дате рождения или номеру паспорта на совпадение с существующим клиентом, поэтому при тестировании необходимо вводить различные данные в эти поля.

Описание iFrame Мокка

Регистрация клиента

1-2. Заполнение анкеты.
3. Переход на экран подтверждения номера телефона кодом из смс-сообщения.
3.1 Если клиент допустил ошибку при вводе телефона, то возможен переход на шаг с вводом номера телефона.
4.1 После ввода корректного смс кода происходит отображение окна с результатом "Оформление прошло успешно" и информацией о доступном лимите.
4.2 Либо отображение окна с результатом "К сожалению, 'Оплата частями' Вам недоступна".

При вызове iframe Мокка на первом экране (1) отображены поля для ввода персональных данных:

• Фамилия
• Имя
• Отчество
• Дата Рождения
• Номер мобильного телефона
• Email
• Серия и Номер паспорта

Валидация:

• Фамилия, Имя, Отчество - принимаются данные только в кириллице. Тип данных string.
• Дата рождения - задаётся в формате dd.mm.yyyy, тип данных date.
• Номер мобильного телефона - необходимо вводить в 10-значном формате, например (888)1231212. Тип данных string.
• Email - поле для ввода email, тип данных string.
• Серия и номер паспорта - длина должна быть ровно 10 символов, тип данных string.

Авторизация клиента

1. Нажатие кнопки "Войти" на первой странице формы.
   2.1 Ввод мобильного номера и Нажатие кнопки "Отправить СМС".
   2.2 Если мобильный номер не существует в базе Мокка, клиент переходит на окно с информационным сообщением "С указанным номером телефона мы Вас не нашли". Нажатие на кнопку "Оформить за 1 минуту" приводит к переходу на первый шаг формы.
   3.1 Если мобильный номер существует в базе Мокка, клиент переходит на экран Подтверждение мобильного номера кодом из смс-сообщения.
   3.2 Если клиент допустил ошибку при вводе телефона, то возможен переход на шаг с вводом номера телефона.
   4.1 После ввода корректного смс кода происходит отображение окна результата с информацией "Оформление прошло успешно" и информацией о доступном лимите.
   4.2 Либо отображение окна результата с информацией "К сожалению, 'Оплата частями' Вам недоступна".
   

По нажатию на кнопку FAQ в правом верхнем углу формы открывается список с ответами на часто задаваемые вопросы.

Оформление покупки

1. Заполнение анкеты.
   2.1 Переход на экран подтверждения номера телефона кодом из смс-сообщения.
   2.2 Если клиент допустил ошибку при вводе телефона, то возможен переход на шаг с вводом номера телефона.
   3.1 Если для оформления заказа не требуется предоплата, то идёт переход на экран, где клиенту необходимо выбрать один из возможных для данной суммы заказа периодов оплаты.
   3.2 Если для оформления заказа клиенту необходимо внести предоплату, то идёт переход на экран, где клиенту необходимо выбрать один из возможных для данной суммы заказа периодов оплаты, а также указать желаемую величину предоплаты.
   4.1 После успешного оформления заказа без предоплаты происходит отображение окна результата с информацией "Оформление прошло успешно" и кнопкой для возврата в магазин.
   4.2 Либо отображение окна результата с информацией "К сожалению, 'Оплата частями' Вам недоступна".
   4.3 После успешного оформления заказа с предоплатой происходит отображение окна результата с информацией "Оформление прошло успешно" и кнопкой для перехода к оплате картой.
   4.4 Либо отображение окна результата с информацией "К сожалению, 'Оплата частями' Вам недоступна".
   

Представление на сайте

Рекомендации по представлению услуги Оплата частями на партнёрском сайте представлены в презентации. Ниже приведены инструкции по реализации отдельных элементов Мокка из презентации.

Вызов iFrame

REVO.Form.show(iframe_url, target_selector);

По нажатию на кнопки "Оформить за 1 минуту", "?" справа от надписи "или 150 Р/мес" и "Оплата" при выбранном способе "Оплата частями" необходимо вызвать iFrame Мокка для регистрации и оформления заказа, соответственно. Для этого нужно получить с помощью метода Registration или Checkout ссылку на iFrame и передать её в js метод плагина Мокка.

iframe_url – адрес открываемого iFrame, обязательный параметр. target_selector – селектор элемента, внутрь которого должен быть вставлен iFrame.

Далее работает предоставленный Мокка плагин js (реализован в виде модуля Мокка), который вставляет <iframe src= iframe_url /> и производит манипуляции с этим iFrame.

Плагин доступен по адресу: https://{BASE_URI}/javascripts/iframe/v2/revoiframe.js и его можно добавить на страницу интернет магазина.

<script src="https://{BASE_URI}/javascripts/iframe/v2/revoiframe.js"></script>

Также данный плагин предоставляет возможность получения событий: закрытия формы - onClose, загрузки формы - onLoad и принятия решения по заявке - onResult.

REVO.Form.onClose(function () { alert('closed'); });
REVO.Form.onLoad(function () { console.log('frame loaded'); });
REVO.Form.onResult(function() { console.log('result'); });

Отображение доступного лимита

Если клиент уже прошёл регистрацию и получил лимит, то доступные ему для Оплаты частями средства можно отображать с помощью метода Limit.

Тестирование и отладка

Тестовые Параметры

Тестовые мобильные номера для ввода в iframe:

8881ХХХХXX - одобрено всё (второе оформление = повторная заявка)

88821ХХХХХ - отказано полностью

88822ХХХХХ - одобрены только займ

Код для подтверждения номера телефона - 1111

Инструкции для тестирования

Подробное описание вызова формы для регистрации клиента.

Пример формирования signature на ruby:

data = {
"callback_url": "https://shop.ru/revo/decision",
"redirect_url": "https://shop.ru/revo/redirect",
"primary_phone": "9268180621",
"primary_email": "ivan@gmail.com",
"current_order":
{
 "order_id": "R001233"
}}
 => {:callback_url=>"https://shop.ru/revo/decision",
  :redirect_url=>"https://shop.ru/revo/redirect", 
 :primary_phone=>"9268180621",
  :primary_email=>"ivan@gmail.com",
 :current_order=>{:order_id=>"R001233"}}

 data = data.to_json
 => "{\"callback_url\":\"https://shop.ru/revo/decision\",
 \"redirect_url\":\"https://shop.ru/revo/redirect\",
 \"primary_phone\":\"9268180621\",
 \"primary_email\":\"ivan@gmail.com\",
 \"current_order\":{\"order_id\":\"R001233\"}}"

 secret_key = "9fff8c602b08b00323567be0001480f6"

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

puts data
{
  "callback_url": "https://shop.ru/revo/decision",
  "redirect_url": "https://shop.ru/revo/redirect",
  "primary_phone": "9268180621",
  "primary_email": "ivan@gmail.com",
  "current_order": {
    "order_id": "R001233"
  }
}

Для вызова формы используется метод registration.

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

Необходимые параметры для вызова формы:

• базовый URL сервиса для тестирования и отладки
• store_id
• signature

Описание формирования запроса на получение ссылки вызова iframe:

• В переменную data вводится тело json запроса
• Переводим data в json формат
• В переменную secret_key вводим наименование ключа
• В переменную signature формируем подпись
• Выводим тело json запроса через команду puts для отправки запроса через клиент

Данные для отправки запроса в REST CLIENT:

Используется POST URL: https://backend.demo.revoup.ru/factoring/v1/limit/auth?store_id=72 &signature=347e8cff27d30b5200c8b32def4365ebbf4270d0

Тело JSON: { "callback_url": "https: //shop.ru/revo/decision", "redirect_url": "https: //shop.ru/revo/redirect", "primary_phone": "9268180621", "primary_email": "ivan@gmail.com", "current_order": { "order_id": "R001233" } }

Подробное описание отправки запроса на финализацию заказа

Пример формирования signature на ruby:

data = {order_id: "FACTPRECHR00005384", amount: 4999.0, check_number: "sdfhk"}
 => {:order_id=>"FACTPRECHR00005384", :amount=>4999.0, :check_number=>"sdfhk"}
data = data.to_json
 => "{\"order_id\":\"FACTPRECHR00005384\",\"amount\":4999.0,\"check_number\":\"sdfhk\"}"
secret_key = "9fff8c602b08b00323567be0001480f6"
 => "9fff8c602b08b00323567be0001480f6"
signature = Digest::SHA1.hexdigest(data + secret_key)
 => "70189f8a4f413fcb01c8933cae50f4341fe8fdee"
2.3.3 :012 > puts data
{"order_id":"FACTPRECHR00005384","amount":4999.0,"check_number":"sdfhk"}

Пример запроса через REST клиент POSTMAN:

Для финализации заказа используется метод finish

Необходимые параметры для финализации заказа:

• базовый URL для тестирования и отладки
• store_id
• signature

Описание формирования запрос на финализацию заказа:

• В переменную data вводится тело json запроса
• Переводим data в json формат
• В переменную secret_key вводим наименование ключа
• В переменную signature формируем подпись
• Выводим тело json запроса через команду puts для отправки запроса через клиент

Данные для отправки запроса в REST CLIENT:

Используется POST URL: https: //backend.demo.revoup.ru/factoring/v1/precheck/finish?store_id=72 &signature=70189f8a4f413fcb01c8933cae50f4341fe8fdee

Тело JSON с key = body: { "order_id": "FACTPRECHR00005384", "amount": 5000.0, "check_number": "454RCP" }

Приложение фискального документа с key = check.

Кейсы для тестирования

1. Новый клиент проходит форму регистрации и получает одобрение

Шаги	Ожидаемый результат	Статус по заявке
Отправить запрос с помощью метода auth	Получить ссылку на вызов iframe
Вызов iframe_url	Отображение iframe формы с вводом персональных данных
Ввод несуществующих в базе данных и нажатие кнопки «Оформить»	Переход на этап подтверждения СМС-кодом
Нажатие на кнопку «Подтвердить»	Отображение экрана результата с информацией об одобренном лимите

2. Новый клиент проходит форму регистрации и получает отказ

Шаги	Ожидаемый результат	Статус по заявке
Отправить запрос с помощью метода auth	Получить ссылку на вызов iframe
Вызов iframe_url	Отображение iframe формы с вводом персональных данных
Ввод несуществующих в базе данных и нажатие кнопки «Оформить»	Переход на этап подтверждения СМС-кодом
Нажатие на кнопку «Подтвердить»	Отображение экрана результата с информацией о недоступности услуги оплаты частями

3. Новый клиент в момент прохождения формы регистрации меняет номер на несуществующий в базе и получает решение

Шаги	Ожидаемый результат	Статус по заявке
Отправить запрос с помощью метода auth	Получить ссылку на вызов iframe
Вызов iframe_url	Отображение iframe формы с вводом персональных данных
Ввод несуществующих в базе данных и нажатие кнопки «Оформить»	Переход на этап подтверждения СМС-кодом
Нажатие кнопки изменения номера на экране подтверждения СМС-кодом	Переход на этап ввода номера телефона
Ввод несуществующего в базе номера и нажатие кнопки «Отправить SMS»	Переход на этап подтвержения СМС-кодом
Ввод кода подтверждения	Отображение экрана результата с информацией о решении

Особенности

Кейс 1

Логика взаимодействия ввода персональных данных при оформлении заказа в iframe

Кейс 1:

• Ввод в анкету существующего в базе Мокка ФИО + Дата рождения или Паспортные данные + Номер телефона, который не существует в базе Мокка.

Что происходит:

• Клиента переводит на окно с подтверждением кода из смс. Если клиент подтверждает код из смс, то происходит переход на окно с результатом. В результате отображается информационное сообщение о необходимости подтверждения данных клиента.

Кейс 2:

• Ввод существующего номера телефона и фио клиента. Ввод паспортных данных и даты рождения не соответствует данным клиента.

Что происходит:

• Клиента переводит на окно подтверждения кода из смс. Если клиент подтверждает код из смс, то происходит переход на окно с корзиной и графиком платежей. Далее переход на окно с результатом, где отображается информационное сообщение об успешном оформлении. (Подробнее в описание Оформление покупки)