☰ Мәзір · Транзакциялар
Транзакциялар
Касса жіберген жабық чек. Ол есептеу жасайды, онымен кэшбэкпен төлеуге болады, оны болдырмауға болады.
Транзакция объектісі
- 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, басып шығаруға дайын.
/v1/transactionsБір жабық чекті өткізеді. Қайталанған 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 басым. Ештеңе табылмаса, чек жалпы ережелер бойынша есептеледі, ал белгісіз кодтар иесіне «байланбаған» тізімінде көрінеді. Кодтар мекемеде нүкте ережелері қосулы болғанда жұмыс істейді; әйтпесе өрістер еленбейді. Нүкте біреу болса да, екі өрісті де әр чекпен жіберіңіз.
{
"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 болмаса, чек жалпы ережелер бойынша есептелген.
{
"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 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" }
]
}'{
"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, ... },
...
}
}/v1/transactions/{external_id}Сіздегі чек id-і бойынша бір транзакцияны қайтарады.
/v1/transactions/{external_id}/voidЧекті болдырмайды: есептелген кэшбэк пен штамптар кері алынады, төленген кэшбэк қайтарылады. Екі рет болдырмау зиян келтірмейді.
curl -X POST https://loyaltyfy.io/api/v1/transactions/CHK-2026-000123/void \
-H "Authorization: Bearer sk_test_..."{
"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, ... },
...
},
...
}/v1/transactions/{external_id}/refundsКэшбэгі бар чектің бір бөлігін 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
- Дүкеніңіздің коды. Чекпен бірізділік үшін қабылданады; қайтару бастапқы чектің нүктесі бойынша жүреді.
# 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{
"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 }
],
...
}/v1/transactions/{external_id}/returnsЧектің бір немесе бірнеше позициясын қайтарады: қонақ үш тауардың бірін қайтарып әкелді. Осы позицияларда есептелген кэшбэк алынады, ал олар үшін төлеген кэшбэк қайтарылады; әр позицияның шын мәнінде есептегеніне және немен төлеуге болатынына қарай, чекке пропорционал емес. Жауап қайтарудағыдай нысан, 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
- Дүкеніңіздің коды. Чекпен бірізділік үшін қабылданады; қайтару бастапқы чектің нүктесі бойынша жүреді.
# 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{
"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": { ... }, ... }
}/v1/transactionsТранзакциялар тізімі, жаңасынан бастап. ?member= арқылы сүзіңіз. Беттеумен.