Paiements
Faire payer les utilisateurs de votre application avec Stripe Checkout, ouvrir leur portail de facturation, lire leurs factures et abonnements.
This page has not been translated yet and is shown in French.
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
/api/billing/checkout-sessions| Champ | Type | Obligatoire | Contraintes | Description |
|---|---|---|---|---|
lineItems | tableau | oui | 1 à 100 éléments | Lignes de la commande |
lineItems[].name | chaîne | oui | 250 caractères au plus | Libellé affiché par Stripe |
lineItems[].unitAmountCents | entier | oui | ≥ 0 | Prix unitaire en centimes |
lineItems[].quantity | entier | oui | ≥ 1 | Quantité |
successUrl | chaîne | oui | URL absolue d'un hôte de votre application | Retour après paiement |
cancelUrl | chaîne | oui | Idem | Retour après abandon |
idempotencyKey | chaîne | oui | 180 caractères au plus | Clé unique par intention de paiement |
customerEmail | chaîne | non | Pré-remplit l'adresse dans Stripe | |
recurringInterval | chaîne | non | day, week, month, year | Crée un abonnement au lieu d'un paiement unique |
metadata | objet | non | 20 clés au plus, clés de 33 caractères et valeurs de 500 caractères au plus | Vos 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.
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" }
}'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 StripeRéponse 201
{ "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
| Statut | Message |
|---|---|
400 | successUrl origin not allowed (ou cancelUrl) |
400 | Une session de paiement exige au moins une ligne de commande |
403 | Ce endpoint est réservé aux requêtes émises depuis une WakaApp |
404 | Aucune configuration de facturation pour l'application <appWid> |
409 | Les ventes ne sont pas activées pour l'application <appWid> |
409 | Le compte Stripe Connect du Customer <wid> n'est pas encore apte à encaisser |
Lire une session de paiement
/api/billing/checkout-sessions/{sessionId}sessionId : identifiant Stripe de la session (cs_…). Seul l'utilisateur qui a créé la session peut la lire.
curl -s https://api.wakastart.app/api/billing/checkout-sessions/cs_test_a1B2c3D4e5F6 \
-H "Authorization: Bearer $ACCESS_TOKEN"Réponse 200
{
"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
/api/billing/portal-sessionsOuvre 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
/api/billing/invoices/api/billing/subscriptionsRenvoie les factures ou les abonnements de l'utilisateur connecté, lus en direct chez Stripe. Pagination par curseur :
| Paramètre de requête | Type | Description |
|---|---|---|
limit | entier, 1 à 100 | Taille de page |
startingAfter | chaîne (255) | Identifiant du dernier élément de la page précédente (nextCursor) |
Réponse 200
{
"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
/api/billing/subscriptions/{subscriptionId}/cancelProgramme 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.
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.