Retour au blog

Notifications de paiement Stripe : une notification push pour chaque vente, paiement échoué et litige

Notifications de paiement Stripe : une notification push pour chaque vente, paiement échoué et litige

La première vente de la journée est celle dont vous voulez être informé. Le renouvellement échoué à 2 h du matin compte davantage, et un litige a une échéance : si vous ne répondez pas à temps, vous le perdez. Stripe est au courant des trois dès qu'ils se produisent. Vous ne l'apprenez qu'à votre prochaine ouverture du tableau de bord.

Stripe propose ses propres notifications. L'application Stripe Dashboard pour iOS et Android peut envoyer des notifications push pour les nouveaux paiements, les nouveaux clients, les paiements contestés, les virements déposés et un récapitulatif quotidien, et le tableau de bord peut vous envoyer des e-mails pour les événements de votre compte. Cela couvre beaucoup de choses. Ce qui manque, c'est le contrôle : vous ne pouvez pas choisir la formulation, ni rendre une facture impayée plus visible qu'une vente, ni faire parvenir dans le même flux les événements de vos propres systèmes. Un webhook qui va de Stripe vers Pocket Alert le permet.

Ce dont vous avez besoin

  • Un compte Stripe avec l'autorisation de créer des webhooks (rôle Administrateur ou Développeur).
  • Un compte Pocket Alert, une clé API depuis Clés API et l'application sur votre téléphone iPhone ou Android.
  • Pour la voie avec code : Node 20 ou plus récent, et un endroit accessible publiquement pour l'exécuter.

Niveau 1 : sans code

Stripe envoie chaque événement au format JSON, et les webhooks Pocket Alert acceptent le JSON et le rendent à partir d'un modèle. C'est toute la plomberie nécessaire.

1. Créez un webhook Pocket Alert par type d'événement

L'astuce consiste à créer un webhook par type d'événement. Le titre de la notification est toujours Webhook <name>, donc le nom détermine ce que vous voyez sur l'écran verrouillé, et chaque webhook a sa propre priorité par défaut et ses propres boutons. L'offre gratuite inclut un webhook : commencez donc par les ventes. Les quatre webhooks nécessitent une offre payante, qui débloque aussi les boutons.

Vous pouvez créer les webhooks dans la console, sur Webhooks, où l'on définit le nom, le modèle et la priorité par défaut. Les boutons d'action se configurent via l'API : le plus rapide pour tout faire d'un coup est un appel curl par webhook :

export PA_KEY='YOUR_API_KEY'

curl -sS https://api.pocketalert.app/v1/webhooks \
  -H "Token: $PA_KEY" \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'EOF'
{
  "name": "Stripe sale",
  "message": "%data.object.amount_total% %data.object.currency% from %data.object.customer_details.email% (%data.object.payment_status%)",
  "default_level": 0,
  "actions": "[{\"type\":\"view\",\"label\":\"Open in Stripe\",\"value\":\"https://dashboard.stripe.com/payments/%data.object.payment_intent%\"}]"
}
EOF

La réponse contient un identifiant url. Votre URL de réception est https://p4a.me/wh/<slug>, que la console affiche également. actions est une chaîne JSON et non un tableau, d'où les guillemets échappés.

Répétez l'opération avec ces corps pour les trois autres :

{
  "name": "Stripe payment failed",
  "message": "%data.object.amount_due% %data.object.currency% failed for %data.object.customer_email%, attempt %data.object.attempt_count%",
  "default_level": 1,
  "actions": "[{\"type\":\"view\",\"label\":\"Open invoice\",\"value\":\"https://dashboard.stripe.com/invoices/%data.object.id%\"},{\"type\":\"copy\",\"label\":\"Copy pay link\",\"value\":\"%data.object.hosted_invoice_url%\"}]"
}
{
  "name": "Stripe dispute",
  "message": "%data.object.amount% %data.object.currency% disputed. Reason: %data.object.reason%",
  "default_level": 2,
  "actions": "[{\"type\":\"view\",\"label\":\"Open payment\",\"value\":\"https://dashboard.stripe.com/payments/%data.object.payment_intent%\"}]"
}
{
  "name": "Stripe subscription",
  "message": "New %data.object.status% subscription: %data.object.items.data.0.price.unit_amount% %data.object.currency% per %data.object.items.data.0.price.recurring.interval%",
  "default_level": -1,
  "actions": "[{\"type\":\"view\",\"label\":\"Open subscription\",\"value\":\"https://dashboard.stripe.com/subscriptions/%data.object.id%\"}]"
}

