Покупка Частинами

Огляд

API Покупки Частинами Монобанку дозволяє магазинам пропонувати клієнтам оплату товарів та послуг у ПЧ. Цей сервіс надає клієнтам можливість розділити покупку на кілька платежів без відсотків, роблячи товари доступнішими, а магазини отримують оплату миттєво.

Ключові можливості

• Миттєве схвалення - кредитне рішення за 20 секунд
• Без відсотків для клієнтів (комісію сплачує магазин)
• Гнучка Покупка Частинами - від 3 до 25 платежів
• Сповіщення в реальному часі через callback або polling
• Детальна звітність та аналітика
• Ідемпотентні операції для запобігання дублювання замовлень

Схема інтеграції

Типова інтеграція відбувається за наступною схемою:

1. Клієнт обирає товари та вибирає оплату через Покупку Частинами
2. Магазин створює замовлення через /api/order/create
3. Клієнт отримує push-сповіщення в застосунку Монобанку
4. Клієнт підтверджує договір ПЧ
5. Магазин отримує callback зі статусом WAITING_FOR_STORE_CONFIRM
6. Магазин видає товар та викликає /api/order/confirm
7. Покупка Частинами стає активною і з клієнта списується перший платіж

Діаграма процесу

sequenceDiagram
    actor Client as Клієнт
    participant Store as Магазин Backend
    participant Mono as Monobank Backend
    participant App as Мобільний застосунок
    autonumber

    Client->>Store: Оформлює замовлення
    Store->>Mono: POST /api/order/create<br>(опційно: result_callback)
    Mono->>App: Push на підтвердження
    Client->>App: Підтверджує ПЧ
    App->>Mono: Approve
    note over Mono: Статус → IN_PROCESS / WAITING_FOR_STORE_CONFIRM

    alt Варіант А: result_callback передано
        Mono-->>Store: POST result_callback
    else Варіант Б: Самостійний запит
        loop Polling статусу
            Store->>Mono: POST /api/order/state
        end
    end

    alt Варіант А: Товар видано
        Store->>Mono: POST /api/order/confirm
        Store->>Client: Видача товару
    else Варіант Б: Відмова у видачі
        Store->>Mono: POST /api/order/reject
    end

Автентифікація та безпека

Всі API запити повинні містити два обов’язкові заголовки:

• store-id - Ваш унікальний ідентифікатор магазину
• signature - HMAC-SHA256 підпис тіла запиту

Розрахунок підпису

Підпис захищає від атак типу “man in the middle” та забезпечує цілісність запиту.

Формула:

signature = Base64(HMAC-SHA256(request_body_bytes, store_secret))

Приклади реалізації

Java

import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class SignatureCalculator {

    public static String calculateSignature(String storeSecret, String requestBody) {
        try {
            Mac mac = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKey = new SecretKeySpec(
                    storeSecret.getBytes(StandardCharsets.UTF_8),
                    "HmacSHA256"
            );
            mac.init(secretKey);

            byte[] hash = mac.doFinal(requestBody.getBytes(StandardCharsets.UTF_8));
            return Base64.getEncoder().encodeToString(hash);

        } catch (NoSuchAlgorithmException | InvalidKeyException e) {
            throw new RuntimeException("Помилка розрахунку підпису", e);
        }
    }
}

PHP

<?php
function calculateSignature($storeSecret, $requestBody) {
    return base64_encode(hash_hmac('sha256', $requestBody, $storeSecret, true));
}

// Приклад використання
$requestBody = '{"store_order_id":"ORD-001","client_phone":"+380501234567","total_sum":1500.00}';
$signature = calculateSignature('your_store_secret', $requestBody);

$headers = [
    'Content-Type: application/json',
    'store-id: your_store_id',
    'signature: ' . $signature
];
?>

Postman Pre-request скрипт

// Отримати змінні колекції: key, storeId
const key = pm.collectionVariables.get("key");
const storeId = pm.collectionVariables.get("storeId");

// Отримати тіло запиту
let body = "";
if (pm.request.body && pm.request.body.raw) {
    body = pm.request.body.raw;
}

// Розрахувати підпис
const keyUtf8 = CryptoJS.enc.Utf8.parse(key);
const hash = CryptoJS.HmacSHA256(body, keyUtf8);
const signature = CryptoJS.enc.Base64.stringify(hash);

// Встановити заголовки
pm.request.headers.upsert({key: "signature", value: signature});
pm.request.headers.upsert({key: "store-id", value: storeId});

Callback сповіщення

Callback надають оновлення статусу замовлення в реальному часі.

Коли ви вказуєте result_callback при створенні замовлення, Монобанк надсилатиме POST запити на ваш endpoint.

Коли надсилається callback

Важливо: Callback надсилається тільки у двох випадках:

