Транзакции

Закрытый чек, переданный кассой. Начисляет бонусы, может списывать кэшбэк, может быть отменён.

Объект транзакции

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 возврата, повтор с ним безопасен. По одному чеку можно сделать несколько возвратов, последний точно закрывает остатки. Чеки программ со штампами и визитами возвращаются целиком через отмену.

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=. Поддерживает пагинацию.