POS integration · Digikart API

Version 1 · for POS vendors, integrators and middleware

This API lets POS software send every sale to Digikart: the customer's Apple Wallet / Google Wallet loyalty card is credited (stamp or points depending on the business) and updated on their phone in real time, with nothing for staff to re-enter.

1. Authentication

Every Digikart business has an API key generated from its dashboard (My account → POS connection). It is sent in the HTTP header:

Authorization: Bearer dk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The key belongs to one business: it can only credit that business's cards. It can be revoked or regenerated by the merchant at any time.

2. Test the connection

GEThttps://digikart.fr/api/pos/ping

curl https://digikart.fr/api/pos/ping \
  -H "Authorization: Bearer dk_live_..."

→ { "ok": true, "business": "Bar Bichette", "mode": "points", "pointsRate": 1 }

mode vaut "stamps" (stamps: 1 visit = 1 stamp) or "points" (points calculated from the receipt amount).

3. Credit a sale

POSThttps://digikart.fr/api/pos/transaction

Champ	Type	Description
`card`	string*	The customer's card identifier: the contents of the barcode / QR shown on their Wallet card (a serial number, or a URL `/c/<serial>`, both are accepted).
`phone`	string*	Alternative to scanning: the phone number the customer gave when installing their card (useful for tills and kiosks without a 2D reader). Accepted formats: `06 12 34 56 78` or `+33612345678`. * `card` or `phone` : one of the two is required.
`amount`	number	Receipt amount in euros. Required if the business is in points mode (it is what determines the points). Optional in stamps mode (recorded for the merchant's statistics).
`transaction_id`	string	Unique receipt identifier on the POS side. Strongly recommended : it guarantees idempotency (see §4).

Example: business in points mode

curl -X POST https://digikart.fr/api/pos/transaction \
  -H "Authorization: Bearer dk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "card": "A1B2C3D4E5", "amount": 23.80, "transaction_id": "TICKET-20260715-0042" }'

→ {
    "ok": true, "mode": "points",
    "serial": "A1B2C3D4E5", "name": "Marie D.",
    "stamps": 61,            // solde de points après crédit
    "pointsAdded": 24,       // arrondi de 23,80 € × taux du commerce
    "rewardUnlocked": false,
    "claimable": null        // ou { threshold, reward } si un palier est atteint
  }

Example: business in stamps mode

curl -X POST https://digikart.fr/api/pos/transaction \
  -H "Authorization: Bearer dk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "card": "A1B2C3D4E5", "transaction_id": "TICKET-20260715-0043" }'

→ { "ok": true, "mode": "stamps", "stamps": 7, "stampsRequired": 10, "rewardUnlocked": false }

As soon as the response arrives, the customer's Wallet card is updated on their phone (Apple push / Google API): nothing else to do on the POS side.

4. Idempotency (replayed receipts)

If a transaction carrying a transaction_id that has already been processed is sent again (network retry, replayed webhook), Digikart does not credit a second time : the original response is returned, with "duplicate": true. Use your POS receipt identifier, which stays stable between retries.

5. Errors

HTTP	`code`	Signification
400	`invalid_request`	Invalid request body.
400	`amount_required`	The business is in points mode: `amount` is required.
401	`unauthorized`	Key missing, unknown or revoked.
402	`subscription_required`	The business's Digikart subscription is not active.
403	`wrong_merchant`	The card belongs to another business.
404	`card_not_found` / `phone_not_found`	Unknown card, or no customer with that number at this business.
429	`too_soon` / `rate_limited`	Close duplicate without `transaction_id`, or more than 120 requests per minute.

On error, nothing is written: the transaction can safely be sent again.

6. Typical flow at the till

The customer shows their Digikart card (Apple/Google Wallet): the till scans its barcode.
At checkout, the till calls POST /api/pos/transaction with the card, the amount and the receipt identifier.
The customer's card updates instantly on their phone.

7. Integrator contact

POS vendor, integrator, middleware (HubRise, etc.): write to us at contact@digikart.fr : we are glad to support integrations.