Encaisser un paiement
Créer une session Stripe Checkout depuis votre serveur, rediriger le client final, puis confirmer le paiement à son retour.
- Accès requis
- Jeton d'un utilisateur connecté à votre wakapp ; aucun niveau d'administration requis
- Durée
- 20 min
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
- Sur votre serveur, construisez les lignes de la commande. Les montants sont des entiers en centimes, hors taxes.
- Choisissez une clé d'idempotence stable pour cette commande, par exemple son identifiant dans votre base.
- Appelez
POST /api/billing/checkout-sessionsavec 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.
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" }
}'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) :
{
"id": "cs_test_a1B2c3D4e5F6g7H8",
"url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4e5F6g7H8"
}Rediriger le client final
- Renvoyez l'
urlde la session à votre front. - 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.
- Sur votre page de retour, lisez le paramètre
session_id. - Depuis votre serveur, appelez
GET /api/billing/checkout-sessions/{sessionId}avec le jeton du même client final. - Livrez la commande seulement si
paymentStatusvautpaid. Retrouvez la commande grâce àcallerMetadata.
curl -s https://api.wakastart.app/api/billing/checkout-sessions/cs_test_a1B2c3D4e5F6g7H8 \
-H "Authorization: Bearer $USER_TOKEN"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) :
{
"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.
{
"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
- Créez une session avec une ligne à
100centimes. - Ouvrez l'
urlet payez avec un moyen de paiement de test si votre compte Stripe est en mode test. - Appelez la confirmation :
paymentStatusvautpaid. - 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.