☰ Меню · Резервы
Справочник API
Резервы
Кэшбэк, отложенный при скане и подтверждённый закрытым чеком.
Объект резерва
- iduuid
- Передайте его в
hold_idвместе с чеком. - memberstring
- Номер карты.
- amountinteger
- Отложенный кэшбэк в минимальных единицах.
- statusstring
active,captured,releasedилиexpired.- captured_bystring или null
external_idчека, который использовал резерв.- expires_atdatetime
- Когда неиспользованный резерв снимется сам.
POST
/v1/holdsПраво: transactions:write
Откладывает кэшбэк. Действуют те же ограничения, что и для чека; запрос на большую сумму отклоняется с 402 insufficient_balance и limited_by. Передавайте Idempotency-Key.
- memberstring, обязательный
- Номер карты, отсканированное значение, серийный номер, id участника или телефон.
- amountinteger, обязательный
- Сколько кэшбэка отложить.
- check_amountinteger, обязательный
- Сумма чека, для доли программы и правил категорий.
- register_idstring
- Id вашей кассы. Если он привязан к точке, где оплата кэшбэком запрещена, резерв отклоняется с
redeem_not_allowed_here. - store_idstring
- Код магазина (точки) из вашей учётной системы, до 64 символов. Используется, если
register_idне передан или не привязан ни к одной точке. Если оба указывают на разные точки, побеждаетregister_id. См. как передать точку и кассу. - cashierstring or object
- Кто пробивает чек: строка или
{id, name}. Хранится в холде и возвращается вcashier; чек, который списывает холд без своегоcashier, берёт этого кассира. - line_itemsarray
- Для правил категорий.
- line_items[].promoboolean
true, если товар в акции. Тогда правила для акций владельца решают, начисляет ли строка и можно ли оплатить её кэшбэком. Игнорируется, если заведение не включило правило.
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 (в этом случае отмените чек).