Tranzacții

Un bon închis, trimis de casă. Aduce cashback sau ștampile, poate folosi cashback, poate fi anulat.

Obiectul transaction

external_idstring: Id-ul tău de bon. Unic per local.
statusstring: completed sau voided.
amountinteger: Bonul întreg, în subunități.
redeem_amountinteger: Partea plătită cu cashback.
net_amountinteger: amount − redeem_amount.
cashback_earned, stamps_earnedinteger: Ce a adus bonul.
reward_unlockedboolean: Acest bon a completat un card de ștampile.
currency, register_id, closed_atstring: Așa cum au fost trimise.
memberobject: Membrul după bon, cu noul sold.
amount_refundedinteger: Totalul retururilor parțiale de până acum.
displayobject: cashier_text și receipt_lines în limba oaspetelui, gata de tipărit.

Parametru	Tip	Descriere
external_id	string	Id-ul tău de bon. Unic per local.
status	string	`completed` sau `voided`.
amount	integer	Bonul întreg, în subunități.
redeem_amount	integer	Partea plătită cu cashback.
net_amount	integer	`amount − redeem_amount`.
cashback_earned, stamps_earned	integer	Ce a adus bonul.
reward_unlocked	boolean	Acest bon a completat un card de ștampile.
currency, register_id, closed_at	string	Așa cum au fost trimise.
member	object	Membrul după bon, cu noul sold.
amount_refunded	integer	Totalul retururilor parțiale de până acum.
display	object	`cashier_text` și `receipt_lines` în limba oaspetelui, gata de tipărit.

POST/v1/transactions

Permisiune: transactions:write

Aplică un bon închis. Un external_id repetat întoarce rezultatul salvat, cu 200. card_number și gross_amount sunt acceptate ca alias pentru member și amount.

external_idstring, obligatoriu: Id-ul tău de bon, până la 128 de caractere.
memberstring, obligatoriu: Numărul cardului, valoarea scanată, seria, id-ul membrului sau telefonul.
amountinteger, obligatoriu: Bonul întreg înainte de cashback, în subunități, mai mare decât zero.
redeem_amountinteger: Cashback-ul folosit de oaspete pe acest bon. Implicit 0. Plafonat de sold și de redeem_max_percent al programului.
currencystring: ISO 4217. Implicit: moneda programului.
closed_atdatetime: Momentul închiderii bonului, ISO 8601 cu fus orar. Implicit: acum.
register_idstring: Id-ul casei sau al locației tale. Apare în rapoarte.
hold_iduuid: Confirmă această rezervare în loc să trimiți redeem_amount.
line_itemsarray: Până la 500 de elemente {sku, name, quantity, unit_price, category}. Se păstrează împreună cu bonul pentru rapoartele de produse ale localului. Nu schimbă ce primește oaspetele: programele țin cont de suma bonului.

Parametru	Tip	Descriere
external_id	string, obligatoriu	Id-ul tău de bon, până la 128 de caractere.
member	string, obligatoriu	Numărul cardului, valoarea scanată, seria, id-ul membrului sau telefonul.
amount	integer, obligatoriu	Bonul întreg înainte de cashback, în subunități, mai mare decât zero.
redeem_amount	integer	Cashback-ul folosit de oaspete pe acest bon. Implicit 0. Plafonat de sold și de `redeem_max_percent` al programului.
currency	string	ISO 4217. Implicit: moneda programului.
closed_at	datetime	Momentul închiderii bonului, ISO 8601 cu fus orar. Implicit: acum.
register_id	string	Id-ul casei sau al locației tale. Apare în rapoarte.
hold_id	uuid	Confirmă această rezervare în loc să trimiți `redeem_amount`.
line_items	array	Până la 500 de elemente `{sku, name, quantity, unit_price, category}`. Se păstrează împreună cu bonul pentru rapoartele de produse ale localului. Nu schimbă ce primește oaspetele: programele țin cont de suma bonului.

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

Răspuns · 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}

Permisiune: transactions:write

Întoarce o tranzacție după id-ul tău de bon.

POST/v1/transactions/{external_id}/void

Permisiune: transactions:write

Anulează un bon: cashback-ul și ștampilele acumulate se retrag, cashback-ul folosit revine. O anulare repetată nu are niciun efect.

curl

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

Răspuns · 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

Permisiune: transactions:write

Returnează o parte dintr-un bon cu cashback. Cashback-ul acumulat pe acea parte se retrage, iar cashback-ul plătit de oaspete pentru ea îi revine, proporțional cu amount. Trimite un external_id propriu al returului; îl poți repeta în siguranță. Sunt permise mai multe retururi pe același bon; ultimul închide exact restul. Bonurile cu ștampile și vizite se returnează integral, prin anulare.

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

Răspuns · 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

Permisiune: transactions:write

Listează tranzacțiile, cele mai noi primele. Filtrează cu ?member=. Cu paginare.