Aller au contenu

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.

RéférenceDéveloppeur
Voir en Markdown

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

EndpointsJeton 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

ChampTypeDescription
appWidchaîne (6)Application concernée
customerWidchaîne (6)Organisation qui encaisse
applicationFeeBpsentier ou nullTaux de commission propre à l'application ; null = taux par défaut de la plateforme
defaultCurrencychaîne (3)Devise des sessions, EUR par défaut
taxEnabledbooléenCalcul de la taxe par Stripe Tax, false par défaut
salesEnabledbooléenVentes ouvertes ; modifiable seulement par enable-sales et disable-sales
createdAt, updatedAtdate ISO 8601Horodatages

L'objet Session de paiement

ChampTypeDescription
idchaîneIdentifiant Stripe de la session, cs_…
urlchaînePage de paiement Stripe ; renvoyée seulement à la création
statuschaîneStatut Stripe : open, complete ou expired
paymentStatuschaîneStatut du paiement Stripe : paid, unpaid ou no_payment_required
amountTotalentierTotal payé, taxe comprise, en centimes
currencychaîneDevise en minuscules, par exemple eur
callerMetadataobjetVos métadonnées, plus idempotencyKey

Statuts du compte Stripe connecté

StatutEncaissement possible
PENDINGNon
ONBOARDINGOui, si Stripe accepte déjà les paiements
ACTIVEOui
RESTRICTEDNon
DISABLEDNon

Limites

ÉlémentValeur
Lignes par session1 à 100
Libellé d'une ligne250 caractères
Montant d'une ligneentier ≥ 0, en centimes, hors taxes
Quantité d'une ligneentier ≥ 1
idempotencyKey180 caractères, obligatoire
metadata20 clés au plus ; clé de 33 caractères au plus ; valeur texte de 500 caractères au plus
Taux de commission par défaut200 points de base (2 %)
Devise par défautEUR

Créer une session de paiement

POST/api/billing/checkout-sessions
ChampTypeObligatoireDescription
lineItemstableauouiLignes { name, unitAmountCents, quantity }
successUrlURLouiRetour après paiement ; hôte actif de l'application. Peut contenir {CHECKOUT_SESSION_ID}
cancelUrlURLouiRetour après abandon ; même contrainte d'hôte
idempotencyKeychaîneouiIdentifiant stable de l'intention d'achat
customerEmaile-mailnonPrérempli sur la page Stripe
recurringIntervalchaînenonday, week, month ou year : crée un abonnement
metadataobjetnonValeurs 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" }
CodeCause
400Champ invalide, ou « successUrl origin not allowed » / « cancelUrl origin not allowed »
403« Ce endpoint est réservé aux requêtes émises depuis une WakaApp »
404Aucune configuration de facturation ou aucun compte Stripe pour l'application
409Ventes fermées, compte pas encore apte à encaisser, ou compte RESTRICTED / DISABLED

Lire une session de paiement

GET/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

GET/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

GET/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

PUT/api/pay/app-billing
ChampTypeDescription
defaultCurrencychaîneTrois lettres majuscules, EUR ou USD
taxEnabledbooléenActive Stripe Tax

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

Ouvrir les ventes

POST/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

POST/api/pay/app-billing/disable-sales

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

Enregistrer la clé d'un fournisseur

PUT/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

GET/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

GET/api/payments/invoices
GET/api/payments/purchases
GET/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