Holds

Cashback set aside at the scan and confirmed by the closed check.

The hold object

iduuid: Send it as hold_id with the check.
memberstring: The card number.
amountinteger: Cashback set aside, minor units.
statusstring: active, captured, released or expired.
captured_bystring or null: external_id of the check that used it.
expires_atdatetime: When an unused hold is released on its own.

Parameter	Type	Description
id	uuid	Send it as `hold_id` with the check.
member	string	The card number.
amount	integer	Cashback set aside, minor units.
status	string	`active`, `captured`, `released` or `expired`.
captured_by	string or null	`external_id` of the check that used it.
expires_at	datetime	When an unused hold is released on its own.

POST/v1/holds

Scope: transactions:write

Sets cashback aside. The same caps as for a check apply; asking for more is refused with 402 insufficient_balance and limited_by. Send an Idempotency-Key.

memberstring, required: Card number, scanned value, serial, member id or phone.
amountinteger, required: Cashback to set aside.
check_amountinteger, required: The check total, for the program's share and the category rules.
register_idstring: Your register id.
line_itemsarray: For category rules.

Parameter	Type	Description
member	string, required	Card number, scanned value, serial, member id or phone.
amount	integer, required	Cashback to set aside.
check_amount	integer, required	The check total, for the program's share and the category rules.
register_id	string	Your register id.
line_items	array	For category rules.

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" }'

Response · 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}

Scope: transactions:write

One hold with its current status.

POST/v1/holds/{id}/release

Scope: transactions:write

Gives the money back now. Releasing a released or expired hold is harmless; a captured hold answers 409 hold_captured (void the check instead).