☰ Меню · Транзакції
Транзакції
Закритий чек, надісланий касою. За нього нараховуються винагороди, ним можна списати кешбек, його можна скасувати.
Об’єкт транзакції
- external_idstring
- Ваш id чека. Унікальний у межах закладу.
- statusstring
completedабоvoided.- amountinteger
- Повна сума чека в дрібних одиницях.
- redeem_amountinteger
- Сума, оплачена кешбеком.
- net_amountinteger
amount − redeem_amount.- cashback_earned, stamps_earnedinteger
- Що нараховано за чек.
- reward_unlockedboolean
- Цей чек заповнив картку штампів.
- currency, register_id, closed_atstring
- У тому вигляді, в якому їх надіслано.
- locationobject
- Лише якщо чек потрапив на точку зі своїми правилами:
{id, name, store_code, register_id, matched_by}.matched_byцеregister_idабоstore_id. Див. як передати точку і касу. - cashierobject
- Лише якщо чек надіслано з
cashier:{id, name}. - memberobject
- Учасник після проведення чека, з новим балансом.
- amount_refundedinteger
- Загальна сума часткових повернень на цей момент.
- line_itemsarray
- Позиції чека і що зробила кожна:
amount(частка позиції в чеку),cashback_earned,earn_percent(null, якщо категорія не нараховує),redeemable(чи можна було оплатити кешбеком) таquantity_refunded. Порожньо, якщо чек прийшов без позицій. - line_items[].promoboolean
- Лише в закладів із правилами для акцій: чи був рядок надісланий як товар в акції.
- displayobject
cashier_textіreceipt_linesмовою гостя, готові до друку.
/v1/transactionsПроводить один закритий чек. Повтор external_id повертає збережений результат із 200. card_number і gross_amount приймаються як синоніми member і amount.
- external_idstring, обов’язковий
- Ваш id чека, до 128 символів.
- memberstring, обов’язковий
- Номер картки, відскановане значення, серійний номер, id учасника або телефон.
- amountinteger, обов’язковий
- Повна сума чека до списання кешбеку, у дрібних одиницях, більша за нуль.
- redeem_amountinteger
- Кешбек, який гість використовує в цьому чеку. За замовчуванням 0. Обмежується балансом і
redeem_max_percentпрограми. - currencystring
- ISO 4217. За замовчуванням валюта програми.
- closed_atdatetime
- Час закриття чека, ISO 8601 зі зміщенням. За замовчуванням поточний час.
- register_idstring
- Id вашої каси або філії. Відображається у звітах. Якщо власник прив'язав цей код до точки, чек рахується за правилами кешбеку точки.
- store_idstring
- Код магазину (точки) з вашої облікової системи, до 64 символів. Використовується, якщо
register_idне передано або він не прив'язаний до жодної точки. Якщо обидва вказують на різні точки, перемагаєregister_id. Див. як передати точку і касу. - cashierstring or object
- Хто пробив чек, як його знає ваша каса: рядок (ім'я або код) або
{id, name}. Зберігається з чеком і повертається вcashier. Ніколи не змінює кешбек і не входить у перевірку ідемпотентності. За ним сигнали касирів у власника показують, хто пробив підозрілий чек. - hold_iduuid
- Підтвердити цей резерв замість передачі
redeem_amount. - discount_typestring
- Код знижки на цьому чеку (
employee,discount_card,promo), до 64 символів. Якщо увімкнені типи знижок, діють правила власника для цього коду. Позиція теж може мати свійdiscount_type. - line_items[].promoboolean
true, якщо товар в акції. Тоді правила для акцій власника вирішують, чи нараховує рядок і чи можна оплатити його кешбеком. Ігнорується, якщо заклад не ввімкнув правило.- line_itemsarray
- До 500 позицій
{sku, name, quantity, unit_price, category}. Зберігаються разом із чеком для товарних звітів і беруть участь у правилах категорій: категорія без кешбеку, без оплати кешбеком (акційні товари) або зі своїм відсотком. Безcategoryкатегорію знаходимо заskuу каталозі. Без позицій весь чек нараховує за рівнем гостя.
Як передати точку і касу
Передавайте два необов'язкові рядки в кожному чеку (POST /v1/transactions), розрахунку (POST /v1/checks/calculate) і резерві (POST /v1/holds): register_id це код каси, store_id це код магазину (точки) у вашій обліковій системі, до 64 символів. Власник вписує обидва коди в розділі Точки. Точка шукається спершу за register_id; якщо код каси не передано або він не прив'язаний до жодної точки, то за store_id. Якщо передано обидва і вони вказують на різні точки, перемагає register_id. Якщо нічого не знайшлося, чек рахується за загальними правилами, а невідомі коди з'являються у власника в списку «не прив'язано». Коди працюють, коли в закладу ввімкнені правила точок; інакше поля ігноруються. Передавайте обидва поля з кожним чеком, навіть якщо точка одна.
{
"external_id": "000131",
"member": "2000111703779",
"amount": 12550,
"store_id": "122927",
"register_id": "122930",
"line_items": [
{ "sku": "4840001", "name": "Corona 0.33", "quantity": 2, "unit_price": 3500, "category": "106" },
{ "sku": "2040", "name": "Paine", "quantity": 1, "unit_price": 5550 }
]
}Тоді в розрахунку і транзакції є об'єкт location з точкою, за якою пораховано чек: id, name, store_code, register_id і matched_by (register_id або store_id). Немає location у відповіді, отже чек пораховано за загальними правилами.
{
"object": "transaction",
"external_id": "000131",
"register_id": "122930",
...
"location": {
"object": "location",
"id": "3c1f5a7e-2b9d-4e60-8f14-6a0d2c7b9e35",
"name": "Store 1",
"store_code": "122927",
"register_id": "122930",
"matched_by": "register_id"
}
}curl https://loyaltyfy.io/api/v1/transactions \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{
"external_id": "CHK-2026-000123",
"member": "2000111703779",
"amount": 25000,
"currency": "MDL",
"register_id": "POS-1",
"store_id": "S-1",
"closed_at": "2026-10-06T18:17:00+03:00",
"line_items": [
{ "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee" },
{ "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts" }
]
}'{
"object": "transaction",
"id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
"external_id": "CHK-2026-000123",
"status": "completed",
"amount": 25000,
"redeem_amount": 0,
"cashback_earned": 1250,
"stamps_earned": 0,
"reward_unlocked": false,
"net_amount": 25000,
"currency": "MDL",
"register_id": "POS-1",
"closed_at": "2026-10-06T15:17:00+00:00",
"livemode": false,
"created_at": "2026-10-06T18:17:17.921+00:00",
"voided_at": null,
"amount_refunded": 0,
"line_items": [
{ "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee", "amount": 8000, "earn_percent": 5, "cashback_earned": 400, "redeemable": true, "quantity_refunded": 0 },
{ "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts", "amount": 17000, "earn_percent": 5, "cashback_earned": 850, "redeemable": true, "quantity_refunded": 0 }
],
"member": {
"object": "member",
"id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
"card_number": "2000111703779",
"cashback": { "balance": 1250, "currency": "MDL", "earn_rate": 5, ... },
...
}
}/v1/transactions/{external_id}Повертає одну транзакцію за вашим id чека.
/v1/transactions/{external_id}/voidСкасовує чек: нараховані кешбек і штампи списуються, використаний кешбек повертається. Повторне скасування нічого не зламає.
curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
-H "Authorization: Bearer sk_test_..."{
"object": "transaction",
"id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
"external_id": "CHK-2026-000123",
"status": "voided",
"amount": 25000,
"cashback_earned": 1250,
"voided_at": "2026-10-06T18:17:21.003+00:00",
"member": {
"object": "member",
"id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
"card_number": "2000111703779",
"cashback": { "balance": 0, "currency": "MDL", "earn_rate": 5, ... },
...
},
...
}/v1/transactions/{external_id}/refundsПовертає частину чека з кешбеком: за amount або за line_items. За сумою кешбек перераховується пропорційно чеку. За позиціями кешбек іде за тим, що кожна позиція реально нарахувала: акційний товар без кешбеку нічого не зніме, а витрачений гостем кешбек повернеться лише за позиції, які ним можна було оплатити. Передайте власний external_id повернення, повтор із ним безпечний. За одним чеком можна зробити кілька повернень, останнє точно закриває залишки. Чеки програм зі штампами й візитами повертаються цілком через скасування.
- external_idstring, обов'язковий
- Ваш id цього повернення, до 128 символів.
- amountinteger
- Повернена сума в мінімальних одиницях. Не передавайте, якщо повернене описано в
line_items. - line_itemsarray
- Повернені позиції:
{sku, quantity}або{name, quantity}, точно як у чеку. Уже повернені одиниці враховуються; запит більшого відповідаєrefund_exceeds_lineізrefundable. Чек, надісланий без позицій, відповідаєno_line_items: повертайте його за сумою. - line_items[].promoboolean
- Приймається й ігнорується: повернення йде за тим, що нарахував і міг оплатити вихідний рядок.
- register_idstring
- Id вашої каси, для нумерації за касами.
- store_idstring
- Код вашого магазину. Приймається для однаковості з чеком; повернення йде за точкою початкового чека.
# the guest returns 50.00 of a 200.00 check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000124/refunds \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "external_id": "RET-2026-000017", "amount": 5000 }'
# or: the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/refunds \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "external_id": "RET-2026-000018", "line_items": [{ "sku": "1001", "quantity": 1 }] }'
# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back{
"object": "refund",
"id": "c41d2f7a-3b9e-4c11-8e0f-6a2d5b7c9e13",
"external_id": "RET-2026-000017",
"transaction": "CHK-2026-000124",
"amount": 5000,
"cashback_reversed": 200,
"redeem_restored": 1000,
"line_items": [],
"livemode": false,
"created_at": "2026-10-06T18:40:02.000+00:00",
"transaction_after": { "object": "transaction", "amount_refunded": 5000, "member": { ... }, ... }
}
// by lines
{
"object": "refund",
"external_id": "RET-2026-000018",
"transaction": "CHK-2026-000130",
"amount": 4500,
"cashback_reversed": 450,
"redeem_restored": 0,
"line_items": [
{ "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
],
...
}/v1/transactions/{external_id}/returnsПовертає одну або кілька позицій чека: гість приніс назад один товар із трьох. Кешбек, нарахований на ці позиції, знімається, а кешбек, яким гість їх оплатив, повертається, за тим, що кожна позиція реально нарахувала і чим її можна було оплатити, а не пропорційно чеку. У відповіді той самий об'єкт, що й у повернення, з object: "return". Передайте власний external_id повернення, повтор із ним безпечний. Чеки, надіслані без line_items, за позиціями не повертаються: повертайте їх за amount.
- external_idstring, обов'язковий
- Ваш id цього повернення, до 128 символів.
- line_itemsarray, обов'язковий
- Повернені позиції:
{sku, quantity}або{name, quantity}, точно як у чеку. Уже повернені одиниці враховуються; запит більшого відповідаєrefund_exceeds_lineізrefundable. - line_items[].promoboolean
- Приймається й ігнорується: повернення йде за тим, що нарахував і міг оплатити вихідний рядок.
- register_idstring
- Id вашої каси, для нумерації за касами.
- store_idstring
- Код вашого магазину. Приймається для однаковості з чеком; повернення йде за точкою початкового чека.
# the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/returns \
-H "Authorization: Bearer sk_test_..." \
-H "Content-Type: application/json" \
-d '{ "external_id": "RET-2026-000019", "line_items": [{ "sku": "1001", "quantity": 1 }] }'
# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back{
"object": "return",
"id": "9f1c2b8e-5d7a-4e3f-9b21-0c4d6e8f1a23",
"external_id": "RET-2026-000019",
"transaction": "CHK-2026-000130",
"amount": 4500,
"cashback_reversed": 450,
"redeem_restored": 0,
"line_items": [
{ "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
],
"livemode": false,
"created_at": "2026-11-06T09:12:40.000+00:00",
"transaction_after": { "object": "transaction", "amount_refunded": 4500, "line_items": [ ... ], "member": { ... }, ... }
}/v1/transactionsПовертає список транзакцій, від найновіших. Фільтр: ?member=. З пагінацією.