Ereignisse Ihrer Kasse empfangen
POST /v1/entrants/:jeton empfängt die Verkäufe aus Square, Shopify, SumUp, Zettle oder jedem anderen Tool und schreibt den Besuch dem richtigen Kunden gut.
/v1/entrants/:jetonEine Adresse, die Sie in Ihrer Kasse hinterlegen: Bei jedem bezahlten Verkauf ruft die Kasse sie auf, und StampyWallet schreibt den Besuch auf die Karte des Kunden, den es über seine E-Mail-Adresse oder Telefonnummer findet. Sie müssen keinen Schlüssel in die Kasse eintragen: Das Token in der Adresse genügt. Eine unbekannte oder widerrufene Adresse antwortet mit 404.
Die Quellen
Jede Adresse wird für eine Quelle unter Einstellungen › Integrationen erstellt, mit einem optionalen Signaturschlüssel. StampyWallet liest dann das Format dieser Kasse so, wie es ankommt:
| Quelle | Was zählt | Kunde | Betrag | Referenz |
|---|---|---|---|---|
square | payment.created / payment.updated mit Status COMPLETED | E-Mail des Käufers, oder E-Mail und Telefon des Kunden | Ohne Trinkgeld | Die ID der Zahlung |
shopify | orders/paid | E-Mail und Telefon des Kunden oder der Bestellung | Zwischensumme der Bestellung | Die ID der Bestellung |
sumup (Beta) | Transaktion PAID oder SUCCESSFUL | E-Mail oder Telefon | Betrag der Transaktion | Transaktionscode |
zettle (Beta) | PurchaseCreated | E-Mail oder Telefon des Kunden | Betrag des Kaufs | Die ID des Kaufs |
generique | Der Body von POST /v1/passages | client | montant | reference (optional) |
Hinweis : die Kassenquellen legen nie einen Kunden an: Ein Verkauf ohne bekannten Kunden wird ignoriert. Ein Verkauf ohne E-Mail und ohne Telefon, oder ohne Referenz, wird ebenfalls ignoriert. Nur die Quelle generique kann einen Kunden anlegen, mit creer_si_absent: true.
Die Signatur
Ist für die Adresse ein Signaturschlüssel hinterlegt, muss jeder Aufruf signiert sein, sonst 401 signature_invalide. Fügen Sie ihn immer ein, wenn die Kasse einen bereitstellt.
| Quelle | Header | Signatur |
|---|---|---|
generique | X-Stampy-Signature | HMAC-SHA256 hexadezimal über den Roh-Body, mit dem Schlüssel der Adresse (sha256= davor wird akzeptiert) |
square | x-square-hmacsha256-signature | HMAC-SHA256 Base64 über die Benachrichtigungs-URL, gefolgt vom Roh-Body |
shopify | X-Shopify-Hmac-Sha256 | HMAC-SHA256 Base64 über den Roh-Body |
sumup | X-Payload-Signature | HMAC-SHA256 hexadezimal über den Roh-Body |
zettle | X-iZettle-Signature | HMAC-SHA256 hexadezimal über timestamp + "." + payload |
Das generische Format
Für ein Skript, ein No-Code-Tool oder eine Kasse ohne bekanntes Format senden Sie denselben Body wie bei POST /v1/passages:
corps='{"client": {"telephone": "+33612345678"}, "montant": 18.9, "reference": "T-2026-1025-0091"}'
signature=$(printf '%s' "$corps" | openssl dgst -sha256 -hmac "$STAMPY_ENTRANT_SECRET" | sed 's/^.* //')
curl https://app.stampywallet.com/v1/entrants/9QkT2vX7pL4mR8sN1bC6dF3gH5jK0wYz \
-H "Content-Type: application/json" \
-H "X-Stampy-Signature: $signature" \
-d "$corps"const crypto = require('node:crypto');
const corps = JSON.stringify({ client: { telephone: '+33612345678' }, montant: 18.9, reference: 'T-2026-1025-0091' });
const signature = crypto.createHmac('sha256', process.env.STAMPY_ENTRANT_SECRET).update(corps).digest('hex');
await fetch(process.env.STAMPY_ENTRANT_URL, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Stampy-Signature': signature },
body: corps,
});Die Antworten
Sobald der Aufruf authentifiziert ist, lautet die Antwort immer 200, damit die Kasse nichts über Ihren Kundenstamm erfährt:
{ "ok": true, "ignore": true }: Das Ereignis betrifft uns nicht (nicht bezahlt, anderes Thema, ohne Kunde, oder bei einer Kasse ohne Referenz);{ "ok": true }: in allen anderen Fällen, ob der Kunde existiert oder nicht, ob der Besuch gutgeschrieben oder abgelehnt wurde (zu früh, Betrag zu klein).
Nur eine echte Störung antwortet mit 500: Die Kasse versucht es erneut, und die Referenz stellt sicher, dass ein neuer Versuch nicht zweimal stempelt. Jede Adresse nimmt 300 Aufrufe pro Minute an.
Die Einstellungen Schritt für Schritt, Kasse für Kasse: Kasse anbinden.