1. Accueil
  2. /
  3. Guide Admin
  4. /
  5. Intégrations
  6. /
  7. Stripe Invoice — Guide ad...

Stripe Invoice — Guide administrateur

Avant de configurer Stripe, l’organisation Cirrus Shield doit contenir les objets, champs, le plugin et l’application connectée décrits ici, avec exactement ces noms API.

Vue d’ensemble

Stripe Invoice lit les données ci-dessous par leur nom API et n’écrit que deux champs de la facture : Payment_Status et Payment_Date. Un nom API différent (par exemple Facture ou Statut_de_paiement) empêche l’application de trouver la donnée.

Objet (nom API)Champs utilisés (noms API)À créer ?Lu / écrit
InvoiceInvoice_Number, Contact, Amount, VAT, Payment_Status, Payment_Date, Due_Date, Pay_URLOui (objet personnalisé)Lu ; Payment_Status et Payment_Date écrits après paiement
Invoice_Line_ItemInvoice, Product, Quantity, Discount, Price, Total_PriceOui (objet personnalisé)Lu
ContactEmail, Work_Phone, Street, City, Country, ZIPNon (standard)Lu
ProductName, Product_Code, Default_Unit_PriceNon (standard)Lu
OrganisationDevise de base, logoNon (paramètres de l’organisation)Lu

Le libellé est libre, le nom API ne l’est pas. Créez chaque objet et champ avec le nom API exact du tableau. Une fois créé, vous pouvez changer son libellé (par exemple « Facture », « Statut de paiement ») : l’application ne lit que le nom API.

Valeurs de liste : Payment_Status doit avoir les valeurs Unpaid et Paid exactement. Le bouton de paiement n’apparaît que si le statut vaut Unpaid, et l’application écrit Paid après paiement.

Étape 1 — Vérifier l’objet Invoice et ses champs (sinon les créer)

Dans Setup → Objets, vérifiez qu’un objet avec le nom API Invoice existe et qu’il a les champs ci-dessous avec ces noms API et ces types. Créez l’objet ou les champs qui manquent (libellé au choix, par exemple « Facture »). Pour créer le champ Amount, l’objet Invoice_Line_Item (Étape 2) doit déjà exister : c’est un cumul de ses lignes.

Menu Setup de Cirrus Shield : Objets, Onglets, Applications, Intégration, Gestion des utilisateurs, Organisation, Modèle de page, Modèles, Historique des connexions, Extensions, Importation de données, Applications connectées
Le menu Setup : Objets pour les Étapes 1 à 3, Extensions et Applications connectées pour les Étapes 7 et 8.
Détail de l'objet personnalisé Facture : étiquette Facture, nom Invoice
Détail de l’objet : l’étiquette est « Facture », le Nom (nom API) est Invoice. C’est le nom qui compte.
Libellé suggéréNom API (obligatoire)TypeParamètres
Numéro de factureInvoice_NumberNuméro automatique ou TextePar exemple préfixe Inv-, format 00000, début 1
ContactContactRelation de rechercheLié à Contact
MontantAmountCumulatifObjet agrégé Invoice_Line_Item (Ligne de Facture), type de cumul Somme, champ à agréger Total_Price (Prix total)
TVA (%)VATNombreLongueur 3, décimales 2 ; c’est un taux (20 = 20 %)
Statut de paiementPayment_StatusListe de sélectionValeurs dont le Nom est Unpaid et Paid (voir ci-dessous)
Date de paiementPayment_DateDate/Heure—
Date d’échéanceDue_DateDate—
Lien de paiementPay_URLFormule (Texte)Voir l’Étape 3

Pour ajouter un champ : onglet Champs personnalisés de l’objet, bouton +, choisissez le type, puis saisissez l’Étiquette et le Nom.

