METACARD Loyalty API v1
Στα ελληνικά, με λίγα λόγια
Αυτό το API συνδέει το ERP ή το POS σας με τις κάρτες πιστότητας METACARD στο Apple Wallet και στο Google Wallet.
Τι κάνει το ταμείο σας:
- Σκανάρει το QR της κάρτας και ζητά από εμάς τον πελάτη, τους πόντους και τις ανταμοιβές του.
- Μετά την απόδειξη, μας στέλνει την αγορά. Εμείς προσθέτουμε τους πόντους και ενημερώνουμε την κάρτα στο κινητό.
- Ακυρώνει μια αγορά ή εξαργυρώνει μια ανταμοιβή, πάλι με ένα αίτημα.
Αν η ίδια απόδειξη σταλεί δύο φορές, δεν γίνεται τίποτα διπλό. Μπορείτε να ξαναστείλετε με ασφάλεια όταν χαθεί η σύνδεση.
Το κλειδί API το δημιουργεί ο ιδιοκτήτης ή ο διαχειριστής της επιχείρησης, στο Ρυθμίσεις → Επιχείρηση → Προγραμματιστές. Το κλειδί εμφανίζεται μόνο μία φορά.
Για δοκιμές σας δίνουμε κλειδί για τη δοκιμαστική επιχείρηση "METACARD Demo ERP". Τη μοιράζονται όλοι οι συνεργάτες, οπότε μη βάζετε εκεί πραγματικά στοιχεία.
Οι αναλυτικές οδηγίες ακολουθούν στα αγγλικά. Για τη σύνδεση με ERP γενικά, δείτε τη σελίδα Σύνδεση ERP & API.
First 15 minutes
- Get your API key. For tests, we send you a key for the shared demo organization.
- Import the Postman collection and the "METACARD Demo" environment. Paste your key into
apiKey. Setpartnerto your company name. - Run "Look up a card" with a test card from the list below. You get the customer, the points and the rewards.
- Run the "Purchases" folder. It records a purchase, sends it again (a duplicate), and voids it.
- Send us your test webhook URL, or call
GET /changesto see the events your calls made. - Check the webhook signature with the Node or C# code below.
Basics
- Base URL:
https://loyalty.metacard.gr/api/integrations/v1 - Format: JSON in, JSON out. Send
Content-Type: application/jsonwith every body. - Money: integer cents in EUR. 12.50 € is
1250. - Time: ISO 8601 with a time zone, for example
2026-11-09T12:30:00+02:00. "Today" means the calendar day in Europe/Athens. - Card types: only POINTS cards work in v1. A STAMP card answers the lookup with
cardType: "stamp". Every other call on it returns422 card_type_not_supported. - Errors: every error has the same shape:
{"error": "<code>", "message": "<English sentence>"}. Your code should checkerror. The message may change.
Getting a key
The merchant's owner or admin creates the key in the METACARD dashboard: Settings → Organization → Developers → Create API key. The key starts with api_. It is shown only once, so copy it then. The same screen shows the base URL, lets you revoke a key, and adds webhooks.
One key belongs to one business. Every call only sees that business's cards. A card code of another business answers 404 card_not_found.
Keys for the demo organization expire after 90 days. Ask us for a new one.
Authentication
Send the key in every request:
Authorization: Bearer api_0123456789abcdef0123456789abcdef
A missing, wrong, expired or revoked key gets one answer, with the header WWW-Authenticate: Bearer:
HTTP/1.1 401 Unauthorized
{"error": "invalid_api_key", "message": "Missing or invalid API key. Send it as \"Authorization: Bearer <key>\"."}
Rate limits
| Limit | Value |
|---|---|
| Requests per key | 120 per minute |
| Requests per token, counted before the key is checked | 240 per minute |
| Failed sign-ins per IP address | 60 per minute |
Over a limit you get 429 rate_limited with the header Retry-After: 60. Wait that many seconds, then send the same request again.
Card codes
The QR on the Wallet card can hold three forms. Send any of them, as your scanner reads it:
- the bare code:
de300000-0000-4000-8000-000000002002 - with a prefix:
LOYALTY-de300000-0000-4000-8000-000000002002 - the full URL:
https://loyalty.metacard.gr/some-shop/card/de300000-0000-4000-8000-000000002002
Upper case and spaces around the code are fine. In a URL path, percent-encode the code, for example with encodeURIComponent. The answers always use the bare code, as cardCode.
Endpoints
| Method and path | What it does |
|---|---|
GET /cards/{code} |
Look up one card |
GET /cards?phone=... |
Find cards by phone number |
PUT /cards/{code}/link |
Save your customer id on a card |
POST /transactions |
Record a purchase and add points |
POST /transactions/{receiptId}/void |
Cancel a purchase and take its points back |
POST /redemptions |
Redeem a reward or a number of points |
GET /changes |
Read the list of events, for polling |
GET /cards/{code}
Looks up the card that the clerk scanned.
GET /cards/de300000-0000-4000-8000-000000002002
200 OK
{
"cardCode": "de300000-0000-4000-8000-000000002002",
"status": "active",
"customer": { "name": "Demo Πελάτης 2", "phone": "+30 6900000002", "email": null },
"externalCustomerId": null,
"cardType": "points",
"points": 75,
"nextReward": { "name": "Έκπτωση 10 €", "pointsNeeded": 25 },
"rewards": [
{ "id": "de300000-0000-4000-8000-000000000050", "name": "Δωρεάν καφές", "points": 50, "available": true },
{ "id": "de300000-0000-4000-8000-000000000100", "name": "Έκπτωση 10 €", "points": 100, "available": false },
{ "id": "de300000-0000-4000-8000-000000000500", "name": "Δωρεάν γεύμα για δύο", "points": 500, "available": false }
],
"visitsToday": 1,
"lastVisitAt": "2026-11-09T10:15:02.120Z"
}
rewardslists the active reward levels of the card.availableis true when the card has enough points.nextRewardis the first reward the card cannot take yet, ornull.visitsTodaycounts the purchases and other point gains of the Athens calendar day.lastVisitAtis the time of the last one.- If the customer asked us to delete their data,
name,phone,emailandexternalCustomerIdarenull. - Errors:
404 card_not_found.
GET /cards?phone=...
Finds cards by the customer's phone number. Use it when the customer has no phone with them.
GET /cards?phone=%2B30%206900000002
200 OK
{ "cards": [ { "cardCode": "de300000-0000-4000-8000-000000002002", "...": "same fields as GET /cards/{code}" } ] }
- Send at least 10 digits. We compare the last 10 digits, so
+30 690 000 0002and6900000002find the same card. - You get up to 5 cards, newest first. An empty list means no match.
- Errors:
400 invalid_requestwhen the number has fewer than 10 digits.
PUT /cards/{code}/link
Saves your own customer id on the card. You get it back in every lookup and can match the card to your customer.
PUT /cards/de300000-0000-4000-8000-000000002002/link
{ "externalCustomerId": "ERP-1001" }
- The answer is the card, as in
GET /cards/{code}. externalCustomerIdis 1 to 64 characters. Sending a new value replaces the old one.- A card whose customer asked us to delete their data cannot be linked. It answers
404 card_not_found. - Errors:
404 card_not_found,409 external_customer_in_usewhen another card of the business already has this id.
POST /transactions
Records a finished purchase and adds points. Send it after your receipt is issued.
POST /transactions
{
"cardCode": "de300000-0000-4000-8000-000000002002",
"externalReceiptId": "twinsoft-A-000123",
"purchasedAt": "2026-11-09T12:30:00+02:00",
"totalCents": 1250,
"discountCents": 100,
"points": 12,
"storeCode": "STORE-1",
"items": [
{ "sku": "ESP-01", "name": "Espresso", "category": "Coffee", "quantity": 2, "unitPriceCents": 675, "totalCents": 1350 }
]
}
| Field | Required | Rules |
|---|---|---|
cardCode |
yes | Any of the three card code forms |
externalReceiptId |
yes | 1 to 100 characters. Your receipt number. Start it with your company name. |
purchasedAt |
yes | ISO 8601 with a time zone. Not older than 90 days, and not more than 5 minutes in the future. |
totalCents |
yes | The amount the customer paid, after the discount. 0 to 10,000,000. |
discountCents |
no | The discount you gave. Default 0. |
points |
no | 0 to 100,000. If you send it, we add exactly this. If not, we calculate it from totalCents and the card's points per euro, rounded down. |
storeCode |
no | Up to 64 characters. Which store sold it. |
items |
no | Up to 200 lines. name and quantity (more than 0) are required. sku and category are optional. unitPriceCents and totalCents can be negative for discount lines. |
201 Created
{ "purchaseId": "3f1c2a9e-5b7d-4e10-9a61-2c8f0d4b7e55", "pointsAwarded": 12, "balance": 87 }
Sending the same receipt again is safe. It returns the same purchaseId and pointsAwarded, marked as a duplicate. No points are added twice. balance is the card's balance now.
200 OK
{ "purchaseId": "3f1c2a9e-5b7d-4e10-9a61-2c8f0d4b7e55", "pointsAwarded": 12, "balance": 87, "duplicate": true, "voided": false }
voided is true when the purchase was voided after it was recorded. The retry still answers 200 as a duplicate, and it does not add the points again. pointsAwarded is what the purchase earned before the void.
Errors:
409 receipt_conflict: this receipt id was already used with a different total, a different card, or a different API key.404 card_not_found422 card_type_not_supported: the card is a STAMP card.422 card_inactive: the card is expired or switched off.400 invalid_request: a field is missing or wrong, orpurchasedAtis outside the allowed window. The message names the field.
A purchase duplicate needs the same API key. After the merchant creates a new key, a purchase sent again with the new key answers 409 receipt_conflict, not a duplicate, and adds no points. So finish all retries of the old key's purchases before you revoke the old key.
POST /transactions/{receiptId}/void
Cancels a purchase, for a return or a cancelled receipt, and takes its points back. There is no body.
POST /transactions/twinsoft-A-000123/void
200 OK
{ "status": "voided", "pointsReversed": 12, "balance": 75 }
- Any active key of the business can void the purchase, also when the key that recorded it was revoked. We support one ERP per business.
- The balance never goes below 0. If the customer already spent the points,
pointsReversedsays how many we really took back. - Voiding again is safe. It answers
"status": "already_voided"with the samepointsReversed. - A voided receipt id stays used. For a corrected sale, send a new receipt id. Partial returns are not supported: void the whole receipt and send a new one.
- Sending a voided purchase again with
POST /transactionsanswers200as a duplicate with"voided": true. It adds no points. - Errors:
404 purchase_not_found,422 card_type_not_supported,400 invalid_requestwhen the receipt id is longer than 100 characters.
POST /redemptions
Takes points off the card, for a reward level or for a number of points. Send exactly one of rewardId or points.
POST /redemptions
{ "cardCode": "de300000-0000-4000-8000-000000002002", "externalReceiptId": "twinsoft-A-000124", "rewardId": "de300000-0000-4000-8000-000000000050" }
201 Created
{ "status": "redeemed", "pointsRedeemed": 50, "balance": 25, "rewardId": "de300000-0000-4000-8000-000000000050" }
POST /redemptions
{ "cardCode": "de300000-0000-4000-8000-000000002002", "externalReceiptId": "twinsoft-A-000125", "points": 10 }
rewardIdis theidof a reward from the card lookup.externalReceiptIdis the receipt where the reward was used. It can be the same id as a purchase: redemptions keep their own list.- Sending the same redemption again is safe if the points are the same. It answers
200with"status": "duplicate"and takes nothing off. - The same receipt id with a different number of points gives
409 redemption_conflict. - A
pointsredemption can take any number of points from 1 up to the balance. Cards have no minimum, so we no longer send422 below_minimum_redemption. - A repeat counts as a duplicate with any key of the business, so a retry after a key change does not take points off twice.
- We match a repeat by card. The same
externalReceiptIdon another card is a new redemption, not a duplicate.
Errors:
| Status and code | When | Extra fields |
|---|---|---|
422 insufficient_points |
The card has fewer points than needed | balance, needed |
409 redemption_conflict |
Same receipt id, different points | |
404 card_not_found |
||
404 reward_not_found |
No active reward with this id on the card | |
422 card_type_not_supported |
The card is a STAMP card | |
422 card_inactive |
The card is expired or switched off |
422 Unprocessable Entity
{ "error": "insufficient_points", "message": "The card does not have enough points for this redemption.", "balance": 25, "needed": 50 }
GET /changes
The list of events of the business, oldest first. Use it if you cannot receive webhooks, or to catch up after your webhook was down.
GET /changes?after=0&limit=100
200 OK
{
"events": [
{
"seq": 41,
"id": "eaf05891-0bff-4df1-8174-0b20b254b5cf",
"type": "pointsChanged",
"createdAt": "2026-11-09T10:15:02.120Z",
"data": { "cardCode": "de300000-0000-4000-8000-000000002002", "balance": 87, "delta": 12, "source": "api", "purchaseId": "3f1c2a9e-5b7d-4e10-9a61-2c8f0d4b7e55" }
}
],
"nextAfter": 41
}
afteris a cursor. Default 0.limitis 1 to 500. Default 100.- Save
nextAfterand send it back asafteron the next call. Wheneventsis empty, you have everything.nextAfterthen stays the same. - You may see an event twice, for example from a webhook and from this list. Ignore an event whose
idyou already have. datahas the same fields as the webhook payload. See below.- The list holds all events of the business: your calls, calls of other keys, and changes made in the dashboard.
Errors
| Status | error |
Meaning |
|---|---|---|
| 400 | invalid_request |
The body or a parameter is missing or wrong. The message names the field. |
| 401 | invalid_api_key |
The key is missing, wrong, expired or revoked. |
| 404 | card_not_found |
No card with this code in this business. |
| 404 | purchase_not_found |
No purchase with this receipt id for this business. |
| 404 | reward_not_found |
No active reward with this id on the card. |
| 409 | receipt_conflict |
The receipt id was used with another total, card or key. |
| 409 | redemption_conflict |
The receipt id was used for a redemption of other points. |
| 409 | external_customer_in_use |
Another card already has this externalCustomerId. |
| 422 | card_type_not_supported |
The card is a STAMP card. v1 supports POINTS cards only. |
| 422 | card_inactive |
The card is expired or switched off. |
| 422 | insufficient_points |
Not enough points. Has balance and needed. |
| 429 | rate_limited |
Too many requests. Wait for Retry-After seconds. |
| 500 | internal_error |
Our problem. Send the same request again later. |
Retries
Your till should never wait for us. If we do not answer, finish the sale and send the purchase later.
- Network error, timeout,
429or5xx: send the same request again, with the same receipt id. Wait a little longer each time. - Other
4xx: do not retry. Fix the request first. - Sending the same receipt again is always safe.
POST /transactionsanswers as a duplicate,voidanswersalready_voided, andPOST /redemptionsanswersduplicate. - Start every receipt id with your company name, for example
twinsoft-A-000123. Receipt ids must be unique within the business.
Webhooks
A webhook is a URL of yours. We send it a POST each time something changes in the business. The merchant adds it on the same Developers screen, with a secret and the events to send. For the demo organization, send us your test URL and we add it.
What we send
POST https://erp.example.com/metacard-hook
Content-Type: application/json
X-Webhook-Signature-256: 5d41b2d6...e3a9 (64 hex characters)
X-Webhook-Event-Id: cde9806d-73e3-46a5-b9e8-a545d32c072f
{
"trigger": "purchaseRecorded",
"createdAt": "2026-11-09T10:15:03.410Z",
"payload": {
"eventId": "cde9806d-73e3-46a5-b9e8-a545d32c072f",
"seq": 40,
"purchaseId": "3f1c2a9e-5b7d-4e10-9a61-2c8f0d4b7e55",
"cardCode": "de300000-0000-4000-8000-000000002002",
"externalReceiptId": "twinsoft-A-000123",
"purchasedAt": "2026-11-09T10:30:00.000Z",
"totalCents": 1250,
"discountCents": 100,
"pointsAwarded": 12,
"storeCode": "STORE-1"
}
}
payload.eventIdand the headerX-Webhook-Event-Idhold the same id. It is theidinGET /changes.payload.seqis itsseq.createdAtis the time of this send. A retry has a newcreatedAtand so a new signature.
Events
trigger |
When | payload fields, after eventId and seq |
|---|---|---|
purchaseRecorded |
A purchase was recorded through the API | purchaseId, cardCode, externalReceiptId, purchasedAt, totalCents, discountCents, pointsAwarded, storeCode |
pointsChanged |
The balance changed | cardCode, balance, delta, source, and one of purchaseId, externalReceiptId, rewardId |
contactCreated |
A customer signed up for a card | cardCode |
pointsChangedhassource: "api"for purchases, voids and redemptions through the API. It hassource: "dashboard"when staff changed the points in the dashboard. A purchase haspurchaseId. A void or a redemption hasexternalReceiptId. A reward redemption also hasrewardId.deltais negative when points were taken off.contactCreatedholds only thecardCode. Events hold no name, phone or email. To get the customer's details, callGET /cards/{code}.- When a customer asks us to erase their data, we delete the events about their cards. They no longer appear in
GET /changes. - The screen also offers
contactUpdatedandcontactDeleted. v1 does not send these yet.
Check the signature
X-Webhook-Signature-256 is the HMAC-SHA256 of the raw request body, keyed with the webhook's secret, written as 64 lower-case hex characters. There is no prefix.
- Compute it over the body bytes exactly as you received them, before you parse the JSON.
- Compare in constant time.
- Always set a secret. Without one, the header holds the text
no-secret-provided.
Node.js:
import { createHmac, timingSafeEqual } from 'node:crypto';
// rawBody: the request body exactly as received (a Buffer or string), before JSON.parse.
// signature: the X-Webhook-Signature-256 header. secret: the webhook's secret.
export function isValidSignature(rawBody, signature, secret) {
if (typeof signature !== 'string' || !/^[0-9a-f]{64}$/.test(signature)) return false;
const expected = createHmac('sha256', secret).update(rawBody).digest();
return timingSafeEqual(expected, Buffer.from(signature, 'hex'));
}
With Express, read the raw body: app.post('/metacard-hook', express.raw({ type: 'application/json' }), handler). Then req.body is a Buffer.
C# (.NET Framework 4.6+ and .NET 6 or later):
using System;
using System.Security.Cryptography;
using System.Text;
public static class MetacardWebhook
{
// rawBody: the request body bytes exactly as received, before you parse the JSON.
// signature: the X-Webhook-Signature-256 header. secret: the webhook's secret.
// Works on .NET Framework 4.6+ and on .NET 6 or later.
public static bool IsValidSignature(byte[] rawBody, string signature, string secret)
{
if (signature == null || signature.Length != 64) return false;
byte[] hash;
using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret)))
{
hash = hmac.ComputeHash(rawBody);
}
string expected = BitConverter.ToString(hash).Replace("-", "").ToLowerInvariant();
// Compare every character, so the time taken does not show where they differ.
int diff = 0;
for (int i = 0; i < 64; i++) diff |= expected[i] ^ signature[i];
return diff == 0;
}
}
In ASP.NET Core, copy Request.Body into a MemoryStream and use its bytes. In ASP.NET Web API 2, use await Request.Content.ReadAsByteArrayAsync().
Answer and retries
- Answer with any
2xxstatus within 10 seconds. Do the slow work after you answer. - A timeout, any other status, or a redirect counts as a failure. We do not follow redirects.
- We retry a failed send for about 4 hours, with longer waits each time, up to 15 minutes apart. After that we stop. Use
GET /changesto catch up. - The URL must be public and start with
https://. We refuse private and local addresses, and do not retry them. - Events can arrive twice or out of order. Ignore an event whose id you already handled. Use
seqfor the order. - A failing webhook never blocks the API call that caused the event.
The demo organization
For tests, we give each partner a key for "METACARD Demo ERP" (metacard-demo-erp). It has one POINTS card: 1 point per euro and rewards at 50, 100 and 500 points.
| Card code | Customer | Phone | Starting points |
|---|---|---|---|
de300000-0000-4000-8000-000000002001 |
Demo Πελάτης 1 | +30 6900000001 | 0 |
de300000-0000-4000-8000-000000002002 |
Demo Πελάτης 2 | +30 6900000002 | 75 |
de300000-0000-4000-8000-000000002003 |
Demo Πελάτης 3 | +30 6900000003 | 520 |
| Reward id | Reward | Points |
|---|---|---|
de300000-0000-4000-8000-000000000050 |
Δωρεάν καφές | 50 |
de300000-0000-4000-8000-000000000100 |
Έκπτωση 10 € | 100 |
de300000-0000-4000-8000-000000000500 |
Δωρεάν γεύμα για δύο | 500 |
- The demo organization is shared. Every partner sees all demo cards, all demo events in
GET /changes, and every webhook of the demo organization gets all demo events. - Do not send real customer data, real receipts or real phone numbers to it.
- Start your receipt ids with your company name, so they do not clash with another partner's. A purchase clash answers
409 receipt_conflict. Voids and redemptions are matched by business, not by key, so in the demo a clash there would touch another partner's receipt. - We reset the demo balances from time to time and delete demo purchases older than 7 days.
- Each partner has its own key. We can revoke one partner's key without touching the others.
Postman
The partner pack has a Postman collection, metacard-loyalty-api.postman_collection.json, and an environment, metacard-demo.postman_environment.json.
- Folders: Cards, Purchases, Redemptions, Changes, Webhook check.
- The collection sends
{{apiKey}}as the Bearer token. Paste your key into the environment. The file has no key. - "Record a purchase" makes a new receipt id on each run:
{{partner}}-<time>. - Each request checks the status code. Run the whole collection with the Collection Runner, or with
npx newman run.
An OpenAPI 3 file, openapi.yaml, describes the same API for code generators.