Методами API можна сформувати посилання на оплату за посиланням або QR у банках-партнерах та додати чек, який необхідно фіскалізувати після оплати інвойсу. Після того, як покупець виконає оплату, даний чек буде автоматично фіскалізовано на стороні ПРРО.
Перед початком необхідно налаштувати еквайринг від партнерів на сайті checkbox.
Схема роботи:
Використовуйте цей метод для отримати список доступних терміналів для каси.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення)>
Authorization: <токен авторизації>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/terminals' \ -H 'accept: application/json' \ -H 'X-Client-Name: X-Client-Name' \ -H 'X-Client-Version: X-Client-Version' \ -H 'X-License-Key: d6b79c938aff6bebc8d11111' \ -H 'Authorization: Bearer token'
[
{
"id": "416cce67-b7f8-47f0-a569-ee30a6211111",
"qr_id": "hL3huAu11111",
"cash_register_id": "cef04e47-ac49-452f-ac0e-74ab2b911111",
"organization_id": "ac9d69b6-c349-4bc0-857f-eee2d3911111",
"type": "MONOBANK",
"acquiring_type": "QR",
"created_at": "2024-03-22T16:20:09.549268+00:00",
"updated_at": "2024-03-22T16:20:09.549268+00:00"
},
{
"id": "58f70942-4d2f-404f-85d5-b5e992311111",
"qr_id": null,
"cash_register_id": "cef04e47-ac49-452f-ac0e-74ab2b911111",
"organization_id": "ac9d69b6-c349-4bc0-857f-eee2d3911111",
"type": "MONOBANK",
"acquiring_type": "INTERNET",
"created_at": "2024-03-22T16:54:38.356837+00:00",
"updated_at": "2024-03-22T16:54:38.356837+00:00"
}
]
id - UUID терміналу в системі checkbox
qr_id - значення ID QR-каси
cash_register_id - UUID ідентифікатор каси в системі checkbox
organization_id - UUID ідентифікатор організації в системі checkbox
type - провайдер послуг (можливе значення: MONOBANK, EASYPAY)
acquiring_type - тип терміналу (можливе значення: QR, INTERNET)
created_at - дата створення терміналу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
updated_at - дата останнього оновлення терміналу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm (значення дорівнює created_at, якщо дані зі створення не змінювались)
Створення рахунку (інвойсу), на основі інформації про чек та при успішній оплаті - фіскалізація чеку. При використані цього методу зміна може бути закритою. Відкриття та закриття зміни відбувається автоматично. Чек стане доступний при успішній оплаті інвойсу.
У разі створення інвойсу з використанням QR-терміналу - код дійсний до створення наступного інвойсу за даним методом.
Для отримання сповіщення про оплату та фіскалізацію чека - рекомендуємо налаштувати Webhook.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення)>
Authorization: <токен авторизації>
Content-Type: application/json
{
"id": "<генерація та передача UUID v4 чека на стороні інтеграції є обов'язковою>",
"cashier_name": "<Ім'я касира>",
"departament": "<Назва відділу>",
"goods":[
{
"good":{
"code": "<Код товару>",
"name": "<Назва товару>",
"price": <ціна у копійках>,
"tax": [<цифровий або літерний код ставки податку (попередньо програмується у особистому кабінеті). Якщо до товару потрібно застосувати декілька податків - вказати через кому>],
"barcode": "<Штрих-код товару>",
"excise_barcodes": ["<цифрове позначення штрих-коду акцизної марки 1>","<цифрове позначення штрих-коду акцизної марки 2>"],
"header": "<Хедер товару 1>",
"footer": "<Футер товару 1>",
"uktzed": "<код УКТЗЕД>"
},
"good_id": "<UUID v4 товару (якщо ви користуэтесь залишками на сайты checkbox)>",
"quantity": <кількість у тисячах, 1 шт = 1000>,
"is_return": <флаг true/false, що визначає, чи це чек повернення>,
"is_winnings_payout": <флаг true/false, що визначає, чи це виплата виграшу>,
"discounts":[{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення)>",
"value": <значення знижки>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок, що застосовуються для товару (якщо їх >1). Потрібно вказувати через кому для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>"
"privilege": "<номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки>"
}],
"total_sum":<сума вартості товару>
},
{
"good":
{<блок з даними про другий товар, за структурою аналогічний попередньому. блоки good потрібно повторювати стільки разів, скільки у вас товарів у чеку>}
}],
"delivery":{
"email": "<e-mail клієнта для відправки копії чека>",
"emails": ["<e-mail клієнта для відправки копії чека 1>","<e-mail клієнта для відправки копії чека 2>"],
"phone": "<номер телефона клієнта для відправки копії чека по SMS/Viber (для роботи функції має бути налаштована та підключена відповідна послуга)>. Формат 380..."
},
"discounts":[{
"type": "<тип знижки - "DISCOUNT"/"EXTRA_CHARGE" (ЗНИЖКА/НАДБАВКА)>",
"mode": "<режим знижки "VALUE"/"PERCENT" (АБСОЛЮТНЕ ЗНАЧЕННЯ/ВІДСОТКОВА ЗНИЖКА - рекомендуємо відмовлятись від вказування відсоткової знижки та передавати у фіскальний чек абсолютне значення)>",
"value": <значення знижки>,
"tax_code": [<код податку, який застосовується для товару. Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"tax_codes": [<коди податкових ставок через кому, що застосовуються для товару (якщо їх >1). Потрібно вказувати для коректного обрахунку знижки, якщо товар має податкову ставку>],
"name": "<назва знижки або надбавки>",
"privilege": "<номер підтвердження пільгової знижки. Отримується від серверу пільгових знижок. Вказується при використані соціальної знижки>"
}],
"bonuses":[
{
"bonus_card": <інформація про бонусну картку покупця, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>,
"value": <інформація про накопичені бонуси, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>,
"additional_info": <додаткова інформація про бонуси, НЕ ДРУКУЄТЬСЯ В ЧЕКУ>
}],
"payments":[{
"type": "<"CASH"/"CASHLESS" (ГОТІВКА/БЕЗГОТІВКОВИЙ РОЗРАХУНОК (картка, сертифікати, бонуси тощо))>",
"value": <сума оплати у копійках>,
"label": "<текстова назва форми оплати>"
}],
"rounding": <true/false активація режиму заокруглення (для його роботи у блоці payments має бути вказана сума вже заокруглена за правилами НБУ>,
"header": "<хедер чека>",
"footer": "<футер чека>",
"barcode": "<штрих-код чека>",
"order_id": "<UUID v4 замовлення (вказується у випадку роботи з API у режимі замовлень). НЕ ДЛЯ ПЕРЕДАЧІ НОМЕРУ ЗАМОВЛЕНЬ ІЗ ФРОНТ-СИСТЕМ>",
"related_receipt_id": "<UUID v4 пов'язаного фіскального чеку (використовується опціонально для контролю послідовності)>",
"previous_receipt_id": "<UUID v4 попереднього фіскального чеку (використовується опціонально для контролю послідовності)>",
"technical_return": <true/false флаг, яким можна позначити, що даний чек є чеком технічного (помилкового) повернення>,
"is_pawnshop": <true/false флаг, яким можна позначити, що даний чек є чеком ломбарду>,
"custom": {
"html_global_header": "<глобальний хедер для чеків html/pdf візуалізацій>",
"html_global_footer": "<глобальний футер для чеків html/pdf візуалізацій>",
"html_body_style": "<фон сторінки з чеком>",
"html_receipt_style": "<стиль блоку з чеком>",
"html_ruler_style": "<стиль роздільника з зірочками між блоками чеку",
"html_light_block_style": "<стиль світлих блоків, це весь підвал чеку та клітинки з вартістю та кількістю>",
"text_global_header": "<глобальний хедер для чеків png/txt візуалізацій>",
"text_global_footer": "<глобальний футер для чеків png/txt візуалізацій>"
},
"terminal_id": "<UUID терміналу, який буде використовуватися>",
"validity": <cтрок дії в секундах, за замовчуванням рахунок перестає бути дійсним через 24 години. Мінімум тривалості - 60 секунд>,
"redirect_url": "<адреса для повернення (GET) - на цю адресу буде переадресовано користувача після завершення оплати (у разі успіху або помилки)>"
}
curl -X 'POST' \ 'https://api.checkbox.ua/api/v1/invoices/fiscalize' \ -H 'accept: application/json' \ -H 'X-Client-Name: X-Client-Name' \ -H 'X-Client-Version: X-Client-Version' \ -H 'X-License-Key: d6b79c938aff6bebc8d11111' \ -H 'Authorization: Bearer token' \ -H 'Content-Type: application/json' \ -d '{ "id":"bee91935-50c4-4484-9923-c6129cf11111", "cashier_name":"Тестовий касир", "departament":"Тестова каса", "goods":[ { "good":{ "code":"500", "name":"Ремонт радіо-технічної апаратури", "price":100, "tax":[ 8 ] }, "good_id":"e60f0efa-7f8d-4e66-a2e8-246206e11111", "quantity":1000 } ], "delivery":{ "email":"[email protected]", "phone":"380500521111" }, "payments":[ { "type":"CASHLESS", "value":100, "label":"Картка" } ], "rounding":false, "header":"Якийсь хедер", "footer":"Якийсь футер", "terminal_id": "58f70942-4d2f-404f-85d5-b5e992311111", "validity": 86400}'
{
"id": "237c11f8-0ac6-4b84-bda3-e476c6311111",
"external_id": "240329Dtm9zpCt211111",
"status": "CREATED",
"page_url": "https://pay.mbnk.biz/240329Dtm9zpCt211111",
"receipt_id": "bee91935-50c4-4484-9923-c6129cf11111"
}
id - UUID інвойсу в системі checkbox
external_id - ID інвойсу в системі провайдера послуг
status - статус інвойсу (можливі значення: CREATED (створено, очікується оплата), PROCESSING(платіж обробляється), HOLD(сума заблокована), SUCCESS(успішна оплата), FAILURE(неуспішна оплата), REVERSED(оплата повернена після успіху), REQUEST_TO_CANCEL(запит на відміну), EXPIRED(час дії вичерпано))
page_url - URL сторінки з оплатою
receipt_id - UUID чека в системі checkbox
Опис методів отримання посилання з візуалізацією чека доступне в загальному описі API
Кількість полів даних у фіскальному чеку, наведеному в прикладі, є приблизним і може відрізнятись в залежності від інформації, яку банк надав при його створенні.
Перевірка статусу інвойсу за його UUID в системі checkbox.
Отримати UUID інвойсу можна у відповідь на його створення або отримавши перелік усіх інвойсів.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення)>
Authorization: <токен авторизації>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/invoices/c916bc4c-afa9-49ee-9840-d27db1111111' \ -H 'accept: application/json' \ -H 'X-License-Key: d6b79c938aff6bebc8d11111' \ -H 'Authorization: Bearer token'
{
"id": "c916bc4c-afa9-49ee-9840-d27db1111111",
"receipt_id": "bee91935-50c4-4484-9923-c6129cf11111",
"terminal_id": "58f70942-4d2f-404f-85d5-b5e992311111",
"external_id": "240329Dtm9zpCt2p11111",
"status": "SUCCESS",
"transaction_id": null,
"page_url": "https://pay.mbnk.biz/240329Dtm9zpCt211111",
"amount": 100,
"ccy": 980,
"final_amount": 100,
"failure_reason": null,
"reference": "CB_bee91935-50c4-4484-9923-c6129cf11111",
"validity": 86400,
"card_mask": "43141401******80",
"auth_code": "414250",
"rrn": "024526112832",
"commission": 1,
"terminal_name": "MI011111",
"created_at": "2024-03-29T07:15:24.345075+00:00",
"updated_at": "2024-03-29T07:17:04+00:00"
}
id - UUID інвойсу в системі checkbox
receipt_id - UUID чека в системі checkbox
terminal_id - UUID терміналу в системі checkbox
external_id - ID інвойсу в системі провайдера послуг
status - статус інвойсу (можливі значення: CREATED (створено, очікується оплата), PROCESSING(платіж обробляється), HOLD(сума заблокована), SUCCESS(успішна оплата), FAILURE(неуспішна оплата), REVERSED(оплата повернена після успіху), REQUEST_TO_CANCEL(запит на відміну), EXPIRED(час дії вичерпано))
transaction_id - ID інвойсу в системі провайдера послуг EasyPay
page_url - URL сторінки з оплатою
amount - cума оплати в копійках
ccy - ISO 4217 код валюти, за замовчуванням 980 (гривня)
final_amount - підсумкова сума у мінімальних одиницях валюти, змінюється після оплати та повернень
failure_reason - причина відмови (визначається провайдером послуг)
reference - референс платежу, який визначається продавцем
validity - cтрок дії інвойсу в секундах (за замовчуванням рахунок перестає бути дійсним через 24 години)
card_mask - маска карти (не більше 19 символів) (тільки для безготівкових платежів)
auth_code - код авторизації банківської операції (тільки для безготівкових платежів)
rrn - Reference Retrieval Number - унікальний ідентифікатор банківської транзакції (тільки для безготівкових платежів)
commission - комісія (тільки для безготівкових платежів)
terminal_name - назва терміналу в системі checkbox
created_at - дата створення інвойсу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm
updated_at - дата останнього оновлення інвойсу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss±hh:mm
Отрмимання списку усіх інвойсів.
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення)>
Authorization: <токен авторизації>
status: <статус інвойсу (можливі значення: `CREATED` (створено, очікується оплата), `PROCESSING`(платіж обробляється), `HOLD`(сума заблокована), `SUCCESS`(успішна оплата), `FAILURE`(неуспішна оплата), `REVERSED`(оплата повернена після успіху), `REQUEST_TO_CANCEL`(запит на відміну), `EXPIRED`(час дії вичерпано)) - (опціонально)>
from_date: <дата створення інвойсу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm (обов'язкове для заповнення)>
to_date: <дата створення інвойсу у форматі ISO 8601 за шаблоном YYYY-MM-DDThh:mm:ss.ssssss±hh:mm (обов'язкове для заповнення)>
limit: <обмеження на кількість записів (опціонально)>
offset: <використовується спільно з оператором LIMIT для визначення кількості рядків, що пропускаються перед початком вибірки результатів запиту (опціонально)>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'GET' \ 'https://api.checkbox.ua/api/v1/invoices?from_date=2024-01-01T00%3A00%3A00%2B0200&to_date=2024-03-29T10%3A30%3A00%2B0200&limit=1000&offset=0' \ -H 'accept: application/json' \ -H 'X-Client-Name: X-Client-Name' \ -H 'X-Client-Version: X-Client-version' \ -H 'X-License-Key: d6b79c938aff6bebc8d11111' \ -H 'Authorization: Bearer token'
{
"meta": {
"limit": 1000,
"offset": 0
},
"results": [
{
"id": "237c11f8-0ac6-4b84-bda3-e476c638fd23",
"receipt_id": "bee91935-50c4-4484-9923-c6129cf08af7",
"terminal_id": "58f70942-4d2f-404f-85d5-b5e992306977",
"external_id": "240329Dtm9zpCt2pJJCX",
"status": "SUCCESS",
"transaction_id": null,
"page_url": "https://pay.mbnk.biz/240329Dtm9zpCt2pJJCX",
"amount": 100,
"ccy": 980,
"final_amount": 100,
"failure_reason": null,
"reference": "CB_bee91935-50c4-4484-9923-c6129cf08af7",
"validity": 86400,
"card_mask": "43141401******80",
"auth_code": "414250",
"rrn": "024526112832",
"commission": 1,
"terminal_name": "MI010072",
"created_at": "2024-03-29T07:15:24.345075+00:00",
"updated_at": "2024-03-29T07:17:04+00:00"
},
{
"id": "253efde4-0c08-4bd2-a844-ec71393e8900",
"receipt_id": "b53278d3-202a-427a-b1f3-1cfaa81d2d90",
"terminal_id": "58f70942-4d2f-404f-85d5-b5e992306977",
"external_id": "2403297evqdrYBqQV87v",
"status": "CREATED",
"transaction_id": null,
"page_url": "https://pay.mbnk.biz/2403297evqdrYBqQV87v",
"amount": null,
"ccy": null,
"final_amount": null,
"failure_reason": null,
"reference": null,
"validity": 86400,
"card_mask": null,
"auth_code": null,
"rrn": null,
"commission": null,
"terminal_name": null,
"created_at": "2024-03-29T07:39:39.168644+00:00",
"updated_at": "2024-03-29T07:39:39.168644+00:00"
}
]
}
results: масив даних інвойсів із наступними параметрами
[{
параметри відповіді співпадають із параметрами відповіді методу GET /api/v1/invoices/{invoice_id}
}]
Скасування рахунку (інвойсу) за його UUID. Скасувати можна тільки створений та не оплачений рахунок (який знаходиться у статусі CREATED). Повторне виконання методу із вказанням вже видаленого інвойсу завжди буде повертати відповідь "ok": true. Після скасування інвойсу його статус зміниться на EXPIRED (час дії вичерпано).
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення)>
Authorization: <токен авторизації>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'DELETE' \ 'https://api.checkbox.ua/api/v1/invoices/d44e9cb6-3dab-4c36-9179-71a46df11111' \ -H 'accept: application/json' \ -H 'X-License-Key: d6b79c938aff6bebc8d11111' \ -H 'Authorization: Bearer token'
{
"ok": true
}
ok - результат скасування інвойсу
Видалення рахунку (інвойсу) за його UUID із системи checkbox. Видалити інвойс можна в будь-якому статусі. Повторне виконання методу із вказанням вже видаленого інвойсу поверне відповідь 404: "Invoice not found".
accept: application/json
X-Client-Name: <назва інтеграції (обов'язкове для заповнення)>
X-Client-Version: <версія інтеграції (опціонально)>
X-License-Key: <ключ ліцензії каси (обов'язкове для заповнення)>
Authorization: <токен авторизації>
Тіло запиту у даному випадку має бути порожнім.
curl -X 'DELETE' \ 'https://api.checkbox.ua/api/v1/invoices/720473b1-5bca-4bd5-aec0-d1a46bd11111/remove' \ -H 'accept: application/json' \ -H 'X-Client-Name: X-Client-Name' \ -H 'X-Client-Version: X-Client-Version' \ -H 'X-License-Key: d6b79c938aff6bebc8d11111' \ -H 'Authorization: Bearer token'
{
"ok": true
}
ok - результат видалення інвойсу