# Encaisser un paiement

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

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](/v1.0/paiements/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.

:::important[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.

::::tabs{sync="lang"}
:::tab{label="cURL"}
```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" }
  }'
```
:::
:::tab{label="TypeScript"}
```ts
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`.

::::tabs{sync="lang"}
:::tab{label="cURL"}
```bash
curl -s https://api.wakastart.app/api/billing/checkout-sessions/cs_test_a1B2c3D4e5F6g7H8 \
  -H "Authorization: Bearer $USER_TOKEN"
```
:::
:::tab{label="TypeScript"}
```ts
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](/v1.0/paiements/depannage).

## Voir aussi

- [Modèle d'encaissement](/v1.0/paiements/modele-d-encaissement)
- [Référence du module Paiements](/v1.0/paiements/reference)
- [Référence API : paiements](/v1.0/reference-api/paiements)
