☰ Мәзір · Транзакциялар
API анықтамалығы

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

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

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

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
Жіберілген күйінде.
locationobject
Чек өз ережелері бар нүктеге түскенде ғана: {id, name, store_code, register_id, matched_by}. matched_by мәні register_id немесе store_id. Қараңыз: нүкте мен кассаны қалай жіберу керек.
cashierobject
Чек cashier өрісімен жіберілгенде ғана: {id, name}.
memberобъект
Чектен кейінгі қатысушы, жаңа балансымен.
amount_refundedinteger
Осы уақытқа дейінгі ішінара қайтарулардың жалпы сомасы.
line_itemsмассив
Чек позициялары және әрқайсысы не істеді: amount (позицияның чектегі үлесі), cashback_earned, earn_percent (санат есептемесе null), redeemable (кэшбэкпен төлеуге бола ма) және quantity_refunded. Чек позицияларсыз келсе бос.
line_items[].promoboolean
Тек акция ережелері бар мекемелерде: жол акциядағы тауар ретінде жіберілген бе.
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-і. Есептерде көрсетіледі. Иесі бұл кодты нүктеге байласа, чек нүктенің кэшбэк ережелерімен есептеледі.
store_idstring
Есеп жүйеңіздегі дүкен (нүкте) коды, 64 таңбаға дейін. register_id жіберілмесе немесе ешбір нүктеге байланбаса қолданылады. Екеуі әртүрлі нүктелерді көрсетсе, register_id басым. Қараңыз: нүкте мен кассаны қалай жіберу керек.
cashierstring or object
Чекті кім өткізгені, кассаңыз білетіндей: жол (аты немесе коды) не {id, name}. Чекпен бірге сақталады және cashier ішінде қайтарылады. Кэшбэкті ешқашан өзгертпейді және идемпотенттік тексеруге кірмейді. Иесінің кассир сигналдары күдікті чекті кім өткізгенін көрсету үшін соны пайдаланады.
hold_iduuid
redeem_amount жіберудің орнына осы резервті растайды.
discount_typestring
Осы чектегі жеңілдік коды (employee, discount_card, promo), 64 таңбаға дейін. Жеңілдік түрлері қосулы болса, иесінің ережелері қолданылады. Жолдың да өз discount_type болуы мүмкін.
line_items[].promoboolean
Тауар акцияда болса true. Сонда иесінің акция ережелері жолдың кэшбэк есептейтінін және оны кэшбэкпен төлеуге болатынын шешеді. Мекеме ережені қоспаса, еленбейді.
line_itemsмассив
{sku, name, quantity, unit_price, category} элементтері, 500-ге дейін. Тауар есептері үшін чекпен бірге сақталады және санат ережелерінде қолданылады: кэшбэксіз, кэшбэкпен төленбейтін (акциялық тауарлар) немесе өз пайызы бар санат. category болмаса санатты каталогтан sku бойынша табамыз. Позициялар болмаса бүкіл чек қонақтың деңгейі бойынша есептеледі.

Нүкте мен кассаны қалай жіберу керек

Әр чекпен (POST /v1/transactions), есептеумен (POST /v1/checks/calculate) және резервпен (POST /v1/holds) екі міндетті емес жолды жіберіңіз: register_id касса коды, store_id есеп жүйеңіздегі дүкен (нүкте) коды, 64 таңбаға дейін. Иесі екі кодты да Нүктелер бөліміне енгізеді. Нүкте алдымен register_id бойынша ізделеді; касса коды жіберілмесе немесе ешбір нүктеге байланбаса, store_id бойынша. Екеуі де жіберіліп, әртүрлі нүктелерді көрсетсе, register_id басым. Ештеңе табылмаса, чек жалпы ережелер бойынша есептеледі, ал белгісіз кодтар иесіне «байланбаған» тізімінде көрінеді. Кодтар мекемеде нүкте ережелері қосулы болғанда жұмыс істейді; әйтпесе өрістер еленбейді. Нүкте біреу болса да, екі өрісті де әр чекпен жіберіңіз.

Сұрау · POST /v1/transactions
{
  "external_id": "000131",
  "member": "2000111703779",
  "amount": 12550,
  "store_id": "122927",
  "register_id": "122930",
  "line_items": [
    { "sku": "4840001", "name": "Corona 0.33", "quantity": 2, "unit_price": 3500, "category": "106" },
    { "sku": "2040", "name": "Paine", "quantity": 1, "unit_price": 5550 }
  ]
}

Сонда есептеу мен транзакцияда чек есептелген нүктесі бар location нысаны болады: id, name, store_code, register_id және matched_by (register_id немесе store_id). Жауапта location болмаса, чек жалпы ережелер бойынша есептелген.

