Транзакциялар

Касса жіберген жабық чек. Ол есептеу жасайды, онымен кэшбэкпен төлеуге болады, оны болдырмауға болады.

Транзакция объектісі

external_idstring: Сіздегі чек id-і. Мекеме ішінде бірегей.
statusstring: completed немесе voided.
amountinteger: Толық чек, кіші бірлікте.
redeem_amountinteger: Кэшбэкпен төленген сома.
net_amountinteger: amount − redeem_amount.
cashback_earned, stamps_earnedinteger: Чек не бергені.
reward_unlockedboolean: Осы чек штамп картасын толтырды.
currency, register_id, closed_atstring: Жіберілген күйінде.
memberобъект: Чектен кейінгі қатысушы, жаңа балансымен.
amount_refundedinteger: Осы уақытқа дейінгі ішінара қайтарулардың жалпы сомасы.
displayобъект: Қонақтың тіліндегі cashier_text және receipt_lines, басып шығаруға дайын.

Параметр	Түрі	Сипаттама
external_id	string	Сіздегі чек id-і. Мекеме ішінде бірегей.
status	string	`completed` немесе `voided`.
amount	integer	Толық чек, кіші бірлікте.
redeem_amount	integer	Кэшбэкпен төленген сома.
net_amount	integer	`amount − redeem_amount`.
cashback_earned, stamps_earned	integer	Чек не бергені.
reward_unlocked	boolean	Осы чек штамп картасын толтырды.
currency, register_id, closed_at	string	Жіберілген күйінде.
member	объект	Чектен кейінгі қатысушы, жаңа балансымен.
amount_refunded	integer	Осы уақытқа дейінгі ішінара қайтарулардың жалпы сомасы.
display	объект	Қонақтың тіліндегі `cashier_text` және `receipt_lines`, басып шығаруға дайын.

POST/v1/transactions

Құқық: transactions:write

Бір жабық чекті өткізеді. Қайталанған external_id сақталған нәтижені 200 кодымен қайтарады. card_number және gross_amount өрістері member және amount өрістерінің баламасы ретінде қабылданады.

external_idstring, міндетті: Сіздегі чек id-і, 128 таңбаға дейін.
memberstring, міндетті: Карта нөмірі, сканерленген мән, сериялық нөмір, қатысушы id-і немесе телефон.
amountinteger, міндетті: Кэшбэкке дейінгі толық чек, кіші бірлікте, нөлден үлкен.
redeem_amountinteger: Қонақ осы чекте пайдаланатын кэшбэк. Әдепкі 0. Баланспен және бағдарламаның redeem_max_percent мәнімен шектеледі.
currencystring: ISO 4217. Әдепкі: бағдарлама валютасы.
closed_atdatetime: Чек жабылған уақыт, ығысуы көрсетілген ISO 8601. Әдепкі: қазіргі уақыт.
register_idstring: Сіздегі касса немесе филиал id-і. Есептерде көрсетіледі.
hold_iduuid: redeem_amount жіберудің орнына осы резервті растайды.
line_itemsмассив: {sku, name, quantity, unit_price, category} элементтері, 500-ге дейін. Мекеменің тауар есептері үшін чекпен бірге сақталады. Қонақтың алатынына әсер етпейді: бағдарламалар чек сомасын есептейді.

Параметр	Түрі	Сипаттама
external_id	string, міндетті	Сіздегі чек id-і, 128 таңбаға дейін.
member	string, міндетті	Карта нөмірі, сканерленген мән, сериялық нөмір, қатысушы id-і немесе телефон.
amount	integer, міндетті	Кэшбэкке дейінгі толық чек, кіші бірлікте, нөлден үлкен.
redeem_amount	integer	Қонақ осы чекте пайдаланатын кэшбэк. Әдепкі 0. Баланспен және бағдарламаның `redeem_max_percent` мәнімен шектеледі.
currency	string	ISO 4217. Әдепкі: бағдарлама валютасы.
closed_at	datetime	Чек жабылған уақыт, ығысуы көрсетілген ISO 8601. Әдепкі: қазіргі уақыт.
register_id	string	Сіздегі касса немесе филиал id-і. Есептерде көрсетіледі.
hold_id	uuid	`redeem_amount` жіберудің орнына осы резервті растайды.
line_items	массив	`{sku, name, quantity, unit_price, category}` элементтері, 500-ге дейін. Мекеменің тауар есептері үшін чекпен бірге сақталады. Қонақтың алатынына әсер етпейді: бағдарламалар чек сомасын есептейді.

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

Жауап · 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}

Құқық: transactions:write

Сіздегі чек id-і бойынша бір транзакцияны қайтарады.

POST/v1/transactions/{external_id}/void

Құқық: transactions:write

Чекті болдырмайды: есептелген кэшбэк пен штамптар кері алынады, төленген кэшбэк қайтарылады. Екі рет болдырмау зиян келтірмейді.

curl

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

Жауап · 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

Құқық: transactions:write

Кэшбэк чегінің бір бөлігін қайтарады. Сол бөлікке есептелген кэшбэк кері алынады, ал қонақ сол бөлік үшін төлеген кэшбэк оған қайтарылады, amount мәніне пропорционал түрде. Қайтарудың өз external_id мәнін жіберіңіз, оны қайталау қауіпсіз. Бір чекке бірнеше қайтару жасауға болады, соңғысы дәл қалдықтарды жабады. Штамп және келу чектері 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 }'

Жауап · 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

Құқық: transactions:write

Транзакциялар тізімі, жаңасынан бастап. ?member= арқылы сүзіңіз. Беттеумен.