Резерви

Кешбек, відкладений під час скану й підтверджений закритим чеком.

Об’єкт резерву

iduuid: Передавайте його як hold_id разом із чеком.
memberstring: Номер картки.
amountinteger: Відкладений кешбек у дрібних одиницях.
statusstring: active, captured, released або expired.
captured_bystring або null: external_id чека, який його використав.
expires_atdatetime: Коли невикористаний резерв зніметься сам.

Параметр	Тип	Опис
id	uuid	Передавайте його як `hold_id` разом із чеком.
member	string	Номер картки.
amount	integer	Відкладений кешбек у дрібних одиницях.
status	string	`active`, `captured`, `released` або `expired`.
captured_by	string або null	`external_id` чека, який його використав.
expires_at	datetime	Коли невикористаний резерв зніметься сам.

POST/v1/holds

Право: transactions:write

Відкладає кешбек. Діють ті самі обмеження, що й для чека. Запит на більшу суму відхиляється з 402 insufficient_balance і limited_by. Передавайте Idempotency-Key.

memberstring, обов’язковий: Номер картки, відскановане значення, серійний номер, id учасника або телефон.
amountinteger, обов’язковий: Скільки кешбеку відкласти.
check_amountinteger, обов’язковий: Сума чека, для частки програми та правил категорій.
register_idstring: Id вашої каси.
line_itemsarray: Для правил категорій.

Параметр	Тип	Опис
member	string, обов’язковий	Номер картки, відскановане значення, серійний номер, id учасника або телефон.
amount	integer, обов’язковий	Скільки кешбеку відкласти.
check_amount	integer, обов’язковий	Сума чека, для частки програми та правил категорій.
register_id	string	Id вашої каси.
line_items	array	Для правил категорій.

curl

curl https://loyaltyfy.io/api/v1/holds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: hold-R3-000131" \
  -d '{ "member": "2000111703779", "amount": 3000, "check_amount": 20000, "register_id": "R3" }'

# at payment: the check captures it
curl https://loyaltyfy.io/api/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "000131", "register_id": "R3", "member": "2000111703779",
        "amount": 20000, "hold_id": "5b0d6c1e-8f3a-4d7e-9a61-2c4b8e0f7d19" }'

Відповідь · 201

{
  "object": "hold",
  "id": "5b0d6c1e-8f3a-4d7e-9a61-2c4b8e0f7d19",
  "member": "2000111703779",
  "amount": 3000,
  "check_amount": 20000,
  "status": "active",
  "register_id": "R3",
  "captured_by": null,
  "expires_at": "2026-10-06T19:02:11.000+00:00",
  "livemode": false,
  "created_at": "2026-10-06T18:32:11.000+00:00",
  "member_after": { "object": "member", "cashback": { "balance": 10200, "held": 3000, "available": 7200, ... }, ... }
}

GET/v1/holds/{id}

Право: transactions:write

Один резерв із його поточним статусом.

POST/v1/holds/{id}/release

Право: transactions:write

Одразу повертає гроші. Повторне зняття знятого резерву або резерву з вичерпаним терміном нічого не зламає. Для підтвердженого резерву відповідь буде 409 hold_captured (у цьому разі скасуйте чек).