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.
This page has not been translated yet and is shown in French.
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.
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
/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 | 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 |
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 :
{ "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
/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.
curl -s https://api.wakastart.app/api/billing/checkout-sessions/cs_test_b2C3d4E5 \
-H "Authorization: Bearer $USER_TOKEN"{
"id": "cs_test_b2C3d4E5",
"status": "complete",
"paymentStatus": "paid",
"amountTotal": 1080,
"currency": "eur",
"callerMetadata": { "idempotencyKey": "commande-0043" }
}Lire la configuration de facturation
/api/pay/app-billingRenvoie l'objet Configuration de facturation de l'application du jeton. 404 si elle n'existe pas.
Lire le contexte de facturation
/api/pay/app-billing/contextRenvoie la configuration résolue : appWid, customerWid, stripeAccountId, applicationFeeBps (taux effectivement appliqué), defaultCurrency, taxEnabled.
{
"appWid": "app123",
"customerWid": "cus456",
"stripeAccountId": "acct_1Pexemple",
"applicationFeeBps": 200,
"defaultCurrency": "EUR",
"taxEnabled": true
}Créer ou modifier la configuration de facturation
/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
/api/pay/app-billing/enable-salesSans 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
/api/pay/app-billing/disable-salesSans corps ni condition. Répond 201 avec salesEnabled: false.
Enregistrer la clé d'un fournisseur
/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
/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
/api/payments/invoices/api/payments/purchases/api/payments/productsLectures en direct chez le fournisseur enregistré. 404 sans clé enregistrée ; 502 si le fournisseur refuse la clé ou ne répond pas.