Жауап · 201 (үзінді)
{
  "object": "transaction",
  "external_id": "000131",
  "register_id": "122930",
  ...
  "location": {
    "object": "location",
    "id": "3c1f5a7e-2b9d-4e60-8f14-6a0d2c7b9e35",
    "name": "Store 1",
    "store_code": "122927",
    "register_id": "122930",
    "matched_by": "register_id"
  }
}
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",
    "store_id": "S-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,
  "amount_refunded": 0,
  "line_items": [
    { "sku": "1001", "name": "Espresso", "quantity": 2, "unit_price": 4000, "category": "Coffee", "amount": 8000, "earn_percent": 5, "cashback_earned": 400, "redeemable": true, "quantity_refunded": 0 },
    { "sku": "2005", "name": "Cheesecake", "quantity": 1, "unit_price": 17000, "category": "Desserts", "amount": 17000, "earn_percent": 5, "cashback_earned": 850, "redeemable": true, "quantity_refunded": 0 }
  ],
  "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 немесе line_items бойынша қайтарады. Сома бойынша кэшбэк чекке пропорционал қайта есептеледі. Позициялар бойынша кэшбэк әр позицияның шын мәнінде есептегеніне сәйкес жүреді: кэшбэксіз акциялық тауар ештеңе алып қоймайды, қонақ жұмсаған кэшбэк тек онымен төлеуге болатын позициялар үшін қайтарылады. Қайтарудың өз external_id мәнін жіберіңіз; оны қайталау қауіпсіз. Бір чекке бірнеше қайтару жасауға болады; соңғысы қалдықтарды дәл жабады. Мөртабан мен сапар бағдарламаларының чектері күшін жою арқылы толық қайтарылады.

external_idstring, міндетті
Осы қайтарудың сіздегі id-і, 128 белгіге дейін.
amountinteger
Қайтарылған сома, ең кіші бірлікпен. Қайтарылғанды line_items сипаттаса жібермеңіз.
line_itemsмассив
Қайтарылған позициялар: чектегідей {sku, quantity} немесе {name, quantity}. Бұрын қайтарылған бірліктер есепке алынады; көбірек сұрау refund_exceeds_line және refundable деп жауап береді. Позицияларсыз жіберілген чек no_line_items деп жауап береді: оны сома бойынша қайтарыңыз.
line_items[].promoboolean
Қабылданады және еленбейді: қайтару бастапқы жолдың есептегені мен төлей алғанымен жүреді.
register_idstring
Кассаңыздың id-і, кассалар бойынша нөмірлеу үшін.
store_idstring
Дүкеніңіздің коды. Чекпен бірізділік үшін қабылданады; қайтару бастапқы чектің нүктесі бойынша жүреді.
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 }'

# or: the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/refunds \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000018", "line_items": [{ "sku": "1001", "quantity": 1 }] }'

# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back
Жауап · 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,
  "line_items": [],
  "livemode": false,
  "created_at": "2026-10-06T18:40:02.000+00:00",
  "transaction_after": { "object": "transaction", "amount_refunded": 5000, "member": { ... }, ... }
}

// by lines
{
  "object": "refund",
  "external_id": "RET-2026-000018",
  "transaction": "CHK-2026-000130",
  "amount": 4500,
  "cashback_reversed": 450,
  "redeem_restored": 0,
  "line_items": [
    { "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
  ],
  ...
}
POST/v1/transactions/{external_id}/returns
Құқық: transactions:write

Чектің бір немесе бірнеше позициясын қайтарады: қонақ үш тауардың бірін қайтарып әкелді. Осы позицияларда есептелген кэшбэк алынады, ал олар үшін төлеген кэшбэк қайтарылады; әр позицияның шын мәнінде есептегеніне және немен төлеуге болатынына қарай, чекке пропорционал емес. Жауап қайтарудағыдай нысан, object: "return" деген белгімен. Қайтарудың өз external_id мәнін жіберіңіз; оны қайталау қауіпсіз. line_items жоқ жіберілген чектер позициялар бойынша қайтарылмайды: оларды amount бойынша қайтарыңыз.

external_idstring, міндетті
Осы қайтарудың сіздегі id-і, 128 белгіге дейін.
line_itemsмассив, міндетті
Қайтарылған позициялар: чектегідей {sku, quantity} немесе {name, quantity}. Бұрын қайтарылған бірліктер есепке алынады; көбірек сұрау refund_exceeds_line және refundable деп жауап береді.
line_items[].promoboolean
Қабылданады және еленбейді: қайтару бастапқы жолдың есептегені мен төлей алғанымен жүреді.
register_idstring
Кассаңыздың id-і, кассалар бойынша нөмірлеу үшін.
store_idstring
Дүкеніңіздің коды. Чекпен бірізділік үшін қабылданады; қайтару бастапқы чектің нүктесі бойынша жүреді.
curl
# the guest brings back one Latte out of the lines on the check
curl https://loyaltyfy.io/api/v1/transactions/CHK-2026-000130/returns \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "RET-2026-000019", "line_items": [{ "sku": "1001", "quantity": 1 }] }'

# the Latte earned 4.50 at its own 10%, so exactly 4.50 is taken back
"Жауап · 201"
{
  "object": "return",
  "id": "9f1c2b8e-5d7a-4e3f-9b21-0c4d6e8f1a23",
  "external_id": "RET-2026-000019",
  "transaction": "CHK-2026-000130",
  "amount": 4500,
  "cashback_reversed": 450,
  "redeem_restored": 0,
  "line_items": [
    { "sku": "1001", "name": "Latte", "quantity": 1, "amount": 4500, "cashback_reversed": 450, "redeem_restored": 0 }
  ],
  "livemode": false,
  "created_at": "2026-11-06T09:12:40.000+00:00",
  "transaction_after": { "object": "transaction", "amount_refunded": 4500, "line_items": [ ... ], "member": { ... }, ... }
}
GET/v1/transactions
Құқық: transactions:write

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

Интеграция бойынша сұрақтар: api@loyaltyfy.io. Бір жұмыс күні ішінде жауап береміз.