Les niveaux vont de -2 (silencieux) à 2 (critique). Un paiement échoué est high, ce qui le fait passer le mode Concentration sur iPhone. Un litige est critical, qui sonne même avec le commutateur silencieux et en mode Ne pas déranger. Les alertes critiques nécessitent une offre payante ; sur l'offre gratuite, elles arrivent en high. Les nouveaux abonnements sont en low : bon à savoir, mais aucune raison de faire vibrer le téléphone.

Le bouton de copie sur la notification de paiement échoué place le lien de paiement hébergé de la facture dans votre presse-papiers, prêt à être collé dans un e-mail du type « votre carte a été refusée ».

2. Ajoutez des destinations d'événements dans Stripe

Dans le tableau de bord Stripe, ouvrez Workbench, allez dans l'onglet Webhooks et cliquez sur Créer une destination d'événements. Ensuite :

  1. Choisissez Votre compte.
  2. Sélectionnez la charge utile Snapshot. Stripe recommande désormais Thin pour le nouveau code, mais un événement thin ne contient que l'identifiant de l'objet : le modèle n'aurait donc ni montant ni e-mail à afficher. Snapshot envoie l'objet complet.
  3. Sélectionnez l'événement, par exemple checkout.session.completed.
  4. Choisissez Webhook endpoint comme type de destination et collez l'URL https://p4a.me/wh/... correspondante.

Faites-le une fois par webhook Pocket Alert, afin que chaque destination Stripe n'envoie qu'un type d'événement vers une seule URL :

Événement StripeWebhook Pocket AlertTitre de la notificationNiveau
checkout.session.completedStripe saleWebhook Stripe saledefault
invoice.payment_failedStripe payment failedWebhook Stripe payment failedhigh
charge.dispute.createdStripe disputeWebhook Stripe disputecritical
customer.subscription.createdStripe subscriptionWebhook Stripe subscriptionlow

Stripe autorise 16 destinations d'événements par compte, donc quatre suffisent largement.

Checkout ou PaymentIntents ? Si vos clients paient via Checkout ou des liens de paiement, utilisez checkout.session.completed. Si vous avez votre propre formulaire de paiement, utilisez plutôt payment_intent.succeeded et remplacez le modèle par %data.object.amount% %data.object.currency% %data.object.receipt_email% et le bouton par /payments/%data.object.id%. Vous abonner aux deux vous enverrait deux notifications par vente, car un paiement Checkout déclenche les deux événements.

3. Testez

Créez un paiement de test dans un bac à sable, ou lancez stripe trigger checkout.session.completed avec la CLI Stripe. Ouvrez ensuite le webhook dans la console Pocket Alert : son historique affiche chaque requête envoyée par Stripe, avec les en-têtes, le corps brut, le message rendu et le code de réponse. Si un champ apparaît vide, c'est là que vous voyez quel chemin était faux.

Une vente s'affiche ainsi :

Webhook Stripe sale
4900 usd from [email protected] (paid)
[Open in Stripe]

Ce que le modèle ne peut pas faire

