# Référence du module Paiements

> Objets, statuts, limites et endpoints de l'API publique pour encaisser avec Stripe Connect et consulter un fournisseur existant.

Tous les endpoints sont servis par l'API publique, `https://api.wakastart.app/api`. Les erreurs suivent le format commun : `{ "statusCode", "message", "error", "timestamp", "path" }`. Le détail transverse (authentification, limites de débit) est dans la [référence API](/v1.0/reference-api/paiements).

## Authentification

| Endpoints | Jeton attendu |
|---|---|
| `/api/billing/*` | Jeton d'un utilisateur connecté, émis pour votre application. Aucun niveau d'administration requis |
| `/api/pay/app-billing*` | Jeton émis pour votre application, niveau Administrateur client, dans l'organisation éditrice |
| `/api/config/payment-credentials/*`, `/api/payments/*` | Niveau Administrateur client ; l'organisation ciblée est toujours la vôtre |

Le jeton se passe en `Authorization: Bearer <jeton>`, ou en jeton enrichi dans `x-enriched-token`. L'application, l'organisation et l'identité du payeur sont lues dans le jeton, jamais dans le corps.

## L'objet Configuration de facturation

| Champ | Type | Description |
|---|---|---|
| `appWid` | chaîne (6) | Application concernée |
| `customerWid` | chaîne (6) | Organisation qui encaisse |
| `applicationFeeBps` | entier ou `null` | Taux de commission propre à l'application ; `null` = taux par défaut de la plateforme |
| `defaultCurrency` | chaîne (3) | Devise des sessions, `EUR` par défaut |
| `taxEnabled` | booléen | Calcul de la taxe par Stripe Tax, `false` par défaut |
| `salesEnabled` | booléen | Ventes ouvertes ; modifiable seulement par `enable-sales` et `disable-sales` |
| `createdAt`, `updatedAt` | date ISO 8601 | Horodatages |

## L'objet Session de paiement

| Champ | Type | Description |
|---|---|---|
| `id` | chaîne | Identifiant Stripe de la session, `cs_…` |
| `url` | chaîne | Page de paiement Stripe ; renvoyée seulement à la création |
| `status` | chaîne | Statut Stripe : `open`, `complete` ou `expired` |
| `paymentStatus` | chaîne | Statut du paiement Stripe : `paid`, `unpaid` ou `no_payment_required` |
| `amountTotal` | entier | Total payé, taxe comprise, en centimes |
| `currency` | chaîne | Devise en minuscules, par exemple `eur` |
| `callerMetadata` | objet | Vos métadonnées, plus `idempotencyKey` |

## Statuts du compte Stripe connecté

| Statut | Encaissement possible |
|---|---|
| `PENDING` | Non |
| `ONBOARDING` | Oui, si Stripe accepte déjà les paiements |
| `ACTIVE` | Oui |
| `RESTRICTED` | Non |
| `DISABLED` | Non |

## Limites

| Élément | Valeur |
|---|---|
| Lignes par session | 1 à 100 |
| Libellé d'une ligne | 250 caractères |
| Montant d'une ligne | entier ≥ 0, en centimes, hors taxes |
| Quantité d'une ligne | entier ≥ 1 |
| `idempotencyKey` | 180 caractères, obligatoire |
| `metadata` | 20 clés au plus ; clé de 33 caractères au plus ; valeur texte de 500 caractères au plus |
| Taux de commission par défaut | 200 points de base (2 %) |
| Devise par défaut | `EUR` |

## Créer une session de paiement

::endpoint{method="POST" path="/api/billing/checkout-sessions"}

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `lineItems` | tableau | oui | Lignes `{ name, unitAmountCents, quantity }` |
| `successUrl` | URL | oui | Retour après paiement ; hôte actif de l'application. Peut contenir `{CHECKOUT_SESSION_ID}` |
| `cancelUrl` | URL | oui | Retour après abandon ; même contrainte d'hôte |
| `idempotencyKey` | chaîne | oui | Identifiant stable de l'intention d'achat |
| `customerEmail` | e-mail | non | Prérempli sur la page Stripe |
| `recurringInterval` | chaîne | non | `day`, `week`, `month` ou `year` : crée un abonnement |
| `metadata` | objet | non | Valeurs texte restituées dans `callerMetadata` |

