Aller au contenu

Encaisser un paiement

Créer une session Stripe Checkout depuis votre serveur, rediriger le client final, puis confirmer le paiement à son retour.

GuideDéveloppeur
Accès requis
Jeton d'un utilisateur connecté à votre wakapp ; aucun niveau d'administration requis
Durée
20 min
Voir en Markdown

Ce guide fait payer un client final de votre wakapp : votre serveur crée une session de paiement, le client paie sur la page Stripe, puis votre serveur confirme le paiement avant de livrer. Le même appel sert aux abonnements.

Avant de commencer

  • Les ventes de votre application sont ouvertes : voir Activer les ventes.
  • Le client final est connecté à votre wakapp, et votre serveur dispose de son jeton d'accès. Le jeton doit avoir été émis pour votre application : l'API en déduit l'application et l'identité du payeur.
  • Vos pages de retour sont servies sur un nom d'hôte déclaré et actif pour votre application, le même que celui de votre front. Une URL sur un autre hôte est refusée.

Calculez la commande sur votre serveur

Le montant de chaque ligne est celui que vous envoyez. Construisez les lignes sur votre serveur, à partir de vos propres tarifs, et n'acceptez jamais un montant venu du navigateur.

Créer la session de paiement

  1. Sur votre serveur, construisez les lignes de la commande. Les montants sont des entiers en centimes, hors taxes.
  2. Choisissez une clé d'idempotence stable pour cette commande, par exemple son identifiant dans votre base.
  3. Appelez POST /api/billing/checkout-sessions avec le jeton du client final.

Placez {CHECKOUT_SESSION_ID} dans successUrl : Stripe le remplace par l'identifiant de la session au moment de la redirection.

Bash
curl -s -X POST https://api.wakastart.app/api/billing/checkout-sessions \
  -H "Authorization: Bearer $USER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "lineItems": [
      { "name": "Module Gestes d'\''urgence", "unitAmountCents": 4900, "quantity": 1 },
      { "name": "Attestation imprimée", "unitAmountCents": 2000, "quantity": 1 }
    ],
    "successUrl": "https://mon-app.exemple.fr/paiement/merci?session_id={CHECKOUT_SESSION_ID}",
    "cancelUrl": "https://mon-app.exemple.fr/panier",
    "idempotencyKey": "commande-2026-10-0042",
    "customerEmail": "jeanne.martin@exemple.fr",
    "metadata": { "orderId": "2026-10-0042" }
  }'
TypeScript
type LineItem = { name: string; unitAmountCents: number; quantity: number };

export async function createCheckout(userToken: string, orderId: string, items: LineItem[]) {
  const response = await fetch("https://api.wakastart.app/api/billing/checkout-sessions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${userToken}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      lineItems: items,
      successUrl: "https://mon-app.exemple.fr/paiement/merci?session_id={CHECKOUT_SESSION_ID}",
      cancelUrl: "https://mon-app.exemple.fr/panier",
      idempotencyKey: `commande-${orderId}`,
      metadata: { orderId },
    }),
  });
  if (!response.ok) {
    const error = await response.json();
    throw new Error(`${response.status} ${error.message}`);
  }
  return (await response.json()) as { id: string; url: string };
}

Réponse attendue (201) :

JSON
{
  "id": "cs_test_a1B2c3D4e5F6g7H8",
  "url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4e5F6g7H8"
}

Rediriger le client final

  1. Renvoyez l'url de la session à votre front.
  2. Redirigez le navigateur vers cette url.

Résultat : le client voit la page de paiement Stripe à votre nom, avec le détail des lignes et, si elle est activée, la taxe calculée.

S'il abandonne, Stripe le renvoie sur cancelUrl. S'il paie, Stripe le renvoie sur successUrl, avec l'identifiant de session à la place de {CHECKOUT_SESSION_ID}.

Confirmer le paiement au retour

