Dans ce tutoriel, vous construirez NeuralAPI — une plateforme IA en niveaux où chaque plan d’abonnement dispose d’une allocation mensuelle de crédits de jetons, les clients peuvent acheter des packs de recharge lorsqu’ils sont à court, et votre backend déduit automatiquement les crédits à mesure que les demandes sont traitées par OpenAI.Documentation Index
Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
Use this file to discover all available pages before exploring further.
- Créer un droit de crédit personnalisé (jetons) et un compteur qui déduit automatiquement
- Attacher des crédits à des plans d’abonnements (avec et sans surconsommation) et un produit de recharge ponctuel
- Connecter un véritable point de terminaison de complétion OpenAI qui facture les jetons via Dodo Payments
- Interroger le solde de crédits en direct d’un client via le SDK
- Vérifier les signatures des webhooks et router les événements de crédits de Dodo Payments
Ce que nous construisons
Voici le modèle de tarification pour NeuralAPI :| Produit | Prix | Jetons | Surconsommation |
|---|---|---|---|
| Plan Starter | 29 $/mois | 10,000,000 jetons/cycle | Bloqué à zéro |
| Plan Pro | 99 $/mois | 40,000,000 jetons/cycle | 0,005 $ par 1 000 jetons |
| Pack de recharge de jetons | 19 $ une fois | +5,000,000 jetons | — |
- Un compte Dodo Payments (mode test suffisant)
- Une clé API OpenAI
- Node.js 18+
- Une connaissance de base de TypeScript/Node.js
Étape 1 : Créez votre droit de crédit de jetons
Tout d’abord, créez le droit de crédit que les deux plans d’abonnement et le pack de recharge partageront. Considérez cela comme la définition de l’unité “jeton” utilisée par votre plateforme.
Navigate to Credits
- Connectez-vous à votre tableau de bord Dodo Payments
- Cliquez sur Produits dans la barre latérale gauche
- Sélectionnez l’onglet Crédits
- Cliquez sur Créer un crédit
Configure the credit unit
API TokensType de crédit : Sélectionnez Unité personnaliséeNom de l’unité : tokenPrécision : 0 (les jetons sont toujours des nombres entiers)Expiration des crédits : 30 days (les crédits se réinitialisent à chaque cycle de facturation)Skip overage at the credit level
Save and copy the credit ID
cent_xxxxxxxxxxxx.API Tokens est prêt. Ensuite, créez un compteur afin que les événements d’utilisation puissent entraîner des déductions automatiquement.Étape 2 : Créez un compteur pour l’utilisation des jetons
Un compteur agrège les événements d’utilisation entrants et les convertit en déductions de crédits. Vous en avez besoin avant de créer les produits de planification, car vous l’attacherez lors de la création du produit à l’étape 3.Open the Meters section
- Dans la barre latérale du tableau de bord, allez à Produits → Compteurs
- Cliquez sur Créer un compteur
Configure the meter
Token Usage MeterNom de l’événement : api.tokens_used (cela doit correspondre exactement à ce que votre application envoie)Type d’agrégation : Sum — nous additionnons le nombre de jetons de chaque événementSur propriété : tokens — la clé de métadonnées sur chaque événement dont la valeur sera additionnéeUnité de mesure : tokensEnregistrez le compteur et copiez son identifiant — vous le référencerez lors de l’attachement aux produits.Étape 3 : Créez les produits de planification
Les deux plans doivent être des produits de facturation basée sur l’utilisation, pas de simples abonnements — les compteurs ne peuvent être attachés qu’aux produits UBB, et vous avez besoin du compteur pour déduire automatiquement les crédits à mesure que les clients appellent votre API. Les produits UBB prennent toujours en charge des frais de base récurrents (la$29 / $99); l’utilisation au-delà de cela est facturée en crédits.

Plan Starter (29 $/mois — 10M de jetons, pas de surconsommation)
Create the Starter UBB product
- Allez à Produits → Créer un produit
- Sélectionnez Facturation basée sur l’utilisation comme type de tarification
- Remplissez :
NeuralAPI StarterDescription : 10 million API tokens per month. Perfect for individual developers and small projects.Prix fixe : 29.00 (les frais de base récurrents — facturés mensuellement même avant toute utilisation)Cycle de facturation : MonthlyDevise : USDAttach the meter
Token Usage Meter. Puis sur le compteur :- Basculer Facturer l’utilisation en crédits sur on
- Droit de crédit : sélectionnez
API Tokens - Unités de compteur par crédit :
1— chaque jeton de l’événement correspond à 1 crédit déduit - Seuil gratuit :
0— l’allocation de crédits elle-même est le “niveau gratuit” du client ; nous n’avons pas besoin d’une bande gratuite supplémentaire