```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":"Offre Découverte","unitAmountCents":900,"quantity":1}],"successUrl":"https://mon-app.exemple.fr/merci?session_id={CHECKOUT_SESSION_ID}","cancelUrl":"https://mon-app.exemple.fr/offres","idempotencyKey":"commande-0043"}'
```

Réponse `201` :

```json
{ "id": "cs_test_b2C3d4E5", "url": "https://checkout.stripe.com/c/pay/cs_test_b2C3d4E5" }
```

| Code | Cause |
|---|---|
| `400` | Champ invalide, ou « successUrl origin not allowed » / « cancelUrl origin not allowed » |
| `403` | « Ce endpoint est réservé aux requêtes émises depuis une WakaApp » |
| `404` | Aucune configuration de facturation ou aucun compte Stripe pour l'application |
| `409` | Ventes fermées, compte pas encore apte à encaisser, ou compte `RESTRICTED` / `DISABLED` |

## Lire une session de paiement

::endpoint{method="GET" path="/api/billing/checkout-sessions/{sessionId}"}

Renvoie l'objet Session de paiement, sans `url`. La lecture reste possible après la fermeture des ventes. Répond `404` si la session appartient à une autre application ou à un autre client final.

```bash
curl -s https://api.wakastart.app/api/billing/checkout-sessions/cs_test_b2C3d4E5 \
  -H "Authorization: Bearer $USER_TOKEN"
```

```json
{
  "id": "cs_test_b2C3d4E5",
  "status": "complete",
  "paymentStatus": "paid",
  "amountTotal": 1080,
  "currency": "eur",
  "callerMetadata": { "idempotencyKey": "commande-0043" }
}
```

## Lire la configuration de facturation

::endpoint{method="GET" path="/api/pay/app-billing"}

Renvoie l'objet Configuration de facturation de l'application du jeton. `404` si elle n'existe pas.

## Lire le contexte de facturation

::endpoint{method="GET" path="/api/pay/app-billing/context"}

Renvoie la configuration résolue : `appWid`, `customerWid`, `stripeAccountId`, `applicationFeeBps` (taux effectivement appliqué), `defaultCurrency`, `taxEnabled`.

```json
{
  "appWid": "app123",
  "customerWid": "cus456",
  "stripeAccountId": "acct_1Pexemple",
  "applicationFeeBps": 200,
  "defaultCurrency": "EUR",
  "taxEnabled": true
}
```

## Créer ou modifier la configuration de facturation

::endpoint{method="PUT" path="/api/pay/app-billing"}

| Champ | Type | Description |
|---|---|---|
| `defaultCurrency` | chaîne | Trois lettres majuscules, `EUR` ou `USD` |
| `taxEnabled` | booléen | Active Stripe Tax |

Les champs absents ne sont pas modifiés. `404` si votre organisation n'a pas de compte Stripe connecté.

## Ouvrir les ventes

::endpoint{method="POST" path="/api/pay/app-billing/enable-sales"}

Sans corps. Répond `201` avec la configuration, `salesEnabled: true`. `409` si la checklist TVA n'est pas validée, si le compte n'est pas apte à encaisser ou s'il est `RESTRICTED` ou `DISABLED` ; le message nomme la condition.

## Fermer les ventes

::endpoint{method="POST" path="/api/pay/app-billing/disable-sales"}

Sans corps ni condition. Répond `201` avec `salesEnabled: false`.

## Enregistrer la clé d'un fournisseur

::endpoint{method="PUT" path="/api/config/payment-credentials/{customerWid}"}

Corps : `provider` (`STRIPE`, `PADDLE`, `POLAR`) et `apiKey`. La clé est chiffrée et jamais renvoyée. L'organisation ciblée est celle de votre jeton.

## Lire la configuration du fournisseur

::endpoint{method="GET" path="/api/config/payment-credentials/{customerWid}"}

Renvoie `customerWid`, `provider`, `connectionMode` et `updatedAt`, ou `null` si aucune clé n'est enregistrée.

## Lire les données du fournisseur

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

::endpoint{method="GET" path="/api/payments/purchases"}

::endpoint{method="GET" path="/api/payments/products"}

Lectures en direct chez le fournisseur enregistré. `404` sans clé enregistrée ; `502` si le fournisseur refuse la clé ou ne répond pas.

## Voir aussi

- [Encaisser un paiement](/v1.0/paiements/encaisser-un-paiement)
- [Référence API : paiements](/v1.0/reference-api/paiements)
