Aller au contenu

Paiements

Faire payer les utilisateurs de votre application avec Stripe Checkout, ouvrir leur portail de facturation, lire leurs factures et abonnements.

RéférenceDéveloppeur
Voir en Markdown

Ces endpoints permettent à votre application d'encaisser ses propres utilisateurs, sur le compte Stripe Connect de l'éditeur : votre application crée une session de paiement Stripe Checkout, redirige l'utilisateur, puis vérifie le résultat. La configuration commerciale (compte Stripe, commission, devise, ouverture des ventes) se fait au préalable dans la console : voir Paiements.

Conditions d'accès

  • Accès : tout utilisateur connecté à votre application, sans niveau d'administration. L'appel doit porter le jeton de l'utilisateur, émis pour votre application : jeton Keycloak ou jeton enrichi.
  • L'application et l'utilisateur payeur sont toujours déduits du jeton : n'envoyez jamais d'identifiant d'application ou de client.
  • Les ventes doivent être ouvertes pour l'application et le compte Stripe de l'éditeur apte à encaisser.

Créer une session de paiement

POST/api/billing/checkout-sessions
ChampTypeObligatoireContraintesDescription
lineItemstableauoui1 à 100 élémentsLignes de la commande
lineItems[].namechaîneoui250 caractères au plusLibellé affiché par Stripe
lineItems[].unitAmountCentsentieroui≥ 0Prix unitaire en centimes
lineItems[].quantityentieroui≥ 1Quantité
successUrlchaîneouiURL absolue d'un hôte de votre applicationRetour après paiement
cancelUrlchaîneouiIdemRetour après abandon
idempotencyKeychaîneoui180 caractères au plusClé unique par intention de paiement
customerEmailchaînenonE-mailPré-remplit l'adresse dans Stripe
recurringIntervalchaînenonday, week, month, yearCrée un abonnement au lieu d'un paiement unique
metadataobjetnon20 clés au plus, clés de 33 caractères et valeurs de 500 caractères au plusVos données, restituées à la lecture de la session

Les hôtes de successUrl et cancelUrl doivent être des hôtes déclarés pour votre application ; sinon la session est refusée.

Bash
curl -s -X POST https://api.wakastart.app/api/billing/checkout-sessions \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "lineItems": [{ "name": "Téléconsultation", "unitAmountCents": 4900, "quantity": 1 }],
    "successUrl": "https://mon-app.exemple.fr/paiement/succes",
    "cancelUrl": "https://mon-app.exemple.fr/paiement/annule",
    "idempotencyKey": "commande-2026-10-23-0042",
    "metadata": { "orderId": "0042" }
  }'
TypeScript
const res = await fetch("https://api.wakastart.app/api/billing/checkout-sessions", {
  method: "POST",
  headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    lineItems: [{ name: "Téléconsultation", unitAmountCents: 4900, quantity: 1 }],
    successUrl: "https://mon-app.exemple.fr/paiement/succes",
    cancelUrl: "https://mon-app.exemple.fr/paiement/annule",
    idempotencyKey: order.id,
  }),
});
const { url } = await res.json();
window.location.assign(url); // page de paiement Stripe

Réponse 201

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

Redirigez l'utilisateur vers url. Au retour sur successUrl, lisez la session pour confirmer le paiement : ne vous fiez pas au seul retour du navigateur.

Erreurs

StatutMessage
400successUrl origin not allowed (ou cancelUrl)
400Une session de paiement exige au moins une ligne de commande
403Ce endpoint est réservé aux requêtes émises depuis une WakaApp
404Aucune configuration de facturation pour l'application <appWid>
409Les ventes ne sont pas activées pour l'application <appWid>
409Le compte Stripe Connect du Customer <wid> n'est pas encore apte à encaisser

Lire une session de paiement

GET/api/billing/checkout-sessions/{sessionId}

sessionId : identifiant Stripe de la session (cs_…). Seul l'utilisateur qui a créé la session peut la lire.

Bash
curl -s https://api.wakastart.app/api/billing/checkout-sessions/cs_test_a1B2c3D4e5F6 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Réponse 200

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

Le paiement est acquis quand paymentStatus vaut paid. 404 Session <id> introuvable pour l'application <appWid> pour une session d'un autre utilisateur ou d'une autre application.

Ouvrir le portail de facturation

POST/api/billing/portal-sessions

Ouvre le portail Stripe où l'utilisateur change de moyen de paiement et consulte ses factures. Corps : returnUrl, URL absolue d'un hôte de votre application.

Réponse 201 : { "url": "https://billing.stripe.com/p/session/test_…" }.

Erreurs : 404 Aucun historique de facturation pour ce client tant que l'utilisateur n'a jamais payé.

Lister ses factures et ses abonnements

GET/api/billing/invoices
GET/api/billing/subscriptions

Renvoie les factures ou les abonnements de l'utilisateur connecté, lus en direct chez Stripe. Pagination par curseur :

Paramètre de requêteTypeDescription
limitentier, 1 à 100Taille de page
startingAfterchaîne (255)Identifiant du dernier élément de la page précédente (nextCursor)

Réponse 200

JSON
{
  "data": [
    {
      "id": "sub_1Q2w3E4r5T6y",
      "status": "active",
      "currentPeriodStart": "2026-10-23T00:00:00.000Z",
      "currentPeriodEnd": "2026-11-23T00:00:00.000Z",
      "cancelAtPeriodEnd": false,
      "canceledAt": null,
      "trialEnd": null
    }
  ],
  "hasMore": false,
  "nextCursor": null
}

Champs d'une facture : id, number, status, currency, amountDueCents, amountPaidCents, createdAt, periodStart, periodEnd, hostedInvoiceUrl (page de la facture chez Stripe), invoicePdfUrl. Champs d'un abonnement : id, status, currentPeriodStart, currentPeriodEnd, cancelAtPeriodEnd, canceledAt, trialEnd. Les statuts sont ceux de Stripe.

Résilier un abonnement

POST/api/billing/subscriptions/{subscriptionId}/cancel

Programme la résiliation à la fin de la période en cours. Le corps doit être vide : tout champ, y compris une demande de résiliation immédiate, est refusé avec 400.

Bash
curl -s -X POST https://api.wakastart.app/api/billing/subscriptions/sub_1Q2w3E4r5T6y/cancel \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Erreurs : 404 Abonnement <id> inconnu pour <appWid> pour l'abonnement d'un autre utilisateur.