Applications et intégration de paiement

Utilisez einvoice comme backend de facturation pour vos propres SaaS. Créez une application, définissez des plans tarifaires, intégrez le widget de paiement et recevez des webhooks signés lors de chaque transaction.

Vue d’ensemble

La fonctionnalité Applications vous permet de :

Créer des applications représentant vos SaaS tiers
Définir des plans tarifaires (abonnements récurrents ou paiements uniques)
Générer des clés API pour sécuriser les appels serveur-à-serveur
Configurer des webhooks pour être notifié de chaque paiement
Intégrer le paywall SDK einvoice directement dans vos pages web
Surveiller les livraisons échouées de webhooks pour le débogage

Qu’est-ce qu’une application ?

Une application (ou « app ») est la représentation d’un de vos SaaS dans einvoice. Lorsqu’un de vos clients paie via le paywall, einvoice :

Crée la session de paiement sous le nom de votre application
Encaisse le paiement via votre passerelle de paiement (Berexia)
Émet une facture à votre client (B2C ou B2B)
Envoie un webhook signé à votre URL pour que vous provisiez l’accès

Créer une application

Allez dans Entreprise → Paramètres → Applications
Cliquez sur “Créer une application”
Remplissez le formulaire :
- Nom : nom affiché de votre SaaS (ex. : « Mon Application »)
- Slug : identifiant court unique (ex. : mon-app) — utilisé dans les préfixes de clés API
- URL Webhook : URL de votre serveur pour recevoir les notifications de paiement
- URL de succès : page vers laquelle rediriger après un paiement réussi (optionnel)
- URL d’annulation : page de retour en cas d’abandon (optionnel)
Cliquez sur “Créer”

Important — Copiez le secret webhook immédiatement. Après la création, le secret webhook est affiché une seule fois. Copiez-le et stockez-le en lieu sûr (variable d’environnement). Il ne sera plus accessible ensuite.

Comprendre les clés API

Les clés API sécurisent la communication entre votre serveur et l’API einvoice. Il en existe deux types :

Clé applicative (`ek_`)

Préfixe : ek_{slug}_
Portée limitée à une seule application
Utilisée côté serveur pour créer des sessions de paiement
Recommandée pour l’intégration d’une application spécifique

Clé société (`ck_`)

Préfixe : ck_{slug}_
Accès complet à toutes les données de votre compte
Utilisée pour les intégrations globales (ex. : outils de gestion internes)
À utiliser avec précaution — accès plus large

Règles de sécurité fondamentales

Une clé API est affichée une seule fois à la création — copiez-la immédiatement
Ne jamais inclure une clé API dans le code frontend ou dans le SDK côté client
Stockez les clés dans des variables d’environnement côté serveur
Faites tourner vos clés régulièrement (rotation)

Générer une clé API

Dans la liste des applications, cliquez sur “Voir les clés” de l’application concernée
Cliquez sur “Créer une clé”
Donnez un nom descriptif à la clé (ex. : « Production », « Serveur Node.js »)
Cliquez sur “Créer”
Copiez immédiatement la clé affichée — elle ne sera plus visible après fermeture

Rotation d’une clé API

La rotation génère une nouvelle clé et laisse l’ancienne active pendant 24 heures (période de grâce), le temps de déployer la nouvelle.

Sur la ligne de la clé concernée, cliquez sur “Faire tourner”
Confirmez l’opération
Récupérez la nouvelle clé dans la boîte d’affichage
Mettez à jour votre variable d’environnement
L’ancienne clé s’invalidera automatiquement après 24 heures

Révoquer une clé API

La révocation est immédiate et irréversible. Toute requête utilisant cette clé sera refusée.

Sur la ligne de la clé concernée, cliquez sur “Révoquer”
Confirmez dans la boîte de dialogue
La clé est désactivée instantanément

Utilisez la rotation (et non la révocation) si vous souhaitez remplacer une clé sans interruption de service.

Secret webhook

Le secret webhook est utilisé pour vérifier l’authenticité des notifications envoyées par einvoice à votre serveur. Il est généré automatiquement lors de la création de l’application.

Régénérer le secret webhook

Si votre secret est compromis, régénérez-le :

Dans la vue d’une application, cliquez sur “Régénérer le secret”
Confirmez l’opération
Copiez immédiatement le nouveau secret affiché
Mettez à jour votre variable d’environnement