Étape 1 de 2 de la création d'un champ : liste des types de données (Case à cocher, Cumulatif, Date, Devise, Formule, Nombre, Liste de sélection, ...)
Choix du type de données (Étape 1 de 2 de l’assistant).
Champ Cumulatif : étiquette Montant, nom Amount, objet agrégé Ligne de Facture, type de cumul Somme, champ à agréger Prix total
Le champ Amount : Cumulatif, objet agrégé Ligne de Facture, Somme de Prix total.
Champ Nombre : étiquette TVA (%), nom VAT, longueur 3, décimales 2
Le champ VAT : Nombre, longueur 3, 2 décimales.
  • Organisation standard Cirrus Shield : l’objet Facture existe souvent déjà avec le nom API Invoice et les champs Invoice_Number, Contact, Payment_Status, Payment_Date, Due_Date et Pay_URL. Il faut en général seulement ajouter Amount, VAT et les valeurs Unpaid / Paid.
  • Valeurs de Payment_Status : dans le détail du champ, Valeurs de la liste de sélection → +, saisissez Unpaid puis Paid (une valeur par ligne) et enregistrez. Cirrus Shield donne à chaque valeur le même Nom (Unpaid, Paid). Gardez ces noms. Les nouvelles factures à payer doivent avoir le statut Unpaid (cochez-le comme Valeur par défaut si toutes vos factures passent par Stripe).
  • Montant payé par le client : Stripe Invoice encaisse le Total = Montant + Montant × TVA / 100. Le montant de TVA et le total sont calculés par l’application.
  • Statut et date : après le paiement, l’application écrit Payment_Status = Paid et Payment_Date (heure UTC). Ne les rendez pas obligatoires.
  • Enregistrement du cumul : l’enregistrement du champ Amount peut prendre environ une minute, le temps que Cirrus Shield calcule le montant de toutes les factures. Attendez sans recharger la page.
  • Renommer après coup : vous pouvez changer le libellé de l’objet et de chaque champ (par exemple « Statut », « Réglée le »). Le nom API ne doit pas changer.
Valeurs de la liste de sélection du champ Statut (Payment_Status) : Unpaid, Non Envoyée (par défaut), Paid, Envoyée au Client, Payée Partiellement, Payée en Totalité, Annulée/ Supprimée
Payment_Status après ajout : les valeurs Unpaid et Paid (même Valeur et Nom) côtoient les valeurs existantes de l’organisation ; ici la valeur par défaut est restée « Non Envoyée ».

Étape 2 — Vérifier l’objet Invoice_Line_Item et ses champs (sinon les créer)

Vérifiez qu’un objet avec le nom API Invoice_Line_Item existe avec les champs ci-dessous ; sinon créez-le ou ajoutez les champs manquants (libellé au choix, par exemple « Ligne de facture »). Chaque ligne s’affiche sur la page de paiement avec son produit, sa quantité, son prix, sa remise et son total.

Libellé suggéréNom API (obligatoire)TypeParamètres
FactureInvoiceRelation de rechercheLié à Invoice (Facture)
ProduitProductRelation de rechercheLié à Product (Produit)
QuantitéQuantityNombre—
Remise (%)DiscountNombre ou Pourcentage10 = 10 %
PrixPriceFormule, type de renvoi Devise, 2 décimalesProduct__ro.Product__ro.Default_Unit_Price * Quantity
Prix totalTotal_PriceFormule, type de renvoi Devise, 2 décimalesPrice - Price * Discount / 100

La syntaxe Product__ro.Product__ro.<champ> (champ de recherche, puis objet) est celle qu’accepte l’éditeur de formules ; l’ancienne forme Product__ro.Default_Unit_Price est refusée (« Erreur dans la syntaxe »). Cliquez sur l’icône de vérification à droite de la formule : Cirrus Shield doit afficher « La syntaxe de la formule est correcte ! ».

Remise vide : sur Price et Total_Price, cochez Les champs vides vont être considérés comme des zéros. Sinon une ligne sans remise a un Prix total vide et la facture un montant de 0.

Case cochée : Les champs vides vont être considérés comme des zéros
L’option à cocher dans le formulaire du champ formule.

Factures existantes : le cumul Amount ne se recalcule que lorsqu’une ligne est enregistrée. Après avoir créé ou modifié ces champs, ouvrez et enregistrez à nouveau les lignes des factures à payer.