Soyez clair sur les limites avant de vous y fier :

  • Les montants sont en unités mineures. Stripe envoie 4900 pour 49,00 $ et 5000 pour ¥5 000, car le yen n'a pas de centimes. Le modèle copie les valeurs telles quelles et ne peut pas diviser par 100. On s'habitue vite à lire 4900 usd, mais si vous voulez $49.00, utilisez le niveau 2.
  • Pas de vérification de signature. Stripe signe chaque requête avec un en-tête Stripe-Signature. Pocket Alert ne vérifie pas les signatures de tiers : le slug aléatoire de l'URL est le seul secret. Quiconque le connaît peut vous envoyer de fausses « ventes ». Pour une notification, c'est une gêne et non une faille, puisque rien n'est exécuté. Gardez tout de même l'URL privée, et utilisez le niveau 2 si vous avez besoin de prouver qu'une notification vient bien de Stripe.
  • Pas de conditions. Un modèle ne peut pas dire « envoyer seulement les ventes supérieures à 500 $ » ni « ignorer le mode test ». Le filtrage se fait dans Stripe, via les événements choisis, ou dans le code.
  • Les boutons du tableau de bord pointent vers le mode réel. Les objets de test se trouvent sous dashboard.stripe.com/test/... : pour un événement en mode test, le bouton ouvre donc une page inexistante. Les litiges issus de l'ancienne API Charges n'ont pas de payment_intent, ce qui laisse ce bouton avec un lien vide.
  • Les abonnements n'affichent que le premier prix. items.data.0 correspond à la première ligne de l'abonnement. L'événement contient un identifiant client, et non un e-mail.
  • Chaque événement compte dans votre quota quotidien. L'offre gratuite autorise 50 messages par jour. Au-delà, Pocket Alert répond 429, et Stripe considère cela comme une livraison échouée et, en mode réel, réessaie pendant trois jours au maximum.

Niveau 2 : un petit gestionnaire vérifié

Lorsque vous voulez un vrai formatage des devises, la vérification des signatures et un seul point d'entrée pour tous les événements, placez une soixantaine de lignes de Node entre Stripe et Pocket Alert. Il utilise la bibliothèque officielle de Stripe pour vérifier la signature et POST /v1/messages pour envoyer la notification.

npm install express stripe
// server.mjs
import express from 'express';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const app = express();

function money(minor, currency) {
  const fmt = new Intl.NumberFormat('en-US', { style: 'currency', currency: currency.toUpperCase() });
  return fmt.format(minor / 10 ** fmt.resolvedOptions().maximumFractionDigits);
}

function toPush(event) {
  const o = event.data.object;
  switch (event.type) {
    case 'checkout.session.completed':
      return { title: `Sale ${money(o.amount_total, o.currency)}`, level: 'default',
        message: `${o.customer_details?.email ?? 'no email'} · ${o.payment_status}`,
        path: o.payment_intent ? `payments/${o.payment_intent}` : `customers/${o.customer}` };
    case 'invoice.payment_failed':
      return { title: `Payment failed ${money(o.amount_due, o.currency)}`, level: 'high',
        message: `${o.customer_email ?? o.customer} · attempt ${o.attempt_count}`,
        path: `invoices/${o.id}` };
    case 'charge.dispute.created':
      return { title: `Dispute ${money(o.amount, o.currency)}`, level: 'critical',
        message: `Reason: ${o.reason}. Evidence due ${new Date(o.evidence_details.due_by * 1000).toDateString()}`,
        path: `payments/${o.payment_intent ?? o.charge}` };
    case 'customer.subscription.created': {
      const price = o.items.data[0]?.price;
      return { title: 'New subscription', level: 'low',
        message: price?.unit_amount != null
          ? `${money(price.unit_amount, price.currency)} per ${price.recurring?.interval} · ${o.status}`
          : o.status,
        path: `subscriptions/${o.id}` };
    }
  }
  return null;
}

app.post('/stripe-webhook', express.raw({ type: 'application/json' }), async (req, res) => {
  let event;
  try {
    event = stripe.webhooks.constructEvent(req.body, req.headers['stripe-signature'], process.env.STRIPE_WEBHOOK_SECRET);
  } catch (err) {
    return res.status(400).send(`Bad signature: ${err.message}`);
  }
  res.sendStatus(200);

  const push = toPush(event);
  if (!push) return;
  const dashboard = event.livemode ? 'https://dashboard.stripe.com/' : 'https://dashboard.stripe.com/test/';

  await fetch('https://api.pocketalert.app/v1/messages', {
    method: 'POST',
    headers: { Token: process.env.POCKETALERT_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      title: push.title,
      message: push.message,
      level: push.level,
      actions: [{ type: 'view', label: 'Open in Stripe', value: dashboard + push.path }],
    }),
  }).catch((err) => console.error('Pocket Alert:', err.message));
});

