Если ваш магазин работает на одной из указанных CMS, то пройдите упрощенный курс интеграции, нажав на соответствующую иконку

Техническая документация

Сервис онлайн-кредитования ВКредит24.ру позволяет интернет-магазинам продавать товары в кредит. Сервис обеспечивает взаимодействие банков с интернет-магазинами и их клиентами.

Процесс покупки товара в кредит

В процессе покупки в кредит задействованы четыре стороны:

  • клиент
  • сервис ВКредит24.ру
  • интернет-магазин
  • банки-партнеры
Диаграмма процессов при покупке товара в кредит

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

  1. Клиент оформляет заказ в интернет-магазине, в качестве способа оплаты выбирает “В кредит”.
  2. После завершения формирования заказа, в интернет-магазине клиенту открывается специальный виджет ВКредит24.ру, где клиент оформляет заявку на кредит. Заявка отправляется в сервис ВКредит24.ру.
  3. Сервис ВКредит24.ру передаёт заявку на кредит в банки-партнеры.
  4. Банки передают сервису ВКредит24.ру решения по кредиту.
  5. Сервис ВКредит24.ру сообщает клиенту решения банков-партнеров.
  6. Клиент выбирает оптимальное кредитное решение и сообщает его сервису ВКредит24.ру.
  7. Сервис ВКредит24.ру передаёт решение клиента банку-партнеру.
  8. Банк-партнер передает сервису ВКредит24.ру документы для подписания с клиентом.
  9. Сервис ВКредит24.ру передаёт клиенту документы для подписания.
  10. Клиент передаёт подписанные документы сервису ВКредит24.ру.
  11. Сервис ВКредит24.ру направляет подписанные документы банку-партнеру для авторизации кредита.
  12. Банк-партнер авторизует кредит и оповещает об этом сервис ВКредит24.ру.
  13. Сервис ВКредит24.ру оповещает интернет-магазин об успешной авторизации кредита и даёт разрешение на доставку заказа.
  14. Интернет-магазин осуществляет доставку заказа клиенту.
  15. Банк-партнер перечисляет в интернет-магазин кредитные денежные средства.
  16. Клиент погашает кредит в банке-партнере.

Интеграция с сервисом ВКредит24.ру

Сервис ВКредит24.ру предоставляет интернет магазинам набор инструментов для интеграции и взаимодействия:

  1. Функциональный виджет
  2. Стилизованный набор элементов интерфейса
  3. Функциональное API
Для интеграции с сервисом ВКредит24.ру интернет-магазину необходимо установить виджет и разместить кнопки на сайте. Внедрение API является опциональным.

Виджет ВКредит24.ру

Виджет ВКредит24.ру предоставляет интернет-магазину удобный механизм создания заявки на кредит. Виджет легко встраивается в сайт магазина и представляет из себя всплывающий слой (div), в котором клиенту предоставляется информация о получении кредита и предоставляется возможность создать заявку на кредит.

Подключение виджета

Чтобы подключить виджет к своему интернет-магазину, партнеру необходимо:

  1. подключить библиотеку сервиса ВКредит24.ру на страницы своего магазина:
    <script type="text/javascript" src="http://vkredit24.ru/js/widget.js"></script>
    
  2. добавить объект настроек:
    var VVC_SETTINGS = {
        shop_id : 2, // Идентификатор магазина в системе ВКредит24.ру.
        order_id : "ord-555", // Номер заказа на стороне магазина.
        name: "Иванов Иван",  // Фамилия и имя клиента. 
                              // Указывать нужно в порядке: ФАМИЛИЯ ИМЯ, а не наоборот.
        phone:"9261234567",   // Номер телефона клиента, указывается без 8 или +7
          onStateChange :       // (необязательно) Обработчик событий виджета
            function(state) {
                switch(state) {
                    case 'opened':
                        // виджет открыт
                    break;
                    case 'order':
                        // заявка отправлена в нашу систему
                    break;
                    case 'closed':
                        // пользователь закрыл виджет
                        // (пользователь может закрыть виджет в любой момент,
                        // в том числе и до отправки заявки)
                    break;
                }
            }
    }
    
    
  3. Сделать вызов виджета на странице оплаты товара:
    VVC.onBuy([
        { 
            "id": 1923,                // идентификатор товара в интернет-магазине
            "title": "iPhone 6",       // наименование товара
            "amount": 55000.00,        // общая стоимость товаров
            "count":1,                 // количество товара
            "info": "Apple"            // дополнительная информация о товаре, 
                                       // например категория товара
        },
        { 
            "id": 1924, 
            "title": "iMac", 
            "amount":160000.00, 
            "count":1, 
            "info": "Apple"
        }
    ], 2);
    
    
    В функцию необходимо передать два параметра – массив товаров для покупки и задержку перед вызовом виджета в секундах.

