Συναλλαγές

Μια κλεισμένη απόδειξη που έστειλε ένα ταμείο. Δίνει επιβράβευση, μπορεί να εξαργυρώσει cashback, μπορεί να ακυρωθεί.

Το αντικείμενο transaction

external_idstring: Το id της απόδειξής σας. Μοναδικό ανά επιχείρηση.
statusstring: completed ή voided.
amountinteger: Ολόκληρη η απόδειξη, στη μικρότερη υποδιαίρεση.
redeem_amountinteger: Το ποσό που πληρώθηκε με cashback.
net_amountinteger: amount − redeem_amount.
cashback_earned, stamps_earnedinteger: Τι κέρδισε η απόδειξη.
reward_unlockedboolean: Αυτή η απόδειξη συμπλήρωσε μια κάρτα σφραγίδων.
currency, register_id, closed_atstring: Όπως στάλθηκαν.
memberobject: Το μέλος μετά την απόδειξη, με το νέο υπόλοιπο.
amount_refundedinteger: Το σύνολο των μερικών επιστροφών μέχρι τώρα.
displayobject: Τα cashier_text και receipt_lines στη γλώσσα του πελάτη, έτοιμα για εκτύπωση.

Παράμετρος	Τύπος	Περιγραφή
external_id	string	Το id της απόδειξής σας. Μοναδικό ανά επιχείρηση.
status	string	`completed` ή `voided`.
amount	integer	Ολόκληρη η απόδειξη, στη μικρότερη υποδιαίρεση.
redeem_amount	integer	Το ποσό που πληρώθηκε με cashback.
net_amount	integer	`amount − redeem_amount`.
cashback_earned, stamps_earned	integer	Τι κέρδισε η απόδειξη.
reward_unlocked	boolean	Αυτή η απόδειξη συμπλήρωσε μια κάρτα σφραγίδων.
currency, register_id, closed_at	string	Όπως στάλθηκαν.
member	object	Το μέλος μετά την απόδειξη, με το νέο υπόλοιπο.
amount_refunded	integer	Το σύνολο των μερικών επιστροφών μέχρι τώρα.
display	object	Τα `cashier_text` και `receipt_lines` στη γλώσσα του πελάτη, έτοιμα για εκτύπωση.

POST/v1/transactions

Δικαίωμα: transactions:write

Καταχωρίζει μία κλεισμένη απόδειξη. Η επανάληψη ενός external_id επιστρέφει το αποθηκευμένο αποτέλεσμα με 200. Τα card_number και gross_amount γίνονται δεκτά ως ψευδώνυμα των member και amount.

external_idstring, υποχρεωτικό: Το id της απόδειξής σας, έως 128 χαρακτήρες.
memberstring, υποχρεωτικό: Αριθμός κάρτας, τιμή σάρωσης, serial, id μέλους ή τηλέφωνο.
amountinteger, υποχρεωτικό: Ολόκληρη η απόδειξη πριν από το cashback, στη μικρότερη υποδιαίρεση, μεγαλύτερη από μηδέν.
redeem_amountinteger: Το cashback που χρησιμοποιεί ο πελάτης σε αυτή την απόδειξη. Προεπιλογή 0. Περιορίζεται από το υπόλοιπο και το redeem_max_percent του προγράμματος.
currencystring: ISO 4217. Προεπιλογή: το νόμισμα του προγράμματος.
closed_atdatetime: Πότε έκλεισε η απόδειξη, σε ISO 8601 με offset. Προεπιλογή: τώρα.
register_idstring: Το id του ταμείου ή του καταστήματός σας. Εμφανίζεται στις αναφορές.
hold_iduuid: Επιβεβαιώνει αυτή τη δέσμευση αντί να στείλετε redeem_amount.
line_itemsarray: Έως 500 στοιχεία {sku, name, quantity, unit_price, category}. Αποθηκεύονται μαζί με την απόδειξη για τις αναφορές προϊόντων της επιχείρησης. Δεν αλλάζουν όσα κερδίζει ο πελάτης: τα προγράμματα μετρούν το ποσό της απόδειξης.

Παράμετρος	Τύπος	Περιγραφή
external_id	string, υποχρεωτικό	Το id της απόδειξής σας, έως 128 χαρακτήρες.
member	string, υποχρεωτικό	Αριθμός κάρτας, τιμή σάρωσης, serial, id μέλους ή τηλέφωνο.
amount	integer, υποχρεωτικό	Ολόκληρη η απόδειξη πριν από το cashback, στη μικρότερη υποδιαίρεση, μεγαλύτερη από μηδέν.
redeem_amount	integer	Το cashback που χρησιμοποιεί ο πελάτης σε αυτή την απόδειξη. Προεπιλογή 0. Περιορίζεται από το υπόλοιπο και το `redeem_max_percent` του προγράμματος.
currency	string	ISO 4217. Προεπιλογή: το νόμισμα του προγράμματος.
closed_at	datetime	Πότε έκλεισε η απόδειξη, σε ISO 8601 με offset. Προεπιλογή: τώρα.
register_id	string	Το id του ταμείου ή του καταστήματός σας. Εμφανίζεται στις αναφορές.
hold_id	uuid	Επιβεβαιώνει αυτή τη δέσμευση αντί να στείλετε `redeem_amount`.
line_items	array	Έως 500 στοιχεία `{sku, name, quantity, unit_price, category}`. Αποθηκεύονται μαζί με την απόδειξη για τις αναφορές προϊόντων της επιχείρησης. Δεν αλλάζουν όσα κερδίζει ο πελάτης: τα προγράμματα μετρούν το ποσό της απόδειξης.

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

Αναιρεί μια απόδειξη: το cashback και οι σφραγίδες που κερδήθηκαν αφαιρούνται, το cashback που εξαργυρώθηκε επιστρέφεται. Η διπλή ακύρωση δεν προκαλεί πρόβλημα.

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

Επιστρέφει μέρος μιας απόδειξης cashback. Το cashback που κερδήθηκε για αυτό το μέρος αφαιρείται και το cashback με το οποίο το πλήρωσε ο πελάτης του επιστρέφεται, αναλογικά με το 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=. Με σελιδοποίηση.