Transactions

A closed check sent by a till. It earns, it can redeem cashback, it can be voided.

The transaction object

external_idstring: Your check id. Unique per venue.
statusstring: completed or voided.
amountinteger: The full check, minor units.
redeem_amountinteger: Paid with cashback.
net_amountinteger: amount − redeem_amount.
cashback_earned, stamps_earnedinteger: What the check earned.
reward_unlockedboolean: This check completed a stamp card.
currency, register_id, closed_atstring: As sent.
memberobject: The member after the check, with the new balance.
amount_refundedinteger: Total of partial refunds so far.
displayobject: cashier_text and receipt_lines in the guest's language, ready to print.

Parameter	Type	Description
external_id	string	Your check id. Unique per venue.
status	string	`completed` or `voided`.
amount	integer	The full check, minor units.
redeem_amount	integer	Paid with cashback.
net_amount	integer	`amount − redeem_amount`.
cashback_earned, stamps_earned	integer	What the check earned.
reward_unlocked	boolean	This check completed a stamp card.
currency, register_id, closed_at	string	As sent.
member	object	The member after the check, with the new balance.
amount_refunded	integer	Total of partial refunds so far.
display	object	`cashier_text` and `receipt_lines` in the guest's language, ready to print.

POST/v1/transactions

Scope: transactions:write

Applies one closed check. Repeating an external_id returns the stored result with 200. card_number and gross_amount are accepted as aliases of member and amount.

external_idstring, required: Your check id, up to 128 characters.
memberstring, required: Card number, scanned value, serial, member id or phone.
amountinteger, required: The full check before cashback, minor units, above zero.
redeem_amountinteger: Cashback the guest uses on this check. Default 0. Capped by the balance and the program's redeem_max_percent.
currencystring: ISO 4217. Default: the program currency.
closed_atdatetime: When the check closed, ISO 8601 with offset. Default: now.
register_idstring: Your till or location id. Shown in reports.
hold_iduuid: Capture this hold instead of sending redeem_amount.
line_itemsarray: Up to 500 of {sku, name, quantity, unit_price, category}. Stored with the check for the venue's product reports. They do not change what the guest earns: programs count the check amount.

Parameter	Type	Description
external_id	string, required	Your check id, up to 128 characters.
member	string, required	Card number, scanned value, serial, member id or phone.
amount	integer, required	The full check before cashback, minor units, above zero.
redeem_amount	integer	Cashback the guest uses on this check. Default 0. Capped by the balance and the program's `redeem_max_percent`.
currency	string	ISO 4217. Default: the program currency.
closed_at	datetime	When the check closed, ISO 8601 with offset. Default: now.
register_id	string	Your till or location id. Shown in reports.
hold_id	uuid	Capture this hold instead of sending `redeem_amount`.
line_items	array	Up to 500 of `{sku, name, quantity, unit_price, category}`. Stored with the check for the venue's product reports. They do not change what the guest earns: programs count the check amount.

curl

curl https://loyaltyfy.io/api/v1/transactions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "CHK-2026-000123",
    "member": "2000111703779",
    "amount": 25000,
    "currency": "MDL",
    "register_id": "POS-1",
    "closed_at": "2026-10-06T18:17:00+03:00",
    "line_items": [
      { "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee" },
      { "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts" }
    ]
  }'

Response · 201

{
  "object": "transaction",
  "id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
  "external_id": "CHK-2026-000123",
  "status": "completed",
  "amount": 25000,
  "redeem_amount": 0,
  "cashback_earned": 1250,
  "stamps_earned": 0,
  "reward_unlocked": false,
  "net_amount": 25000,
  "currency": "MDL",
  "register_id": "POS-1",
  "closed_at": "2026-10-06T15:17:00+00:00",
  "livemode": false,
  "created_at": "2026-10-06T18:17:17.921+00:00",
  "voided_at": null,
  "member": {
    "object": "member",
    "id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
    "card_number": "2000111703779",
    "cashback": { "balance": 1250, "currency": "MDL", "earn_rate": 5, ... },
    ...
  }
}

GET/v1/transactions/{external_id}

Scope: transactions:write

Returns one transaction by your check id.

POST/v1/transactions/{external_id}/void

Scope: transactions:write

Undoes a check: earned cashback and stamps are taken back, redeemed cashback is returned. Voiding twice is harmless.

curl

curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
  -H "Authorization: Bearer sk_test_..."

Response · 200

{
  "object": "transaction",
  "id": "f8acbb16-0b3b-4afc-acbb-e5eabd4dd072",
  "external_id": "CHK-2026-000123",
  "status": "voided",
  "amount": 25000,
  "cashback_earned": 1250,
  "voided_at": "2026-10-06T18:17:21.003+00:00",
  "member": {
    "object": "member",
    "id": "6dacfe0a-2500-44c6-a37c-05c660b093b4",
    "card_number": "2000111703779",
    "cashback": { "balance": 0, "currency": "MDL", "earn_rate": 5, ... },
    ...
  },
  ...
}

POST/v1/transactions/{external_id}/refunds

Scope: transactions:write

Returns part of a cashback check. Cashback earned on that part is taken back and cashback the guest paid for it is given back, in proportion to amount. Send the refund's own external_id; repeating it is safe. Several refunds per check are allowed; the last one settles exact remainders. Stamp and visit checks are refunded in full with void.

curl

# the guest returns 50.00 of a 200.00 check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000124/refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000017", "amount": 5000 }'

Response · 201

{
  "object": "refund",
  "id": "c41d2f7a-3b9e-4c11-8e0f-6a2d5b7c9e13",
  "external_id": "RET-2026-000017",
  "transaction": "CHK-2026-000124",
  "amount": 5000,
  "cashback_reversed": 200,
  "redeem_restored": 1000,
  "livemode": false,
  "created_at": "2026-10-06T18:40:02.000+00:00",
  "transaction_after": { "object": "transaction", "amount_refunded": 5000, "member": { ... }, ... }
}

GET/v1/transactions

Scope: transactions:write

Lists transactions, newest first. Filter with ?member=. Paginated.