Транзакції

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

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

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: У тому вигляді, в якому їх надіслано.
memberobject: Учасник після проведення чека, з новим балансом.
amount_refundedinteger: Загальна сума часткових повернень на цей момент.
displayobject: cashier_text і receipt_lines мовою гостя, готові до друку.

Параметр	Тип	Опис
external_id	string	Ваш id чека. Унікальний у межах закладу.
status	string	`completed` або `voided`.
amount	integer	Повна сума чека в дрібних одиницях.
redeem_amount	integer	Сума, оплачена кешбеком.
net_amount	integer	`amount − redeem_amount`.
cashback_earned, stamps_earned	integer	Що нараховано за чек.
reward_unlocked	boolean	Цей чек заповнив картку штампів.
currency, register_id, closed_at	string	У тому вигляді, в якому їх надіслано.
member	object	Учасник після проведення чека, з новим балансом.
amount_refunded	integer	Загальна сума часткових повернень на цей момент.
display	object	`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 вашої каси або філії. Відображається у звітах.
hold_iduuid: Підтвердити цей резерв замість передачі redeem_amount.
line_itemsarray: До 500 позицій {sku, name, quantity, unit_price, category}. Зберігаються разом із чеком для товарних звітів закладу. На нарахування не впливають: програми рахують суму чека.

Параметр	Тип	Опис
external_id	string, обов’язковий	Ваш id чека, до 128 символів.
member	string, обов’язковий	Номер картки, відскановане значення, серійний номер, id учасника або телефон.
amount	integer, обов’язковий	Повна сума чека до списання кешбеку, у дрібних одиницях, більша за нуль.
redeem_amount	integer	Кешбек, який гість використовує в цьому чеку. За замовчуванням 0. Обмежується балансом і `redeem_max_percent` програми.
currency	string	ISO 4217. За замовчуванням валюта програми.
closed_at	datetime	Час закриття чека, ISO 8601 зі зміщенням. За замовчуванням поточний час.
register_id	string	Id вашої каси або філії. Відображається у звітах.
hold_id	uuid	Підтвердити цей резерв замість передачі `redeem_amount`.
line_items	array	До 500 позицій `{sku, name, quantity, unit_price, category}`. Зберігаються разом із чеком для товарних звітів закладу. На нарахування не впливають: програми рахують суму чека.

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",
    "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,
  "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. Передавайте власний external_id повернення, тоді повтор безпечний. На один чек можна зробити кілька повернень, останнє закриває точні залишки. Чеки зі штампами та візитами повертаються повністю через void.

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 }'

Відповідь · 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,
  "livemode": false,
  "created_at": "2026-10-06T18:40:02.000+00:00",
  "transaction_after": { "object": "transaction", "amount_refunded": 5000, "member": { ... }, ... }
}

GET/v1/transactions

Право: transactions:write

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