Reservas

Cashback apartado al escanear y confirmado por el ticket cerrado.

El objeto hold

iduuid: Envíalo como hold_id con el ticket.
memberstring: El número de tarjeta.
amountinteger: Cashback apartado, en unidades mínimas.
statusstring: active, captured, released o expired.
captured_bystring o null: external_id del ticket que la usó.
expires_atdatetime: Cuándo se libera sola una reserva sin usar.

Parámetro	Tipo	Descripción
id	uuid	Envíalo como `hold_id` con el ticket.
member	string	El número de tarjeta.
amount	integer	Cashback apartado, en unidades mínimas.
status	string	`active`, `captured`, `released` o `expired`.
captured_by	string o null	`external_id` del ticket que la usó.
expires_at	datetime	Cuándo se libera sola una reserva sin usar.

POST/v1/holds

Permiso: transactions:write

Aparta cashback. Se aplican los mismos topes que a un ticket; si pides más, se rechaza con 402 insufficient_balance y limited_by. Envía una Idempotency-Key.

memberstring, obligatorio: Número de tarjeta, valor escaneado, número de serie, id de socio o teléfono.
amountinteger, obligatorio: Cashback que se aparta.
check_amountinteger, obligatorio: El total del ticket, para el porcentaje del programa y las reglas de categoría.
register_idstring: El id de tu caja.
line_itemsarray: Para las reglas de categoría.

Parámetro	Tipo	Descripción
member	string, obligatorio	Número de tarjeta, valor escaneado, número de serie, id de socio o teléfono.
amount	integer, obligatorio	Cashback que se aparta.
check_amount	integer, obligatorio	El total del ticket, para el porcentaje del programa y las reglas de categoría.
register_id	string	El id de tu caja.
line_items	array	Para las reglas de categoría.

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

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

Permiso: transactions:write

Una reserva con su estado actual.

POST/v1/holds/{id}/release

Permiso: transactions:write

Devuelve el dinero ahora. Liberar una reserva ya liberada o caducada no tiene efecto; una reserva capturada responde 409 hold_captured (en ese caso, anula el ticket).