Wakastart n'envoie pas de webhook à votre application. La confirmation se fait au retour du client, en relisant la session côté serveur.

  1. Sur votre page de retour, lisez le paramètre session_id.
  2. Depuis votre serveur, appelez GET /api/billing/checkout-sessions/{sessionId} avec le jeton du même client final.
  3. Livrez la commande seulement si paymentStatus vaut paid. Retrouvez la commande grâce à callerMetadata.
Bash
curl -s https://api.wakastart.app/api/billing/checkout-sessions/cs_test_a1B2c3D4e5F6g7H8 \
  -H "Authorization: Bearer $USER_TOKEN"
TypeScript
export async function confirmCheckout(userToken: string, sessionId: string) {
  const response = await fetch(
    `https://api.wakastart.app/api/billing/checkout-sessions/${encodeURIComponent(sessionId)}`,
    { headers: { Authorization: `Bearer ${userToken}` } },
  );
  if (response.status === 404) return { paid: false as const };
  const session = await response.json();
  return {
    paid: session.paymentStatus === "paid",
    orderId: session.callerMetadata.orderId as string,
    amountTotal: session.amountTotal as number,
  };
}

Réponse attendue (200) :

JSON
{
  "id": "cs_test_a1B2c3D4e5F6g7H8",
  "status": "complete",
  "paymentStatus": "paid",
  "amountTotal": 8280,
  "currency": "eur",
  "callerMetadata": {
    "orderId": "2026-10-0042",
    "idempotencyKey": "commande-2026-10-0042"
  }
}

amountTotal inclut la taxe : ici 69,00 € HT et 13,80 € de TVA. Une session qui appartient à une autre application, ou à un autre client final, répond 404.

Encaisser un abonnement

Ajoutez recurringInterval au corps de la création de session : day, week, month ou year. Le montant de chaque ligne devient le montant facturé à chaque période.

JSON
{
  "lineItems": [{ "name": "Offre Titulaire", "unitAmountCents": 1900, "quantity": 1 }],
  "recurringInterval": "month",
  "successUrl": "https://mon-app.exemple.fr/abonnement/merci?session_id={CHECKOUT_SESSION_ID}",
  "cancelUrl": "https://mon-app.exemple.fr/abonnement",
  "idempotencyKey": "abonnement-usr077-2026-10"
}

Stripe crée l'abonnement sur votre compte connecté au premier paiement, puis facture à chaque échéance. La commission de Wakastart est prélevée sur chaque facture de l'abonnement, en pourcentage. La confirmation au retour suit la même étape que pour un paiement ponctuel. L'abonnement vit ensuite sur votre compte Stripe : vous le résiliez ou le remboursez depuis votre tableau de bord Stripe.

Rejouer une requête sans doublon

idempotencyKey est obligatoire, au plus 180 caractères. Elle identifie l'intention d'achat, pas la requête HTTP :

  • en cas d'expiration du délai ou d'erreur réseau, renvoyez exactement le même corps avec la même clé : vous obtenez la même session, jamais une seconde ;
  • pour une nouvelle commande, utilisez une nouvelle clé ;
  • n'envoyez pas un contenu différent avec une clé déjà utilisée : Stripe refuse la requête.

Wakastart préfixe la clé par l'identifiant de votre application avant de la transmettre à Stripe : deux applications de votre organisation peuvent utiliser la même numérotation de commandes sans collision. La clé est restituée au retour dans callerMetadata.idempotencyKey.

Vérifier le résultat

  1. Créez une session avec une ligne à 100 centimes.
  2. Ouvrez l'url et payez avec un moyen de paiement de test si votre compte Stripe est en mode test.
  3. Appelez la confirmation : paymentStatus vaut paid.
  4. Dans votre tableau de bord Stripe, le paiement apparaît sur votre compte, avec les frais de l'application Wakastart.

Dépannage

  • 400 « successUrl origin not allowed » : l'hôte de l'URL de retour n'est pas un hôte actif de votre application.
  • 403 « Ce endpoint est réservé aux requêtes émises depuis une WakaApp » : le jeton n'a pas été émis pour votre application.
  • 409 « Les ventes ne sont pas activées pour l'application … » : ouvrez les ventes.
  • Tous les cas : Résoudre les problèmes de paiement.

Voir aussi