Μετάβαση στο περιεχόμενο

METACARD Loyalty API v1

Στα ελληνικά, με λίγα λόγια

Αυτό το API συνδέει το ERP ή το POS σας με τις κάρτες πιστότητας METACARD στο Apple Wallet και στο Google Wallet.

Τι κάνει το ταμείο σας:

  1. Σκανάρει το QR της κάρτας και ζητά από εμάς τον πελάτη, τους πόντους και τις ανταμοιβές του.
  2. Μετά την απόδειξη, μας στέλνει την αγορά. Εμείς προσθέτουμε τους πόντους και ενημερώνουμε την κάρτα στο κινητό.
  3. Ακυρώνει μια αγορά ή εξαργυρώνει μια ανταμοιβή, πάλι με ένα αίτημα.

Αν η ίδια απόδειξη σταλεί δύο φορές, δεν γίνεται τίποτα διπλό. Μπορείτε να ξαναστείλετε με ασφάλεια όταν χαθεί η σύνδεση.

Το κλειδί API το δημιουργεί ο ιδιοκτήτης ή ο διαχειριστής της επιχείρησης, στο Ρυθμίσεις → Επιχείρηση → Προγραμματιστές. Το κλειδί εμφανίζεται μόνο μία φορά.

Για δοκιμές σας δίνουμε κλειδί για τη δοκιμαστική επιχείρηση "METACARD Demo ERP". Τη μοιράζονται όλοι οι συνεργάτες, οπότε μη βάζετε εκεί πραγματικά στοιχεία.

Οι αναλυτικές οδηγίες ακολουθούν στα αγγλικά. Για τη σύνδεση με ERP γενικά, δείτε τη σελίδα Σύνδεση ERP & API.

First 15 minutes

  1. Get your API key. For tests, we send you a key for the shared demo organization.
  2. Import the Postman collection and the "METACARD Demo" environment. Paste your key into apiKey. Set partner to your company name.
  3. Run "Look up a card" with a test card from the list below. You get the customer, the points and the rewards.
  4. Run the "Purchases" folder. It records a purchase, sends it again (a duplicate), and voids it.
  5. Send us your test webhook URL, or call GET /changes to see the events your calls made.
  6. 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/json with 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 returns 422 card_type_not_supported.
  • Errors: every error has the same shape: {"error": "<code>", "message": "<English sentence>"}. Your code should check error. 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"
}
  • rewards lists the active reward levels of the card. available is true when the card has enough points.
  • nextReward is the first reward the card cannot take yet, or null.
  • visitsToday counts the purchases and other point gains of the Athens calendar day. lastVisitAt is the time of the last one.
  • If the customer asked us to delete their data, name, phone, email and externalCustomerId are null.
  • 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 0002 and 6900000002 find the same card.
  • You get up to 5 cards, newest first. An empty list means no match.
  • Errors: 400 invalid_request when 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}.
  • externalCustomerId is 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_use when 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_found
  • 422 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, or purchasedAt is 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, pointsReversed says how many we really took back.
  • Voiding again is safe. It answers "status": "already_voided" with the same pointsReversed.
  • 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 /transactions answers 200 as a duplicate with "voided": true. It adds no points.
  • Errors: 404 purchase_not_found, 422 card_type_not_supported, 400 invalid_request when 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 }
  • rewardId is the id of a reward from the card lookup.
  • externalReceiptId is 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 200 with "status": "duplicate" and takes nothing off.
  • The same receipt id with a different number of points gives 409 redemption_conflict.
  • A points redemption can take any number of points from 1 up to the balance. Cards have no minimum, so we no longer send 422 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 externalReceiptId on 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
}
  • after is a cursor. Default 0. limit is 1 to 500. Default 100.
  • Save nextAfter and send it back as after on the next call. When events is empty, you have everything. nextAfter then stays the same.
  • You may see an event twice, for example from a webhook and from this list. Ignore an event whose id you already have.
  • data has 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, 429 or 5xx: 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 /transactions answers as a duplicate, void answers already_voided, and POST /redemptions answers duplicate.
  • 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.eventId and the header X-Webhook-Event-Id hold the same id. It is the id in GET /changes. payload.seq is its seq.
  • createdAt is the time of this send. A retry has a new createdAt and 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
  • pointsChanged has source: "api" for purchases, voids and redemptions through the API. It has source: "dashboard" when staff changed the points in the dashboard. A purchase has purchaseId. A void or a redemption has externalReceiptId. A reward redemption also has rewardId.
  • delta is negative when points were taken off.
  • contactCreated holds only the cardCode. Events hold no name, phone or email. To get the customer's details, call GET /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 contactUpdated and contactDeleted. 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 2xx status 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 /changes to 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 seq for 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.