Paiements et facturation : vue d'ensemble
Bêta
Fonctionnalité en cours de déploiement. L'interface décrite ici est celle de la prochaine livraison : elle peut encore évoluer, et n'est pas forcément activée sur votre tenant.
Paiements et facturation est en cours de déploiement : tant que la fonctionnalité n'est pas activée sur votre tenant, les manifestes BillingAccount et BillingWebhook sont refusés.
À quoi ça sert
Paiements et facturation vous permet d'encaisser vos propres clients, en marque blanche : votre application envoie un panier, la plateforme renvoie un lien vers une page de paiement à vos couleurs, puis émet la facture. L'argent arrive directement sur vos comptes Stripe ou PayPal : la plateforme ne le détient jamais.
Trois façons d'encaisser :
| Mode | Pour quoi | Page |
|---|---|---|
one_time | un achat ponctuel : un panier, un paiement, une facture | Encaisser un paiement |
subscription | un abonnement : la plateforme débite chaque échéance et facture | Abonnements |
usage | le paiement à l'usage : vous envoyez le panier du mois, la plateforme débite le moyen de paiement enregistré | Paiement à l'usage |
Comment ça marche, de votre côté
- Vous configurez votre compte de paiement une fois, avec un manifeste
BillingAccount: nom affiché, vos clés Stripe et/ou PayPal, vos informations légales de facturation, votre logo et vos couleurs. Voir Configurer votre compte de paiement. - Votre application appelle l'API de paiement avec un jeton d'application de votre organisation : créer un panier, débiter un client, rembourser, lire les factures.
- Vos clients paient sur la page de paiement, sans créer de compte : ils y accèdent par un lien signé, à durée limitée.
- La plateforme vous prévient de chaque événement (paiement réussi, échéance impayée,
facture émise, remboursement…) par des webhooks signés que vous
déclarez avec
BillingWebhook. - Vous écrivez à vos clients : la plateforme n'envoie aucun e-mail à vos clients. C'est votre application qui envoie confirmation, facture ou relance, à partir des webhooks.
Ce que vous obtenez
- Une page de paiement à vos couleurs, sous
https://pay.dev.stackngo.fr/<slug>/…, qui propose Stripe (carte) et/ou PayPal selon votre configuration. - Une facture pour chaque paiement réussi et un avoir pour chaque remboursement, au format Factur-X (PDF/A-3 avec les données structurées embarquées), numérotées sans trou, à votre nom et avec vos mentions légales. Voir Factures.
- Un portail client par lien signé, où votre client retrouve ses factures, ses abonnements et son moyen de paiement.
- Un rapport d'encaissement qui répond à « à qui appartient cet argent ? », par application et par étiquette. Voir Savoir à qui appartient l'argent.
L'API en bref
| Adresse | https://billing-api.dev.stackngo.fr |
| Authentification | Authorization: Bearer <jeton> : jeton d'application de votre organisation (voir Configurer votre compte de paiement) |
| Montants | chaînes décimales ("49.00"), devise ISO 4217 (EUR) ; chaque ligne est arrondie au centime |
| TVA | calculée par catégorie et par taux, selon la norme européenne EN 16931 |
| Erreurs | application/problem+json (RFC 9457) : title, status, detail, et errors[] champ par champ |
| Rejeu sans risque | en-tête Idempotency-Key : facultatif sur la création d'un panier, obligatoire sur un débit et un remboursement |
| Listes | limit (1 à 100, 25 par défaut) et cursor ; la réponse donne next_cursor |
Votre jeton ne peut faire que ce que vous avez autorisé à l'application dans votre
BillingAccount (carts, charges, subscriptions, refunds, invoices:read).
Ce que vous pouvez en attendre
- Un seul compte de paiement par tenant, qui peut utiliser Stripe, PayPal ou les deux.
- Aucun catalogue à maintenir : chaque panier porte ses lignes, ses prix et sa TVA.
- Vos clés restent les vôtres : vous les gérez comme vos autres secrets ; la plateforme s'en sert pour encaisser en votre nom, sans jamais les afficher.
- Les frais de transaction sont ceux de votre contrat Stripe ou PayPal.
- Les factures sont conservées 10 ans, même si vous retirez votre compte de paiement.
Pas encore disponible
- Les domaines personnalisés pour la page de paiement : elle est servie sous
pay.dev.stackngo.fr. - Le prélèvement SEPA : seuls la carte (Stripe) et PayPal sont proposés.
- Plusieurs devises dans une même facture : une facture, un panier et un abonnement ont une seule devise.
- La transmission des factures aux plateformes de dématérialisation (PDP) : vous téléchargez vos factures Factur-X et les transmettez vous-même.
Si ça ne marche pas
Voir Dépannage des paiements.