Recevoir les événements de votre caisse
POST /v1/entrants/:jeton reçoit les ventes de Square, Shopify, SumUp, Zettle ou de n'importe quel outil, et ajoute le passage au bon client.
/v1/entrants/:jetonUne adresse à donner à votre caisse : à chaque vente payée, la caisse l'appelle, et StampyWallet ajoute le passage à la carte du client, retrouvé par son e-mail ou son téléphone. Pas de clé à écrire dans la caisse : le jeton de l'adresse suffit. Une adresse inconnue ou révoquée répond 404.
Les sources
Chaque adresse est créée pour une source dans Réglages › Intégrations, avec une clé de signature facultative. StampyWallet lit alors le format de cette caisse tel quel :
| Source | Ce qui compte | Client | Montant | Référence |
|---|---|---|---|---|
square | payment.created / payment.updated au statut COMPLETED | E-mail de l'acheteur, ou e-mail et téléphone du client | Hors pourboire | L'id du paiement |
shopify | orders/paid | E-mail et téléphone du client ou de la commande | Sous-total de la commande | L'id de la commande |
sumup (bêta) | Transaction PAID ou SUCCESSFUL | E-mail ou téléphone | Montant de la transaction | Code de transaction |
zettle (bêta) | PurchaseCreated | E-mail ou téléphone du client | Montant de l'achat | L'id de l'achat |
generique | Le corps de POST /v1/passages | client | montant | reference (facultative) |
Note : les sources des caisses ne créent jamais de client : une vente sans client connu est ignorée. Une vente sans e-mail ni téléphone, ou sans référence, est ignorée aussi. Seule la source generique peut créer un client, avec creer_si_absent: true.
La signature
Quand une clé de signature est enregistrée pour l'adresse, chaque appel doit être signé, sinon 401 signature_invalide. Collez-la toujours quand la caisse en fournit une.
| Source | En-tête | Signature |
|---|---|---|
generique | X-Stampy-Signature | HMAC-SHA256 hexadécimal du corps brut, avec la clé de l'adresse (sha256= accepté devant) |
square | x-square-hmacsha256-signature | HMAC-SHA256 base64 de l'URL de notification suivie du corps brut |
shopify | X-Shopify-Hmac-Sha256 | HMAC-SHA256 base64 du corps brut |
sumup | X-Payload-Signature | HMAC-SHA256 hexadécimal du corps brut |
zettle | X-iZettle-Signature | HMAC-SHA256 hexadécimal de timestamp + "." + payload |
Le format générique
Pour un script, un outil sans code ou une caisse sans format connu, envoyez le même corps que 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,
});Les réponses
Une fois l'appel authentifié, la réponse est toujours 200, pour que la caisse n'apprenne rien de votre fichier de clients :
{ "ok": true, "ignore": true }: l'événement ne nous concerne pas (non payé, autre sujet, sans client, ou sans référence pour une caisse) ;{ "ok": true }: dans tous les autres cas, que le client existe ou non, que le passage soit posé ou refusé (trop tôt, montant trop petit).
Seule une vraie panne répond 500 : la caisse réessaie, et la référence garantit qu'un nouvel essai ne tamponne pas deux fois. Chaque adresse accepte 300 appels par minute.
Les réglages pas à pas, caisse par caisse : Relier votre caisse.
Mis à jour le