Champ formule Prix : type de renvoi Devise, 2 décimales, formule Product__ro.Product__ro.Default_Unit_Price * Quantity, message La syntaxe de la formule est correcte
Le champ Price : renvoi Devise, 2 décimales, et la formule acceptée par la vérification.
  • Ordre de création : créez Invoice et Product avant les formules, car Price lit le prix unitaire du produit lié (Product__ro.Product__ro.Default_Unit_Price).
  • Lien avec le montant : le champ Amount de la facture (Étape 1) additionne Total_Price de toutes ses lignes. Créez-le après cet objet.
  • Libellés : comme pour la facture, renommez librement les libellés ensuite, mais gardez les noms API.

Étape 3 — Vérifier le lien de paiement Pay_URL (sinon le créer)

Sur l’objet Invoice, vérifiez qu’un champ Formule avec le nom API Pay_URL et le type de retour Texte existe et contient la formule ci-dessous ; sinon créez-le ou corrigez sa formule. Il affiche sur chaque facture le lien à envoyer au client (par exemple par e-mail).

HyperLink("https://stripe.cirrus-shield.net/Payment.php?i=" + Id + "&o=" + $Organization.Id, "Payer")
Détail du champ Lien de paiement : nom Pay_URL, type de renvoi Texte, formule HyperLink vers stripe.cirrus-shield.net/Payment.php
Le champ Pay_URL (étiquette « Lien de paiement ») avec la formule, ici avec le texte de lien "Pay".
  • Ne changez pas l’adresse : https://stripe.cirrus-shield.net/Payment.php?i=…&o=… est l’adresse que l’application attend. Les anciennes formules en payment.php (minuscules) fonctionnent aussi.
  • Texte du lien : "Payer" est libre (par exemple "Pay").
  • Ce que voit le client : la facture (en-tête, contact, lignes, TVA, total), puis le bouton de paiement qui ouvre la page de paiement Stripe. Une facture déjà payée s’affiche sans bouton.

Étape 4 — Vérifier les champs standard utilisés

Ces champs existent déjà dans Cirrus Shield : rien à créer, mais ils doivent être remplis pour que la facture s’affiche complètement.

ObjetChamps (noms API)Utilisé pour
ContactEmail, Work_Phone, Street, City, Country, ZIPBloc « client » de la page de paiement
ProductName, Product_Code, Default_Unit_PriceNom et code de chaque ligne ; prix unitaire lu par la formule Price
OrganisationDevise de base, logoDevise du paiement ; logo en haut de la page (logo Cirrus Shield si absent)
  • Devise : le paiement se fait dans la devise de base de l’organisation (Setup → Organisation). Vérifiez-la avant le premier paiement.
  • Logo : ajoutez le logo de l’organisation dans Setup → Organisation pour qu’il apparaisse sur la page de paiement.

Étape 5 — Afficher les factures aux utilisateurs

Ces réglages ne changent rien pour l’application : ils permettent aux utilisateurs de créer les factures et de voir le lien de paiement.

  1. Onglet : Setup → Onglets → Nouveau, type Objet, objet personnalisé Invoice (libellé au choix).
  2. Profils : dans le détail de l’onglet, rubrique Profils → Modifier les profils, ajoutez les profils qui doivent voir les factures.
  3. Application : Setup → Applications, ouvrez l’application concernée (par exemple CRM), rubrique Onglets → Modifier, ajoutez Invoice, enregistrez. L’onglet apparaît dans le menu de gauche.
  4. Mise en page : créez une mise en page (page designer) pour Invoice_Line_Item, puis une pour Invoice. Dans celle de la facture, ajoutez une section avec la liste associée Invoice_Line_Item et le champ Pay_URL. Cochez Onglets pour afficher la section en onglet.

L’ancienne page web « InvoiceUsers_Management.php » n’est plus utilisée : ne créez pas d’onglet web vers cette adresse.

Étape 6 — Vérifier les objets et les champs

