Cas d’usage
Recharge balance via Stripe Checkout
Top-up à la consommation de la balance API
Scell.io facture à la consommation : chaque facture émise, signature initiée, OCR consomme du crédit sur la balance du tenant. Pour recharger : `POST /api/v1/balance/reload` retourne une URL Stripe Checkout préremplie (montant, devise EUR, métadonnées tenant_id). Le client paie via Stripe (carte, SEPA, Bacs), Stripe notifie Scell.io via webhook signé, et la balance est créditée en moins de 60 secondes. Idempotency-Key recommandé pour éviter les double-recharges en cas de retry réseau. Webhook `balance.reloaded` notifie votre backend. Auto-reload configurable : seuil min (ex: 50€) → top-up auto (ex: 500€) avec carte sauvegardée Stripe.
À retenir
- Endpoint `POST /api/v1/balance/reload` → URL Stripe Checkout
- Méthodes Stripe : carte, SEPA, Bacs
- Crédit balance < 60s après paiement
- Idempotency-Key recommandé
- Webhook `balance.reloaded` post-crédit
- Auto-reload configurable (seuil + montant + carte sauvegardée)
Exemple de code
import { ScellClient } from '@scell/sdk';
import { randomUUID } from 'node:crypto';
const scell = new ScellClient({ apiKey: process.env.SCELL_SECRET_KEY! });
// 1. Top-up manuel : générer la session Checkout
const session = await scell.balance.reload({
amount: 500_00, // en centimes (500€)
currency: 'EUR',
return_url: 'https://app.example.com/billing/success',
cancel_url: 'https://app.example.com/billing/cancel',
}, { idempotencyKey: randomUUID() });
console.log('Redirect user to:', session.checkout_url);
// 2. Configurer l'auto-reload (carte sauvegardée requise)
await scell.balance.configureAutoReload({
enabled: true,
threshold_cents: 50_00, // déclenche à 50€
topup_amount_cents: 500_00, // recharge 500€
});