☰ Меню · Транзакции
Транзакции
Закрытый чек, переданный кассой. Начисляет бонусы, может списывать кэшбэк, может быть отменён.
Объект транзакции
- 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=. Поддерживает пагинацию.