Элементы интерфейса

Сервис ВКредит24.ру предоставляет интернет-магазинам конструктор для формирования стилизованных кнопок, которые размещаются на сайте для информирования клиентов о возможности купить товар в кредит.
Конструктор находится по адресу http://vkredit24.ru/choosebutton

API ВКредит24.ру

Сервис ВКредит24.ру позволяет осуществлять автоматическое взаимодействие с программным обеспечением интернет-магазина. Для этого в сервисе реализовано API, которое позволяет создавать заявки на получение кредита, получать статус заявок, а также осуществлять уведомления партнеров о смене статуса заявок.

API ВКредит24.ру работает через HTTP-протокол. Вызовы осуществляются POST-запросом на URL соответствующего вызова. Данные передаются в теле POST-запроса.

Параметры вызова передаются в виде JSON. Перед кем, как передать их, они кодируются в base64, и помещаются внутрь «конверта» вызова. Конверт – JSON-объект, который состоит из трёх частей:

  1. callerId – идентификатор партнера в сервисе ВКредит24.ру
  2. sign – “подпись” запроса (подробнее в разделе «Аутентификация»)
  3. data – параметры вызова, закодированные в base64
Конверт помещается в тело POST-запроса вызова API.

Аутентификация

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

Подпись – это MD5 хеш строки, являющейся результатом конкатенации закодированных в base64 параметров вызова и секретного ключа.

Пример реализации алгоритма создания подписи на языке PHP:

<?php
function vk24Sign($str, $secret)
{
    return md5($str.$secret);
}

В конечном результате получается строка, длинной 40 байт, которая используется для аутентификации запроса.

Создание заявки на кредит

Данная функция позволяет партнеру создать заявку на кредит в сервисе ВКредит24. URL: http://vkredit24.ru/api/v01/create_short_confirmed_app Параметры вызова:

{
    "orderNumber": "ord-555", // номер заказа
    "firstName": "Иван",      // Имя
    "middleName": "Иванович", // Отчество
    "lastName": "Иванов",     // Фамилия
    "phone": "1231234567",    // номер сотового телефона клиента, 10 цифр без +7 и 8
    "email": "ivan@ivanov.dom",     // эл. почта
    "isConfirmed": false,     // необязателен, false - (значение по умолчанию) заявку надо будет подтвердить перед тем, как наша система отправит её в банки; true  - заявка потверждена (менеджер магазина проверил наличие товара и связался с клиентом), обратитесь к менеджеру нашего сервиса, чтобы эта опция стала вам доступна).
    "products": [             // массив с товарами
        {                     // первый товар
            "amount": 25000.00,     // стоимость единицы товара
            "count": 2,             // кол-во единиц товара в заказе
            "title": "iPhone 5C",   // название товара
            "info": "Телефоны"      // доп. информация: категория товара в каталоге магазина и т.д.

        },
        {                           // второй товар
            "amount": 1500.00,
            "count": 1,
            "title": "Чехол Belkin для iPhone 5C, белый",
            "info": "Аксессуары для телефонов"
        }
    ]
}

Ответ:
{
    "status": "ok"
}

Получение статуса заявки на кредит

Данная функция позволяет партнеру получить текущий статус заявки на кредит в сервисе ВКредит24.ру. URL: http://vkredit24.ru/api/v01/get_application_status Параметры вызова:

{
    "orderNumber": "ord-555"    // id/номер заказа на стороне партнера
}

Успешный ответ:
{
    "status": "ok",
    "result": {
        "orderNumber": "ord-555",          // id/номер заказа на стороне партнера
        "status": "new/needs-confirmation" // статус заявки
    }
}

Список возможных статусов:

  • new/needs-confirmation – новая заявка, поступившая от клиента для обработки
  • confirmed/sent2banks – заявка в обработке, передана банкам-партнерам для принятия решения
  • approved/signing – заявка одобрена, в процессе подписания с клиентом
  • signed – договор авторизован в банке-партнере, можно осуществлять доставку заказа клиенту
  • cancelled – отказ/отмена