Avant d’installer le plugin, contrôlez les noms API dans Setup → Objets : c’est la cause la plus fréquente d’une facture qui ne s’affiche pas.

  • ☐ L’objet Invoice existe et son nom API est Invoice.
  • ☐ Ses champs ont les noms API Invoice_Number, Contact, Amount, VAT, Payment_Status, Payment_Date, Due_Date, Pay_URL.
  • ☐ Payment_Status contient les valeurs Unpaid et Paid ; Unpaid est la valeur par défaut.
  • ☐ L’objet Invoice_Line_Item existe avec Invoice, Product, Quantity, Discount, Price, Total_Price.
  • ☐ Une facture de test avec au moins une ligne affiche un Montant non nul et un lien Payer.
  • ☐ Le contact de la facture a une adresse e-mail ; l’organisation a sa devise de base (et son logo).

Une organisation créée avec l’ancienne aide en français peut avoir les noms Facture, Ligne_de_facture, Statut_de_paiement, Date_de_paiement, Payer_URL ou les valeurs Payé / Non payé. Ces noms ne sont pas reconnus : créez les objets et champs avec les noms API ci-dessus.

Étape 7 — Vérifier l’extension et l’application connectée

Stripe Invoice se connecte à Cirrus Shield par une application connectée confidentielle (OAuth 2.0) liée à l’extension Stripe Invoice : aucun identifiant ni mot de passe Cirrus Shield n’est saisi dans l’application. Le Support Cirrus Shield installe ces deux éléments ; vous vérifiez seulement qu’ils sont présents et actifs.

  • ☐ Setup → Extensions : la ligne Stripe Invoice existe et la case Installé est cochée.
  • ☐ Setup → Applications connectées : la ligne Stripe Invoice Confidentiel existe, de type Confidentiel, portées api:read,api:write, Statut coché.

Si l’une des deux manque ou n’est pas active, contactez le Support Cirrus Shield.

Liste Extensions : Stripe Invoice, case Installé cochée
Setup → Extensions après installation : Stripe Invoice a la case Installé cochée (liste réduite à cette ligne).
Liste Applications connectées : Stripe Invoice Confidentiel, type Confidentiel, portées api:read,api:write, statut actif
Setup → Applications connectées : Stripe Invoice Confidentiel, type Confidentiel, portées api:read,api:write, statut actif (identifiant client masqué).
  • Utilisateur associé : ouvrez le Détail de Stripe Invoice Confidentiel et vérifiez qu’un utilisateur associé est renseigné. Il doit pouvoir lire Invoice, Invoice_Line_Item, Contact, Product et l’organisation, et modifier Invoice.

Étape 8 — Ouvrir la configuration du plugin

Dans Setup → Extensions → Stripe Invoice, ouvrez le détail du plugin. Cirrus Shield affiche la page de configuration de Stripe Invoice et lui transmet les identifiants de l’application connectée.

  • Attendu : « The Cirrus Shield connection is configured. », avec le serveur (Production ou Beta) et l’identifiant de l’organisation. La même page sert ensuite à saisir les clés Stripe et l’e-mail d’alerte (voir la configuration Stripe).
  • Toujours depuis le plugin : ouvrez cette page depuis Cirrus Shield, jamais par un lien enregistré. Cirrus Shield transmet un nouveau secret à chaque affichage, et l’application l’enregistre à chaque ouverture.
Message affichéCauseQue faire
Open this page from the Stripe Invoice plugin in Cirrus Shield Setup.Page ouverte hors du plugin, ou aucune application connectée active liéeVérifier l’Étape 7 (extension installée, application connectée active ; sinon contacter le Support), puis rouvrir depuis le plugin
The Connected App needs an Associated User.L’application connectée n’a pas d’utilisateur associéRenseigner l’utilisateur associé dans Applications connectées
Cirrus Shield did not accept these credentials.Secret refusé (régénéré ou application inactive)Rouvrir la page depuis le plugin ; vérifier que le plugin est installé
Cirrus Shield could not be reached.Serveur Cirrus Shield injoignableRéessayer plus tard

Configuration Stripe