• При переході в статус IN_PROCESS/WAITING_FOR_STORE_CONFIRM (клієнт підтвердив ПЧ)
• При переході в будь-який статус FAIL/* (відмова з будь-якої причини)

Для інших статусів (наприклад, IN_PROCESS/WAITING_FOR_CLIENT) callback не надсилається - використовуйте polling через /api/order/state.

Формат Callback

{
  "order_id": "fa4a8249-336e-4e6d-9b85-79bc8be62377",
  "state": "IN_PROCESS",
  "order_sub_state": "WAITING_FOR_STORE_CONFIRM"
}

Безпека Callback

Перевіряйте автентичність callback:

1. Розрахуйте підпис тим же методом, що й для запитів
2. Порівняйте з заголовком signature з callback запиту
3. Обробляйте тільки якщо підписи збігаються

Альтернатива: Опитування статусу

Якщо callback не підходить або необхідно отримувати проміжні статуси, використовуйте /api/order/state для ручної перевірки статусу замовлення.

Довідник статусів замовлень

Розуміння статусів замовлень критично важливе для правильної інтеграції:

Ключовий статус: WAITING_FOR_STORE_CONFIRM

Це найважливіший статус - він означає, що клієнт схвалив кредит і ви можете безпечно видавати товар.

Завжди викликайте /api/order/confirm після видачі товару для активації ПЧ.

Середовища

Тестове середовище (Пісочниця)

Ідеально підходить для початкової інтеграції та тестування різних сценаріїв.

Дані для доступу:

• URL: https://u2-demo-ext.mono.st4g3.com
• Store ID: test_store_with_confirm
• Секретний ключ: secret_98765432--123-123

Тестові сценарії: Використовуйте різні закінчення номерів телефонів для імітації різних результатів:

Приклад: +380501234561 імітує успішне схвалення.

Stage середовище (Передпродакшн)

Реальна інтеграція з застосунком Монобанку для комплексного тестування.

Дані для доступу:

• URL: https://u2-ext.mono.st4g3.com
• Store ID: COMFY
• Секретний ключ: sign_key

Використовуйте це середовище після успішного тестування в пісочниці для перевірки взаємодії з реальним застосунком.

Production середовище

URL: https://u2.monobank.com.ua

Використовуйте ваші продакшн дані, надані Монобанком після успішного тестування та схвалення.

Обробка помилок

Використовувані HTTP статус коди

• 200 - Успіх
• 201 - Замовлення успішно створено
• 400 - Поганий запит (помилки валідації)
• 401 - Підпис не передано або не валідний
• 403 - Заборонено (магазин не має права створювати замовлення)
• 404 - Замовлення не знайдено
• 429 - Перевищено ліміт запитів
• 500 - Внутрішня помилка сервісу

Формат відповіді з помилкою

{
  "message": "Котик перегриз кабель до сервера. Спробуйте ще раз через хвилинку 🐱"
}

Найкращі практики

Створення замовлень

1. Валідуйте дані клієнта перед надсиланням запитів
2. Використовуйте унікальний store_order_id для запобігання дублікатів
3. Завжди вказуйте result_callback для оновлень в реальному часі
4. Обробляйте ідемпотентність - дублікат запиту з однаковим store_order_id повертає ідентифікатор замовлення що вже існує, замість створення нового

Моніторинг статусу

1. Обробляйте WAITING_FOR_STORE_CONFIRM негайно
2. Налаштуйте правильну обробку callback з перевіркою підпису
3. Реалізуйте резервне опитування (polling), якщо callback не працюють
4. Логуйте всі зміни статусу для налагодження

Відновлення після помилок

1. Повторюйте при тимчасових збоях (5xx помилки)
2. Не повторюйте помилки валідації (4xx помилки)
3. Реалізуйте експоненційну затримку для повторів

Підтримка та усунення неполадок

AI Асистент

Отримайте миттєву допомогу з питань інтеграції: 🤖 Помічник API Монобанку

Запланувати сесію тестування

Тестування на передпроді проходить у текстовому форматі.

Забронювати тайм-слот для проведення тестування: 📅 Запланувати тестування

Технічна підтримка

При зверненні до підтримки завжди включайте:

• Trace-Id заголовок з API відповідей
• Store ID та Order ID
• Приклади запитів/відповідей
• Повідомлення про помилки та часові мітки

Заголовок Trace-Id включається в усі API відповіді та допомагає нашій команді підтримки швидко знайти ваші запити в логах.

Поширені проблеми

Помилка валідації підпису

• Перевірте кодування тіла запиту (UTF-8)
• Перевірте правильність секретного ключа
• Переконайтеся, що немає зайвих пробілів у заголовках

Клієнта не знайдено

• Перевірте формат номера телефону (+380XXXXXXXXX)
• Переконайтеся, що клієнт є клієнтом Монобанку
• Перевірте, чи це фінансовий номер телефону

Помилка створення замовлення

• Валідуйте всі обов’язкові поля
• Перевірте ліміти сум (мінімум 1 грн)
• Переконайтеся, що у клієнта немає активних замовлень

Швидкий старт - чек-лист

• Отримати тестові дані від Монобанку
• Реалізувати розрахунок підпису
• Протестувати створення замовлення в пісочниці
• Налаштувати callback endpoint
• Протестувати всі статуси замовлень
• Реалізувати обробку помилок
• Протестувати в stage середовищі
• Отримати продакшн дані
• Розгорнути в продакшн
• Моніторити та підтримувати

Готові до інтеграції? Почніть з пісочниці та слідуйте нашій покроковій документації API🐾