Recibir los eventos de tu TPV
POST /v1/entrants/:jeton recibe las ventas de Square, Shopify, SumUp, Zettle o de cualquier herramienta, y añade la visita al cliente correcto.
/v1/entrants/:jetonUna dirección que darle a tu TPV: en cada venta pagada, el TPV la llama y StampyWallet añade la visita a la tarjeta del cliente, encontrado por su correo o su teléfono. No hay clave que escribir en el TPV: basta con el token de la dirección. Una dirección desconocida o revocada responde 404.
Las fuentes
Cada dirección se crea para una fuente en Ajustes › Integraciones, con una clave de firma opcional. StampyWallet lee entonces el formato de ese TPV tal cual:
| Fuente | Lo que cuenta | Cliente | Importe | Referencia |
|---|---|---|---|---|
square | payment.created / payment.updated con estado COMPLETED | Correo del comprador, o correo y teléfono del cliente | Sin propina | El id del pago |
shopify | orders/paid | Correo y teléfono del cliente o del pedido | Subtotal del pedido | El id del pedido |
sumup (beta) | Transacción PAID o SUCCESSFUL | Correo o teléfono | Importe de la transacción | Código de transacción |
zettle (beta) | PurchaseCreated | Correo o teléfono del cliente | Importe de la compra | El id de la compra |
generique | El cuerpo de POST /v1/passages | client | montant | reference (opcional) |
Nota : las fuentes de los TPV nunca crean clientes: una venta sin cliente conocido se ignora. Una venta sin correo ni teléfono, o sin referencia, también se ignora. Solo la fuente generique puede crear un cliente, con creer_si_absent: true.
La firma
Cuando hay una clave de firma guardada para la dirección, cada llamada debe ir firmada; si no, 401 signature_invalide. Pégala siempre que el TPV proporcione una.
| Fuente | Cabecera | Firma |
|---|---|---|
generique | X-Stampy-Signature | HMAC-SHA256 hexadecimal del cuerpo sin procesar, con la clave de la dirección (se acepta sha256= delante) |
square | x-square-hmacsha256-signature | HMAC-SHA256 base64 de la URL de notificación seguida del cuerpo sin procesar |
shopify | X-Shopify-Hmac-Sha256 | HMAC-SHA256 base64 del cuerpo sin procesar |
sumup | X-Payload-Signature | HMAC-SHA256 hexadecimal del cuerpo sin procesar |
zettle | X-iZettle-Signature | HMAC-SHA256 hexadecimal de timestamp + "." + payload |
El formato genérico
Para un script, una herramienta sin código o un TPV sin formato conocido, envía el mismo cuerpo 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,
});Las respuestas
Una vez autenticada la llamada, la respuesta es siempre 200, para que el TPV no averigüe nada de tu fichero de clientes:
{ "ok": true, "ignore": true }: el evento no nos concierne (no pagado, otro asunto, sin cliente, o sin referencia en el caso de un TPV);{ "ok": true }: en todos los demás casos, exista o no el cliente, y se haya puesto o rechazado la visita (demasiado pronto, importe demasiado bajo).
Solo una avería real responde 500: el TPV reintenta, y la referencia garantiza que un nuevo intento no sella dos veces. Cada dirección acepta 300 llamadas por minuto.
Los ajustes paso a paso, TPV por TPV: Conectar tu TPV.
Actualizado el