Une fois les prérequis en place, l’administrateur relie l’organisation à son propre compte Stripe : les paiements arrivent directement sur ce compte.

Étape 9 — Compte Stripe et clés API

  1. Créez un compte sur stripe.com si l’organisation n’en a pas : c’est sur ce compte que l’argent des factures payées est versé.
  2. Dans le tableau de bord Stripe, ouvrez Développeurs → Clés API. Deux clés sont nécessaires : la clé publiable (pk_…) et la clé secrète (sk_…, ou une clé restreinte rk_…).
  3. Test ou réel : pour essayer, utilisez les clés du mode test (pk_test_…, sk_test_…) : aucun vrai paiement n’est encaissé. Pour encaisser réellement, utilisez les clés live (pk_live_…, sk_live_…).

Ne communiquez jamais la clé secrète par e-mail ou dans un ticket : saisissez-la uniquement dans la page de configuration (Étape 10).

Étape 10 — Saisir les clés Stripe et l’e-mail d’alerte

Ouvrez le détail de l’extension Stripe Invoice (Étape 8). Sous « The Cirrus Shield connection is configured. », la page affiche :

  • Stripe keys : l’état de chaque clé (set / not set) et, avec des clés de test, le bandeau TEST MODE (aucun vrai paiement).
  • Publishable key / Secret key : collez les deux clés de l’Étape 9. Laissez un champ vide pour garder la clé déjà enregistrée. Les clés ne sont jamais réaffichées.
  • Alert email : l’adresse de l’administrateur. Un e-mail est envoyé par noreply@cirrus-shield.com si Cirrus Shield n’accepte plus les identifiants de l’extension ; les clients voient alors une page « paiement temporairement indisponible ».
Page Stripe Invoice — configuration : The Cirrus Shield connection is configured, serveur Beta, clés not set, adresse du webhook, champs Publishable key, Secret key, Webhook signing secret, Alert email, bouton Save
La page de configuration ouverte depuis l’extension, avant la saisie des clés (« not set ») ; l’adresse du webhook se termine par l’identifiant de l’organisation.

Cliquez sur Save : la page affiche « Settings saved. ». Pour changer de clés plus tard (par exemple passer du test au réel), rouvrez le détail de l’extension et recommencez.

Étape 11 — Créer le webhook Stripe

Le webhook permet d’enregistrer le paiement dans Cirrus Shield même si le client ferme sa page avant la fin.

  1. Dans la page de configuration, rubrique Stripe webhook, copiez l’adresse affichée : https://stripe.cirrus-shield.net/stripe/webhook/<identifiant de l'organisation>.
  2. Dans le tableau de bord Stripe, ouvrez Développeurs → Webhooks → Ajouter un endpoint, collez l’adresse et sélectionnez l’événement checkout.session.completed.
  3. Copiez le secret de signature de l’endpoint (whsec_…) et collez-le dans le champ Webhook signing secret de la page de configuration, puis Save. L’état passe à « Webhook signing secret: set ».

Le webhook se crée dans le même mode que les clés : en mode test avec des clés de test, en mode live avec des clés live.

Étape 12 — Faire un paiement de test

Avec des clés de test (bandeau TEST MODE), vérifiez tout le parcours avant de passer aux clés live :

  1. Créez une facture Unpaid avec un contact, au moins une ligne (produit avec un prix unitaire par défaut) et un taux de TVA.
  2. Ouvrez son lien de paiement : la facture s’affiche avec le Total = Montant + TVA et le bouton Pay with Card.
  3. Payez avec la carte de test Stripe 4242 4242 4242 4242, une date d’expiration future et n’importe quel code.
  4. Vérifiez : page « Payment received — thank you », facture passée à Paid avec sa date de paiement, paiement visible dans le tableau de bord Stripe (mode test), et dans Webhooks une livraison réussie de checkout.session.completed.

Ce que voient ensuite les utilisateurs et leurs clients est décrit dans le Guide utilisateur Stripe Invoice.

Cet article vous a-t-il été utile ? Non Oui

Comment pouvons-nous aider ?