Резервы

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

Объект резерва

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 (в этом случае отмените чек).