api.tokens_used entrants déduisent réellement du solde du client.Configure credit issuance for Starter
10000000Permettre la surconsommation : Désactivé — les clients Starter sont bloqués lorsque les jetons sont épuisésImporter les paramètres de crédit par défaut : Activé — utilisez l’expiration de 30 jours du droit de crédit
Plan Pro (99 $/mois — 40M de jetons, surconsommation activée)
Create the Pro UBB product
NeuralAPI ProDescription : 40 million API tokens per month with overage. Built for production applications.Prix fixe : 99.00Cycle de facturation : MonthlyDevise : USDAttach the meter
Token Usage Meter, activez Facturer l’utilisation en crédits, sélectionnez API Tokens, Unités de compteur par crédit 1, Seuil gratuit 0.Configure credit issuance with overage
40000000Importer les paramètres de crédit par défaut : Désactivé — nous devons personnaliser les paramètres de surconsommation par produitPermettre la surconsommation : ActivéPrix par unité : 0.000005 USD par jeton (c’est-à-dire, 0,005 par 1M de jetons — au-dessus du taux effectif par jeton du plan pour décourager les débordements)Comportement de surconsommation : Bill overage at billing — la surconsommation est facturée sur la prochaine facture, puis le solde est réinitialiséEnregistrez le produit et copiez l’identifiant du produit.Étape 4 : Créez le pack de recharge de jetons
Le pack de recharge est un achat unique qui accorde 5,000,000 de jetons au solde d’un client existant.
Create a one-time product
- Allez à Produits → Créer un produit
- Sélectionnez Paiement unique comme type de tarification
- Remplissez :
Token Top-Up PackDescription : Instantly add 5 million tokens to your NeuralAPI balance.Prix : 19.00Devise : USDAttach the token credit
- Dans la section Droits, cliquez sur Attacher à côté de Crédits
- Sélectionnez
API Tokens - Définissez Crédits émis :
5000000 - Désactiver Importer les paramètres de crédit par défaut — nous voulons remplacer l’expiration par défaut de 30 jours
- Définissez Expiration des crédits :
365 days - Enregistrez le produit
Étape 5 : Construire le backend
Construisons maintenant le serveur Express qui gère le paiement de l’abonnement, le paiement de la recharge, les complétions réelles d’OpenAI avec facturation par jetons, les requêtes de solde, et les événements webhooks de crédit.Set up your project
tsconfig.json :package.json :Set up environment variables
.env avec vos identifiants et ID des étapes précédentes :DODO_PAYMENTS_WEBHOOK_KEY à l’étape 7 après l’enregistrement de votre point de terminaison de webhook.Implement the server
src/server.ts :A note on how deductions actually happen
- Votre gestionnaire appelle OpenAI et reçoit
usage.total_tokens(par exemple, 1532). - Vous ingérez un seul événement d’utilisation :
event_name: api.tokens_used,metadata: { tokens: 1532 }. - Le
Token Usage Meteragrège des événements par client. - Parce que le compteur est lié au crédit
API Tokensavec Facturer l’utilisation en crédits, Dodo Payments déduit 1532 crédits de la subvention non expirée la plus ancienne du client (FIFO). - Si la surconsommation est activée et que le client passe en dessous de zéro, le déficit est suivi et facturé sur la prochaine facture.
Étape 6 : Ajoutez une interface de démonstration
Créezpublic/index.html pour tester tous les flux dans votre navigateur. Nous conservons l’ID client dans localStorage afin que l’abonnement → génération → recharge partagent tous la même identité, imitant une application connectée :
Étape 7 : Connectez le Webhook
Les webhooks permettent à votre serveur de réagir aux changements de solde — vous les utiliserez pour envoyer des emails “en cours d’épuisement” avant que les clients atteignent zéro.Expose your local server
https://...ngrok-free.app.Register the webhook in Dodo Payments
- Dans le tableau de bord, allez à Développeurs → Webhooks → Ajouter un point de terminaison
- URL :
https://your-tunnel.ngrok-free.app/webhooks/dodo - Abonnez-vous à (au minimum) :
credit.addedcredit.deductedcredit.overage_charged
- Enregistrez et copiez le Secret de signature
- Collez-le dans
.envcommeDODO_PAYMENTS_WEBHOOK_KEY, puis redémarreznpm run dev
Étape 8 : Testez le flux complet
Subscribe a test customer
- Exécutez
npm run dev - Ouvrez
http://localhost:3000 - Choisissez Plan Pro, entrez un email de test + nom, cliquez sur Obtenir un lien de paiement, complétez le paiement avec détails carte test
- Dans le tableau de bord, allez à Clients → plus récent et copiez l’ID
cus_... - Collez-le dans le champ “ID client connecté” sur la démo et cliquez sur Enregistrer
Generate a real AI response
total_tokens, ingère un événement d’utilisation, et retourne la réponse.Dépannage
Credits not deducting after usage events
Credits not deducting after usage events
- Le nom de l’événement du compteur ne correspond pas au
event_nameque vous envoyez (api.tokens_usedest sensible à la casse) - Le compteur n’est pas lié au crédit
API Tokenssur le produit — allez à la configuration du compteur du produit et confirmez que Facturer l’utilisation en crédits est activé - La clé
metadata.tokensne correspond pas au champ “Sur propriété” du compteur - La subvention du client a expiré (vérifiez l’historique des crédits du client)
- Produits → Compteurs : ouvrez le compteur et confirmez qu’il montre le nom du crédit lié sur l’attachement du produit
- L’onglet Événements sur le compteur — les événements ingérés devraient y apparaître même avant la déduction
- Clients → [Client] → Crédits : les entrées du registre devraient apparaître dans une minute ou deux
Balance always shows 0 or 'customer not found'
Balance always shows 0 or 'customer not found'
- Le client n’a pas encore terminé le paiement — les crédits ne sont alloués qu’après un paiement réussi
- Vous interrogez avec le mauvais
customer_id(utilisez l’IDcus_...du tableau de bord, pas votre propre ID DB) - Le
CREDIT_ENTITLEMENT_IDdans.envne correspond pas au crédit attaché au produit
Overage not working for Pro plan customers
Overage not working for Pro plan customers
- La surconsommation n’a pas été activée sur l’attachement de crédit du produit Pro (le paramètre de niveau de crédit est juste une valeur par défaut)
- Le client est en fait sur Starter, pas Pro
- La limite de surconsommation était définie à 0
0.000005 (= 5 $ par million de jetons; vérifiez bien les zéros devant — le champ prend le prix par jeton, pas par 1K).`Webhook verification failed` in logs
`Webhook verification failed` in logs
- Ordre d’analyse du corps:
express.json()a été appliqué à/webhooks/dodoavantexpress.raw()— le SDK a besoin des octets bruts de la requête, pas JSON analysé - Mauvais secret de signature dans
DODO_PAYMENTS_WEBHOOK_KEY - Le proxy inverse réécrit les en-têtes
app.use('/webhooks/dodo', express.raw(...)) vient avant app.use(express.json()) dans server.ts.Besoin d’aide?
Félicitations ! Vous avez construit une facturation basée sur des crédits pour NeuralAPI
Votre plateforme dispose désormais d’un système de facturation de crédits complet et prêt pour la production :Token Credit Entitlement
API Tokens avec une expiration de 30 jours, partagé sur tous les plans et le pack de rechargeTiered Plans, One Credit
One-Time Top-Up Pack
Auto-Deduction via Meter
Live Balance API
Verified Webhook Pipeline
credit.added, credit.deducted, credit.overage_charged) routés via un gestionnaire vérifié par signature utilisant l’assistant de webhooks standards du SDK- Auth sur
/credits/:customerIdet/api/generate— actuellement, n’importe qui peut les atteindre avec n’importe quel ID client. Authentifiez les utilisateurs et recherchez leur ID client côté serveur. event_idstables — l’exemple utiliseDate.now() + random. En production, utilisez votre ID de requête pour que les réessais soient idempotents (Dodo Payments élimine les doublons parevent_id).- Persister le mapping client↔utilisateur — enregistrez
customer_iddans votre DB après le premier paiement pour éviter un copier-coller manuel. - Décider de ce qui se passe lorsque l’abonnement se termine. Les crédits de plan restent dans le registre du client jusqu’à leur expiration naturelle (30 jours après l’émission) et les crédits de recharge restent valables pendant 365 jours — mais la cuisine de
/api/generatevérifie uniquement le solde, pas l’état de l’abonnement. Ainsi, un client annulé peut toujours consommer ses jetons restants. C’est le choix axé sur le client. Si vous souhaitez un contrôle d’accès plus strict, soit (a) écoutez le webhooksubscription.cancelledet limitez/api/generateselon l’état de l’abonnement, soit (b) appelez l’API du registre de Dodo pour débiter les crédits de plan inutilisés lors de l’annulation tout en laissant les crédits de recharge intacts. - Surveillez le tableau de bord de la facturation à l’utilisation pour détecter les anomalies de mesure tôt.