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

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

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

    Авторизация

    Базовые 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 REVO.

    Parameters

    Пример запроса в формате 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"
      },
      "person":
      {
        "first_name": "Петр",
        "surname": "Чернышев",
        "patronymic": "Александрович",
        "birth_date": "15.01.1975"
      },
      "additional_data":
      {
        "previous_url": "https://revo.ru/where-to-buy",
        "channel": "mobile",
        "returning_customer": true,
        "bank_card": true,
        "last_orders": "3",
        "same_address": true
      }
    }
    
    callback_url
    string
    URL для ответа от Мокка по решению для клиента.
    redirect_url
    string
    URL для редиректа после нажатия на кнопку/ссылку в форме Мокка "Вернуться в интернет магазин".
    current_order
    object
    Объект, содержащий информацию о заказе.
    order_id
    string
    Уникальный номер заказа. Не более 255 символов. Можно использовать уникальную случайную строку.
    primary_phone
    string, optional
    Номер телефона клиента 10 цифр (без кода страны).
    primary_email
    string, optional
    Email клиента.
    person
    object, optional
    Объект, содержащий информацию о клиенте.
    first_name
    string, optional
    Имя клиента.
    surname
    sring, optional
    Фамилия клиента.
    patronymic
    string, optional
    Отчество клиента.
    birth_date
    object, optional
    Дата рождения клиента в формате dd.mm.yyyy.
    additional_data
    object, optional
    Объект для передачи дополнительной информации о клиенте.
    previous_url
    string, optional
    Адрес, откуда клиент зашёл на сайт партнёра.
    channel
    string, optional
    В каком канале открыта форма. Возможные значения: mobile, app, desktop.
    returning_customer
    bool, optional
    Является ли клиент повторным для партнёра.
    bank_card
    bool, optional
    Является ли последним способом оплаты банковская карта.
    last_orders
    string, optional
    Количество заказов за последние 6 мес.
    same_address
    bool, optional
    Совпадает ли текущий адрес доставки с предыдущим адресом доставки.

    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
    Номер телефона клиента 10 цифр (без кода страны).
    email
    string
    Email клиента.

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

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

    Ссылка для вызова формы: https://{BASE_URL}/iframe/v2/limit_form/{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
    Номер телефона клиента 10 цифр (без кода страны).

    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
    Номер телефона клиента 10 цифр (без кода страны).
    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 REVO.

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

    Parameters

    Пример запроса в формате 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",
        "valid_till": "21.07.2018 12:08:01+03:00",
        "term": 3,
        "amount": "59499.00",
        "prepayment_amount": "1000.00"
      },
      "person":
      {
        "first_name": "Петр",
        "surname": "Чернышев",
        "patronymic": "Александрович",
        "birth_date": "15.01.1975"
      },
      "cart_items":
      [{
        "sku": "1231",
        "name": "Samsung Note 8",
        "price": 55999,
        "quantity": 1,
        "unit": "шт.",
        "brand": "Samsung"
      },
      {
        "sku": "23543",
        "name": "Чехол фирменный",
        "price": 3500,
        "sale_price": 2999,
        "quantity": 1,
        "unit": "шт.",
        "brand" : "Samsung",
        "category": "Accessories"
      }],
      "skip_result_page": true,
      "delivery_info":
      {
        "first_name": "Петр",
        "surname": "Чернышев",
        "patronymic": "Александрович",
        "type": "Pickpoint",
        "address": "ул. Ленина, д.1",
        "phone": "9268180621",
        "email": "ivan@gmail.com"
      },
      "additional_data":
      {
        "previous_url": "https://revo.ru/where-to-buy",
        "channel": "mobile",
        "returning_customer": true,
        "bank_card": true,
        "last_orders": "3",
        "same_address": true
        "client":
        {
            "phone": "7909999999",
            "email": "revo@revo.ru",
            "client_id": "Daniel",
            "registration_date": "11.11.2021",
            "data_change_date": "11.11.2021",
            "purchases_volume": 3,
            "purchases_sum": 12999.0,
            "last_purchase_date": "11.11.2021",
            "first_purchase_date": "11.11.2021",
            "birthdate": "11.11.2021",
            "gender": "w",
        }
        "order":
        {
            "country": "RU",
            "currency": "rub",
            "order_price": 10000,
        }
        "delivery":
        {
            "delivery_kind": "store pick-up",
            "receiver_name": "Даниил Иванов",
            "delivery_address": "Варшавское шоссе, 9, 114115, Москва, Россия",
        }
        "purchase":
        {
            [
                {
                    "product_name": "Смартфон Honor x39",
                    "number": 1,
                    "product_price": 11500.0,
                    "category": "physical",
                    "breadcrumbs": "Electronics Store > Computers & Tablets > Smartphones",
                    "discount": "0%",
                    "global_product_ID": "XH39485858RU",
                    "vendor_product_ID": "XH39485858RU-0108",
                }
            ]
        }
      }
    }
    
    callback_url
    string
    URL для ответа от Мокка по решению для клиента.
    redirect_url
    string
    URL для редиректа после нажатия на кнопку/ссылку в форме Мокка "Вернуться в интернет магазин".
    current_order
    object
    Объект, содержащий информацию о заказе.
    order_id
    string
    Уникальный номер заказа. Не более 255 символов. Например, можно использовать нумерацию заказов в системе партнёра.
    valid_till
    String, optional
    Срок, в течении которого заказ считается актуальным (срок холдирования средств). По истечении срока заказ отменяется. Формат: dd.mm.yyyy hh:mm:ss+hh:mm, где после "+" указывается часовой пояс относительно GMT. По умолчанию - 24 часа.
    term
    integer, optional
    Срок рассрочки в месяцах.
    amount
    string
    Сумма заказа в рублях.
    prepayment_amount
    string, optional
    Сумма уже внесённой клиентом предоплаты в рублях.
    primary_phone
    string, optional
    Номер телефона клиента 10 цифр (без кода страны).
    primary_email
    string, optional
    Email клиента.
    person
    object, optional
    Объект, содержащий информацию о клиенте.
    first_name
    string, optional
    Имя клиента.
    surname
    sring, optional
    Фамилия клиента.
    patronymic
    string, optional
    Отчество клиента.
    birth_date
    string, optional
    Дата рождения клиента в формате dd.mm.yyyy.
    cart_items
    object, optional
    Объект, содержащий массив с информацией о заказе.
    sku
    string, optional
    Складская учётная единица (stock keeping unit).
    name
    string
    Наименование товара.
    price
    float
    Цена товара.
    sale_price
    float, optional
    Цена товара со скидкой (если есть).
    quantity
    integer, optional
    Количество товара.
    unit
    string, optional
    Единица измерения товара. Например, "шт.", "л.", "компл." и т.д.
    brand
    string, optional
    Бренд товара.
    category
    string, optional
    Категория товара.
    skip_result_page
    bool, optional
    Флаг, который определяет будет ли отображена страница с результатом оформления в iFrame. По умолчанию - false.
    true - по успешному завершению оформления сразу происходит редирект по redirect_url.
    false - по успешному завершению оформления будет отображено окно с результатом.
    delivery_info
    object, optional
    Объект для передачи массива с дополнительной информацией о заказе, которую клиент вводит на сайте партнёра (не в форме Мокка).
    first_name
    string, optional
    Имя клиента.
    surname
    sring, optional
    Фамилия клиента.
    patronymic
    string, optional
    Отчество клиента.
    type
    string, optional
    Способ доставки.
    address
    string, optional
    Адрес доставки.
    phone
    sring, optional
    Номер телефона клиента 10 цифр (без кода страны).
    email
    string, optional
    Email клиента.
    additional_data
    object, optional
    Объект для передачи дополнительной информации о клиенте.
    previous_url
    string, optional
    Адрес, откуда клиент зашёл на сайт партнёра.
    channel
    string, optional
    В каком канале открыта форма. Возможные значения: mobile, app, desktop.
    returning_customer
    bool, optional
    Является ли клиент повторным для партнёра.
    bank_card
    bool, optional
    Является ли последним способом оплаты банковская карта.
    last_orders
    string, optional
    Количество заказов за последние 6 мес.
    same_address
    bool, optional
    Совпадает ли текущий адрес доставки с предыдущим адресом доставки.
    client
    object, optional
    Объект для ввода дополнительной информации о клиенте.
    phone
    string, optional
    Номер телефона клиента.
    email
    string, optional
    Email клиента.
    client_id
    string, optional
    Имя или идентификатор клиента.
    registration_date
    string, optional
    Дата регистрации клиента в формате дд.мм.гггг.
    data_change_date
    string, optional
    Дата последнего изменения данных клиента в формате дд.мм.гггг.
    purchases_value
    integer, optional
    Число успешных покупок.
    purchases_sum
    float, optional
    Общая сумма успешных покупок за всё время.
    last_purchase_date
    string, optional
    Дата последней покупки клиента в формате дд.мм.гггг.
    first_purchase_date
    string, optional
    Дата первой покупки клиента в формате дд.мм.гггг.
    birthdate
    string, optional
    Дата рождения клиента в формате дд.мм.гггг.
    gender
    string, optional
    Пол клиента. Возможные значения: m, w.
    order
    object, optional
    Объект для ввода дополнительной информации о заказе.
    country
    string, optional
    Страна покупки.
    currency
    string, optional
    Валюта покупки.
    order_price
    float, optional
    Стоимость покупки.
    delivery
    object, optional
    Объект для ввода дополнительной информации о доставке.
    delivery_kind
    string, optional
    Способ доставки. Возможные значения: store pick-up, pick-up point, registered box, unregistered box courier shipping company
    receiver_name
    string, optional
    Имя и фамилия получателя.
    delivery_address
    string, optional
    Адрес доставки.
    purchase
    array, optional
    Массив объектов для ввода дополнительной информации о корзине.
    product_name
    string, optional
    Наименование позиции.
    number
    integer, optional
    Количество.
    product_price
    float, optional
    Стоимость SKU.
    category
    string, optional
    Категория товара. Возможные значения: physical, digital, gift_card, discount shipping_fee
    breadcrumbs
    string, optional
    Путь категории.
    discount
    string, optional
    Размер скидки в %.
    global_product_id
    string, optional
    Глобальный идентификатор продукта.
    vendor_product_id
    string, optional
    Идентификатор продукта вендора.

    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
    Номер телефона клиента 10 цифр (без кода страны).
    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.0,
        "term": 3
      }
    }
    

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

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

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

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

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

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

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

    {
      "status": 0,
      "message": "Payload valid",
      "current_order":
      {
        "order_id": "FACTPRECHR141531",
        "expired": true,
        "status": "expired",
        "decision": "approved",
        "amount": 9000,
        "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": "R107356",
      "amount": "59999.00",
      "valid_till": "29.07.2018 12:08:01+03:00",
      "cart_items":
      [{
        "sku": "1231",
        "name": "Samsung Note 8",
        "price": 55999,
        "quantity": 1
      }]
    }
    
    order_id
    string
    Уникальный номер заказа. Не более 255 символов.
    amount
    string
    Сумма в рублях.
    valid_till
    String, optional
    Срок, в течении которого заказ считается актуальным (срок холдирования средств). По истечении срока заказ отменяется. Формат: dd.mm.yyyy hh:mm:ss+hh:mm, где после "+" указывается часовой пояс относительно GMT. По умолчанию - 24 часа.
    cart_items
    object
    Объект, содержащий массив с информацией о заказе.
    sku
    string, optional
    Складская учётная единица (stock keeping unit).
    name
    string
    Наименование товара.
    price
    float
    Цена товара.
    sale_price
    float, optional
    Цена товара со скидкой (если есть).
    quantity
    integer
    Количество товара. Если передано нецелое число, то в форме не отображается.
    brand
    string, optional
    Бренд товара.

    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.

    Описание iFrame REVO

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

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

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

    Валидация:

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

    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 метод плагина REVO.

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

    Далее работает предоставленный Мокка плагин js (реализован в виде модуля REVO), который вставляет <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:

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

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

    Данные для отправки запроса в 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

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

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

    Данные для отправки запроса в 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":4999.0,"check_number":"sdfhk"}

    Приложение фискального документа с 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:

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