# Paiements

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

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

::endpoint{method="POST" path="/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 | E-mail | 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.

```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" }
  }'
```

```ts
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**

| 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

::endpoint{method="GET" path="/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

::endpoint{method="POST" path="/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

::endpoint{method="GET" path="/api/billing/invoices"}

::endpoint{method="GET" path="/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ê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`**

```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

::endpoint{method="POST" path="/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.
