☰ Meniu · Tranzacții
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
completedsauvoided.- 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.
- locationobject
- Doar când bonul a ajuns la o locație cu reguli proprii:
{id, name, store_code, register_id, matched_by}.matched_byesteregister_idsaustore_id. Vezi cum transmiteți locația și casa. - cashierobject
- Doar când bonul a fost trimis cu
cashier:{id, name}. - memberobject
- Membrul după bon, cu noul sold.
- amount_refundedinteger
- Totalul retururilor parțiale de până acum.
- line_itemsarray
- Pozițiile bonului și ce a făcut fiecare:
amount(partea poziției din bon),cashback_earned,earn_percent(null când categoria nu acumulează),redeemable(se putea plăti cu cashback) șiquantity_refunded. Gol când bonul a venit fără poziții. - line_items[].promoboolean
- Doar pentru localurile cu reguli pentru promoții: dacă linia a fost trimisă ca produs în promoție.
- displayobject
cashier_textșireceipt_linesîn limba oaspetelui, gata de tipărit.
/v1/transactionsAplică 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_percental 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. Dacă proprietarul a legat acest cod de o locație, bonul urmează regulile de cashback ale locației.
- store_idstring
- Codul magazinului (locației) din sistemul vostru contabil, până la 64 de caractere. Se folosește când
register_idlipsește sau nu este legat de nicio locație. Când ambele indică locații diferite, câștigăregister_id. Vezi cum transmiteți locația și casa. - cashierstring or object
- Cine a emis bonul, așa cum îl știe casa dvs.: un șir (nume sau cod) sau
{id, name}. Se salvează cu bonul și se întoarce încashier. Nu schimbă niciodată cashback-ul și nu intră în verificarea de idempotență. Semnalele casierilor ale proprietarului îl folosesc ca să arate cine a emis un bon suspect. - hold_iduuid
- Confirmă această rezervare în loc să trimiți
redeem_amount. - discount_typestring
- Codul reducerii pe acest bon (
employee,discount_card,promo), până la 64 de caractere. Cu tipurile de reduceri pornite se aplică regulile proprietarului. O linie poate avea și propriuldiscount_type. - line_items[].promoboolean
truecând produsul este în promoție. Atunci regulile pentru promoții ale proprietarului decid dacă linia acumulează și dacă poate fi plătită cu cashback. Ignorat dacă localul nu a pornit regula.- line_itemsarray
- Până la 500 de elemente
{sku, name, quantity, unit_price, category}. Se păstrează împreună cu bonul pentru rapoartele de produse și sunt folosite de regulile categoriilor: o categorie fără cashback, care nu se poate plăti cu cashback (produse la promoție) sau cu procentul ei propriu. Fărăcategorycăutăm categoria dupăskuîn catalog. Fără poziții, tot bonul acumulează la nivelul oaspetelui.
Cum transmiteți locația și casa
Trimiteți două șiruri opționale cu fiecare bon (POST /v1/transactions), calcul (POST /v1/checks/calculate) și rezervare (POST /v1/holds): register_id este codul casei, store_id este codul magazinului (locației) în sistemul vostru contabil, până la 64 de caractere. Proprietarul introduce ambele coduri în Locații. Locația se caută întâi după register_id; dacă codul casei lipsește sau nu este legat de nicio locație, după store_id. Dacă sunt trimise ambele și indică locații diferite, câștigă register_id. Dacă nu se găsește nimic, bonul urmează regulile generale, iar codurile necunoscute apar la proprietar în lista „nelegate”. Codurile funcționează când localul are regulile pe locații pornite; altfel câmpurile sunt ignorate. Trimiteți ambele câmpuri cu fiecare bon, chiar și cu o singură locație.
{
"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 }
]
}Calculul și tranzacția au atunci un obiect location cu locația la care s-a calculat bonul: id, name, store_code, register_id și matched_by (register_id sau store_id). Fără location în răspuns, bonul a urmat regulile generale.
{
"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}Întoarce o tranzacție după id-ul tău de bon.
/v1/transactions/{external_id}/voidAnulează un bon: cashback-ul și ștampilele acumulate se retrag, cashback-ul folosit revine. O anulare repetată nu are niciun efect.
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}/refundsReturnează o parte dintr-un bon cu cashback, după amount sau după line_items. După sumă, cashback-ul se recalculează proporțional cu bonul. După poziții, cashback-ul urmează ce a acumulat cu adevărat fiecare poziție: un produs la promoție care nu a acumulat nimic nu retrage nimic, iar cashback-ul cheltuit de oaspete revine doar pentru pozițiile care se puteau plăti cu el. Trimiteți propriul external_id al returnării; repetarea lui este sigură. Se pot face mai multe returnări pe un bon; ultima închide exact resturile. Bonurile programelor cu ștampile și vizite se returnează integral prin anulare.
- external_idstring, obligatoriu
- Id-ul vostru al acestei returnări, până la 128 de caractere.
- amountinteger
- Suma returnată în unități minime. Nu o trimiteți când
line_itemsspun ce s-a returnat. - line_itemsarray
- Pozițiile returnate:
{sku, quantity}sau{name, quantity}, exact ca pe bon. Unitățile deja returnate se iau în calcul; cererea unui număr mai mare răspunderefund_exceeds_linecurefundable. Un bon trimis fără poziții răspundeno_line_items: returnați-l după sumă. - line_items[].promoboolean
- Acceptat și ignorat: returul urmează ce a acumulat și ce putea plăti linia inițială.
- register_idstring
- Id-ul casei voastre, pentru numerotarea pe case.
- store_idstring
- Codul magazinului vostru. Este acceptat pentru simetrie cu bonul; returul urmează locația bonului inițial.
# 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}/returnsReturnează una sau mai multe poziții ale unui bon: oaspetele aduce înapoi un produs din trei. Cashback-ul acumulat pe acele poziții se retrage, iar cashback-ul cu care le-a plătit revine, după ce a acumulat fiecare poziție și cu ce se putea plăti, niciodată proporțional cu bonul. Răspunsul este același obiect ca la o returnare, cu object: "return". Trimiteți propriul external_id al returnării; repetarea lui este sigură. Bonurile trimise fără line_items nu se returnează pe poziții: returnați-le după amount.
- external_idstring, obligatoriu
- Id-ul vostru al acestei returnări, până la 128 de caractere.
- line_itemsarray, obligatoriu
- Pozițiile returnate:
{sku, quantity}sau{name, quantity}, exact ca pe bon. Unitățile deja returnate se iau în calcul; cererea unui număr mai mare răspunderefund_exceeds_linecurefundable. - line_items[].promoboolean
- Acceptat și ignorat: returul urmează ce a acumulat și ce putea plăti linia inițială.
- register_idstring
- Id-ul casei voastre, pentru numerotarea pe case.
- store_idstring
- Codul magazinului vostru. Este acceptat pentru simetrie cu bonul; returul urmează locația bonului inițial.
# 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/transactionsListează tranzacțiile, cele mai noi primele. Filtrează cu ?member=. Cu paginare.