Финальным статусом по каждому заказу является либо “signed”, либо “cancelled”.

В случае возникновения ошибки, поле status будет содержать значение error, а также появится дополнительное поле errorMessage с кратким описанием ошибки.

Пример:

{
    "status": "error",
    "errorMessage": "Order not found"
}

Возможные значения поля errorMessage:

  • Order not found – заказ не найден
  • Caller not found – неизвестный магазин
  • Invalid hash (signature) – неверно сформирована подпись
  • Malformed call parameters ([orderNumber]): The orderNumber field must be at least 1 characters long – неправильно указан номер заказа
  • Malformed call parameters ([orderNumber]): The orderNumber field cannot be longer than 50 characters long – неправильно указан номер заказа

Автоматическое уведомление об изменении статуса заявки

Сервис ВКредит24.ру позволяет своим партнерам получать уведомления о смене статуса у заявок.

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

Формат данных запроса соответствует формату, используемому для запросов в API ВКредит24.ру, т.е. параметры вызова являются JSON-объектом, который кодируется в base64 и упаковывается в подписанный конверт.

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

Пример входящего запроса:

{
    "callerId": "77777",
    "sign": " e7d19ca47bb2386c159f5afd1a1ab987 ",
    "data": "eyJvcmRlck51bWJlciI6Im9yZC01NTUiLCJzdGF0dXMiOiJjYW5jZWxsZWQifQ=="
}

После раскодирования и проверки подписи, получаем параметры запроса:
{
    "orderNumber": "ord-555",
    "status": "cancelled"
}

Статус считается доставленным, если в ответ на POST-запрос пришёл ответ с кодом статуса HTTP = 2XX (200-299). В противном случае следующая попытка совершается через 2 часа; сервис пытается доставить статус 10 раз.

Пример использования сервиса на PHP

В данном примере создаётся запрос на получение статуса заявки на кредит.

<?php
$shopId = "77777";
$secretKey = 'mySecretKey';
$statusUrl = 'http://vkredit24.ru/api/v01/get_application_status';

// Получение статуса заявки на кредит
$request = [
    'orderNumber' => "ord-555"
];
 
$response = vk24Request($shopId, $secretKey, $statusUrl, $request);
print_r($response);

function vk24Request($shopId, $secretKey, $url, array $request)
{
    $requestJson = json_encode($request);
    $requestData = base64_encode($requestJson);
    $envelope = [
        'callerId' => $shopId,
        'sign' => vk24Sign($requestData, $secretKey),
        'data' => $requestData
    ];
 
    $postData = json_encode($envelope);
 
    $curl = curl_init();
    curl_setopt($curl, CURLOPT_URL, $url);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($curl, CURLOPT_POST, true);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $postData);
 
    $response = curl_exec($curl);
    curl_close($curl);
 
    return json_decode($response, true);
}
 
function vk24Sign($str, $secret)
{
    return md5($str.$secret);
}

Пример на PHP скрипта, принимающего статус заявки от сервиса ВКредит24.ру

<?php
$shopId = "77777";
$secretKey = ' mySecretKey ';

$postData = file_get_contents('php://input');
// $postData = '{
//     "callerId":"70127",
//     "sign":"314ba99b32bb6ccc87af5581d047c97ed2be7ac4",
//     "data":"eyJvcmRlck51bWJlciI6IjE0Mjc3MzE1NjYiLCJzdGF0dXMiOiJjYW5jZWxsZWQifQ=="
// }';

$envelope = json_decode($postData, true);
if($envelope['callerId'] !== $shopId) {
    exit('Incorrect callerId');
}

$sign = vk24Sign($envelope['data'], $secretKey);
if($sign !== $envelope['hash']) {
    exit('Incorrect sign hash');
}

$requestJson = base64_decode($envelope['data']);
$request = json_decode($requestJson, true);
print_r($request);
//    Результат:
//    Array
//    (
//        [orderNumber] => 1427731566
//        [status] => cancelled
//    )

function vk24Sign($str, $secret)
{
    return md5($str.$secret);
}

Обратная связь

Если у Вас возникли вопросы, буду рад помочь.
Гоголев Роман, технический директор ВКредит24.ру
Email: r.gogolev@vkredit24.ru