☰ Меню · Транзакции
Справочник 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. Отвечаем в течение одного рабочего дня.