☰ Меню · Транзакції
Довідник API

Транзакції

Закритий чек, надісланий касою. За нього нараховуються винагороди, ним можна списати кешбек, його можна скасувати.

Об’єкт транзакції

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 мовою гостя, готові до друку.
POST/v1/transactions
Право: transactions:write

Проводить один закритий чек. Повтор 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. Якщо нічого не знайшлося, чек рахується за загальними правилами, а невідомі коди з'являються у власника в списку «не прив'язано». Коди працюють, коли в закладу ввімкнені правила точок; інакше поля ігноруються. Передавайте обидва поля з кожним чеком, навіть якщо точка одна.

Запит · POST /v1/transactions
{
  "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 у відповіді, отже чек пораховано за загальними правилами.

Відповідь · 201 (фрагмент)
{
  "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
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" }
    ]
  }'
Відповідь · 201
{
  "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, ... },
    ...
  }
}
GET/v1/transactions/{external_id}
Право: transactions:write

Повертає одну транзакцію за вашим id чека.

POST/v1/transactions/{external_id}/void
Право: transactions:write

Скасовує чек: нараховані кешбек і штампи списуються, використаний кешбек повертається. Повторне скасування нічого не зламає.

curl
curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
  -H "Authorization: Bearer sk_test_..."
Відповідь · 200
{
  "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, ... },
    ...
  },
  ...
}
POST/v1/transactions/{external_id}/refunds
Право: transactions:write

Повертає частину чека з кешбеком: за 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
Код вашого магазину. Приймається для однаковості з чеком; повернення йде за точкою початкового чека.
curl
# 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
Відповідь · 201
{
  "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 }
  ],
  ...
}
POST/v1/transactions/{external_id}/returns
Право: transactions:write

Повертає одну або кілька позицій чека: гість приніс назад один товар із трьох. Кешбек, нарахований на ці позиції, знімається, а кешбек, яким гість їх оплатив, повертається, за тим, що кожна позиція реально нарахувала і чим її можна було оплатити, а не пропорційно чеку. У відповіді той самий об'єкт, що й у повернення, з 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
Код вашого магазину. Приймається для однаковості з чеком; повернення йде за точкою початкового чека.
curl
# 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
"Відповідь · 201"
{
  "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": { ... }, ... }
}
GET/v1/transactions
Право: transactions:write

Повертає список транзакцій, від найновіших. Фільтр: ?member=. З пагінацією.

Питання щодо інтеграції: api@loyaltyfy.io. Відповідаємо протягом одного робочого дня.