La fidélité Sourdi, intégrée à votre checkout.

Démarrage rapide

L’API est disponible pour les commerces actifs ayant un programme de fidélité à tampons ou à points.

Authentification

Transmettez la clé avec le schéma Bearer dans l’en-tête Authorization. Les clés dans l’URL ou le corps sont refusées.

Authorization: Bearer sourdi_live_KEY_ID.API_SECRET
Content-Type: application/json

Checkout d’une carte à tampons

À la confirmation du paiement, votre serveur demande un stamp_code signé. Le QR est lié à votre commerce, expire après 10 minutes par défaut et ne peut être validé qu’une fois.

Requête serveur

curl --request POST "/api/v1/checkout/stamps" \
  --header "Authorization: Bearer $SOURDI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "stamps": 2,
    "transaction_id": "order-2026-000184"
  }'

Réponse — HTTP 201

{
  "status": true,
  "data": {
    "reward_type": "stamps",
    "stamps": 2,
    "stamp_code": "sourdi_checkout_v1.…",
    "transaction_id": "order-2026-000184",
    "expires_at": "2026-08-14T12:10:00.000Z",
    "qr": {
      "data": "sourdi_checkout_v1.…",
      "image_data_url": "data:image/png;base64,iVBOR…"
    }
  },
  "idempotent_replay": false
}

Checkout d’une carte à points

Pour une carte à points, le checkout retourne un QR adapté au solde de crédits. Le client le scanne avec la même fonctionnalité de scan de l’application ; les points sont ajoutés après validation serveur.

Requête serveur

curl --request POST "/api/v1/checkout/points" \
  --header "Authorization: Bearer $SOURDI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "points": 25,
    "transaction_id": "order-2026-000185",
    "purchases": ["PRODUCT-001", "PRODUCT-002"]
  }'

Réponse — HTTP 201

{
  "status": true,
  "data": {
    "reward_type": "points",
    "points": 25,
    "transaction_id": "order-2026-000185",
    "expires_at": "2026-08-14T12:10:00.000Z",
    "qr": {
      "data": "sourdi_checkout_v1.…",
      "image_data_url": "data:image/png;base64,iVBOR…"
    }
  },
  "idempotent_replay": false
}

Afficher le QR sur la page de confirmation

Votre backend appelle Sourdi avec la clé secrète, puis renvoie uniquement data.qr.image_data_url à votre navigateur. L’exemple suivant suppose que votre propre endpoint /api/order/reward effectue cet appel serveur-à-serveur.

Alternative : transaction directe de points

Une caisse qui lit déjà l’identifiant de carte peut créditer ou débiter le solde sans afficher de QR. Cette route est réservée aux programmes à points.

curl --request POST "/api/v1/points/transactions" \
  --header "Authorization: Bearer $SOURDI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "card_id": "66b8a42f9759d5ee8c90c123",
    "points": -20,
    "transaction_id": "ticket-2026-000186"
  }'

Retries, expiration et usage unique

En cas de coupure réseau, renvoyez exactement la même requête avec le même transaction_id. Tant que le QR est valide et inutilisé, l’API retourne le même QR avec HTTP 200 et idempotent_replay: true.

Un transaction_id ne peut pas être réutilisé avec un autre type, montant ou panier. Après expiration, créez une nouvelle opération avec un nouvel identifiant. Dès qu’un QR est scanné, toute nouvelle tentative est refusée globalement, même depuis une autre carte.

Erreurs

Bonnes pratiques de sécurité

• Appelez l’API exclusivement depuis votre serveur ou un terminal sécurisé, toujours en HTTPS.
• N’insérez jamais la clé dans le JavaScript du navigateur, une application mobile, Git, les logs ou les outils d’analytics.
• Masquez les en-têtes Authorization et les données QR dans les journaux.
• Rendez le QR uniquement après confirmation effective du paiement et ne le placez pas dans une page mise en cache.
• Révoquez immédiatement une clé suspectée d’avoir fuité, puis générez-en une nouvelle.
• Utilisez un transaction_id unique par commerce et conservez-le avec la commande.