app.listen(process.env.PORT ?? 4242);
STRIPE_SECRET_KEY=sk_live_... STRIPE_WEBHOOK_SECRET=whsec_... POCKETALERT_KEY=... node server.mjs

Les points importants :

  • express.raw conserve le corps sous forme d'octets. constructEvent a besoin de la requête exactement telle que Stripe l'a envoyée, et un analyseur JSON la casserait. Il rejette aussi les événements de plus de cinq minutes, ce qui empêche les rejeux.
  • Le gestionnaire répond 200 avant d'appeler Pocket Alert, car Stripe attend un 2xx rapide. Une clé restreinte en lecture suffit pour STRIPE_SECRET_KEY : ce code n'appelle jamais l'API Stripe.
  • Intl.NumberFormat connaît le nombre de décimales de chaque devise : 4900 usd devient $49.00 et 5000 jpy devient ¥5,000.
  • L'indicateur livemode choisit le bon chemin du tableau de bord, afin que les événements de test ouvrent des pages de test.

Dans Stripe, créez une seule destination d'événements avec la charge utile Snapshot, les quatre événements et l'URL de votre serveur, puis copiez son secret de signature whsec_ depuis la page de la destination. Pour tester en local, stripe listen --forward-to localhost:4242/stripe-webhook affiche un secret à utiliser, et stripe trigger invoice.payment_failed envoie un événement de test signé.

Le résultat sur votre téléphone : une notification intitulée « Sale $49.00 », avec « [email protected] · paid » en dessous, et un litige qui vous réveille avec l'échéance dans le corps du message.

Vous voulez la vente et l'inscription dans le même flux ? Envoyez votre formulaire d'inscription vers la même application avec les alertes d'inscription : les deux se liront comme un entonnoir.

Si rien n'arrive

  • Commencez par Stripe. Ouvrez la destination dans Workbench et consultez l'onglet Livraisons d'événements. Un 400 avec « Invalid JSON » signifie que quelque chose d'autre que du JSON Stripe a atteint l'URL. Un 429 signifie que vous avez atteint la limite quotidienne.
  • Puis l'historique du webhook Pocket Alert. Si la requête y figure mais que certaines parties du message sont vides, un chemin du modèle n'existe pas dans cet événement. Copiez le corps depuis l'historique et vérifiez les noms des champs.
  • Charge utile thin par erreur. Si la notification affiche des montants vides et que le corps dans l'historique contient related_object au lieu de data, la destination a été créée en Thin. Créez-en une nouvelle en Snapshot.
  • Erreurs de signature au niveau 2. Chaque destination a son propre secret whsec_, et un secret de bac à sable diffère du secret de production. Vérifiez aussi qu'aucun élément en amont, comme un proxy ou un middleware du framework, ne réencode le corps.

FAQ

Cela remplace-t-il l'application Stripe Dashboard ?

Non, et ce n'est pas nécessaire. L'application Stripe sert à rembourser, consulter un client ou vérifier votre solde. Pocket Alert vous fournit l'alerte elle-même : votre formulation, vos niveaux de priorité et vos boutons, dans un flux partagé avec le reste de vos alertes provenant des serveurs, de la CI et des formulaires.

Quels événements méritent une notification ?

Commencez par les quatre ci-dessus. invoice.paid est un bon ajout pour les renouvellements SaaS, et customer.subscription.deleted vous signale les résiliations. Stripe conseille de ne s'abonner qu'aux événements que vous utilisez, ce qui garde aussi votre téléphone plus calme.

Puis-je recevoir une seule notification par jour au lieu d'une par vente ?

Pas depuis le webhook. Abaissez le niveau du webhook des ventes à silent pour que les ventes s'accumulent dans le flux sans son, et réservez high et critical aux événements qui exigent votre attention.

Est-ce gratuit ?

Les webhooks Stripe ne coûtent rien. L'offre gratuite de Pocket Alert couvre 50 messages par jour sur un appareil, ce qui suffit largement pour une petite boutique. Les alertes critiques qui passent outre le mode Ne pas déranger sont réservées aux offres payantes.

Créez un compte gratuit, collez une seule URL dans Stripe, et la prochaine vente arrivera sur votre téléphone.

Partager cet article