Toute régénération invalide immédiatement l’ancien secret. Les webhooks non vérifiables seront rejetés par votre serveur.

Vérifier un webhook reçu

Votre serveur doit vérifier la signature de chaque webhook pour rejeter les requêtes frauduleuses.

En-têtes envoyés par einvoice :

X-Einvoice-Event : nom de l’événement (subscription.activated, payment.succeeded, subscription.renewed)
X-Einvoice-Signature : signature HMAC-SHA256 du corps de la requête

Exemple de vérification (Node.js) :

const sig = req.headers['x-einvoice-signature'];
const expected = crypto.createHmac('sha256', process.env.EINVOICE_WEBHOOK_SECRET)
  .update(JSON.stringify(req.body)).digest('hex');
if (sig !== expected) return res.status(401).send('Signature invalide');

Livraisons de webhooks échouées

En bas de la page Applications, la section “Livraisons échouées” liste les webhooks qui n’ont pas pu être livrés après 5 tentatives (délais : immédiat → 1 min → 5 min → 30 min → 2 h).

Pour chaque livraison échouée, vous verrez :

L’événement concerné
Le numéro de la tentative
La date d’occurrence
La référence externe associée (votre identifiant utilisateur)

Vérifiez que votre URL webhook est accessible publiquement et renvoie un code HTTP 200 pour chaque événement.

Intégrer le paywall SDK

Pour afficher les plans de votre application sur votre site, ajoutez le script einvoice :

Affichage simple des plans :

<script src="https://app.einvoice.ma/paywall.js"
  data-app="VOTRE_APP_ID" data-target="#pricing">
</script>

Paiement avec session serveur : Votre serveur crée d’abord une session de paiement via l’API, puis passe l’identifiant au SDK :

<script src="https://app.einvoice.ma/paywall.js"></script>
<script>
  const paywall = new EinvoicePaywall({ app: 'VOTRE_APP_ID' });
  paywall.checkout(sessionId, '#pricing');
  paywall.on('success', (data) => {
    // data.subscription_id, data.plan_slug, data.external_ref
    window.location.href = '/bienvenue';
  });
</script>

La clé API ne doit jamais être incluse dans le code frontend. L’identité de l’acheteur est définie exclusivement côté serveur lors de la création de la session.

Ressources pour vos développeurs

Partagez ces ressources avec l’équipe technique qui intégrera einvoice :

Guide d’intégration — flux complet du backend au frontend : developers.einvoice.ma/integration
Référence SDK — API EinvoicePaywall, attributs data-*, événements : developers.einvoice.ma/sdk
Vérification des webhooks — signature HMAC, événements, relances : developers.einvoice.ma/webhooks/verification

Conseils et bonnes pratiques

Nommez les clés par environnement : « Production », « Staging », « CI » pour une rotation facile
Tournez les clés régulièrement (tous les 90 jours recommandés)
Testez les webhooks avec un outil comme Webhook.site avant la mise en production
Surveillez les livraisons échouées après chaque déploiement de votre serveur
Répondez rapidement (HTTP 200) aux webhooks — einvoice attend une réponse en moins de 10 secondes

Résolution des problèmes

La clé API est rejetée (401)

Vérifiez que vous envoyez l’en-tête X-API-Key: ek_... dans la requête
Confirmez que la clé est active (pas révoquée) dans la liste des clés
La clé en rotation peut encore fonctionner pendant 24 heures — vérifiez la date d’expiration

Le webhook n’arrive pas

Vérifiez que l’URL webhook est accessible depuis internet (pas localhost)
Assurez-vous que votre serveur renvoie HTTP 200 — tout autre code déclenche une relance
Consultez la section “Livraisons échouées” pour identifier l’erreur

Le secret webhook est incorrect

Vérifiez que vous utilisez le corps brut de la requête (pas l’objet parsé)
En Node.js : utilisez express.raw() ou express.json() avant le middleware de signature
Si le secret a changé (régénéré), mettez à jour votre variable d’environnement

Le SDK ne charge pas les plans

Vérifiez que data-app correspond bien à l’identifiant de votre application
L’endpoint /rpc/get_app_plans est public, aucune clé API n’est nécessaire côté client
Vérifiez la console du navigateur pour les erreurs CORS ou réseau

Besoin d’aide ? Contactez notre support technique.