Documentation développeur

Introduction

Spirit Pay permet d’encaisser par virement instantané (Open Banking, via Bridge) à partir d’un lien ou d’un QR code. Vous pilotez tout depuis votre backend : création de lien, relances, réception des statuts par webhook.

Trois familles de parcours coexistent : envoi du lien par Spirit Pay (mode A), récupération du lien pour vos propres canaux (mode B), et encaissement en point de vente avec QR dynamique (mode C, POS).

La plateforme n’est pas limitée à quelques ERP nommés sur le site : vous choisissez comment brancher votre environnement. Les connecteurs Odoo, Abby, Axonaut ou Sage sont des entrées prêtes à l’emploi, pas un périmètre fermé. Les équipes qui veulent uniquement le moteur paiement utilisent l’API et le SDK npm comme tout service financier standard.

Démarrage rapide

Si vous appelez l’API Spirit Pay depuis votre code ou un module type Odoo, créez un compte développeur, activez l’environnement test, puis récupérez une clé secrète dans la rubrique dédiée aux clés API. Ne collez jamais une clé secrète dans une application frontale exposée aux navigateurs.

1. Inscription et validation de l’espace marchand.
2. Génération d’une clé sk_test_… réservée au serveur.
3. Installation du paquet npm officiel (ci-dessous) ou appels HTTP directs.
4. Déclaration d’une URL de webhook HTTPS accessible depuis Internet.
5. Test du parcours payeur sur un lien généré en simulation.

Tester chez vous avec npm : il vous faut une clé secrète sk_test_… émise par Spirit Pay depuis votre compte (page « Clés API » après inscription). On retrouve la même idée qu’un bac à sable : vous codez et vous appelez notre API avec le préfixe test, les paiements restent en simulation. Quand le compte est prêt pour le réel, vous utilisez une clé sk_live_… sur votre backend de production. Vous ne configurez pas à la place des « clés Bridge » côté npm pour parler à Spirit Pay : votre application s’authentifie auprès de l’API Spirit Pay, et la couche bancaire réglementée est gérée dans notre infrastructure.

// 1. Installer le SDK
npm install @spiritpay/node

// 2. Initialiser
import { createClient } from '@spiritpay/node';

const spiritpay = createClient({ apiKey: 'sk_test_...' });

// 3. Créer un lien de paiement
const payment = await spiritpay.invoices.create({
  amount: 10000,
  currency: 'EUR',
  invoiceRef: 'FAC-2024-001',
  dueDate: '2026-03-30',
  invoiceAmountHT: 8333,
  invoiceAmountTVA: 1667,
  vatBreakdown: [{ rate: 20, base: 8333, vat: 1667 }],
  payerName: 'Client SAS',
  payerEmail: 'client@exemple.com',
  sendEmail: true,
});

console.log(payment.paymentLink);

Besoin des clés tout de suite ? Créer un compte développeur puis ouvrez la page « Clés API » une fois connecté.

Authentification

Chaque requête vers l’API doit inclure un jeton Bearer correspondant à votre clé secrète de compte. Les préfixes sk_test_ et sk_live_ distinguent simulation et production.

En-tête obligatoire

Authorization: Bearer sk_test_votre_cle_secrete

Les clés publiques (pk_test_…) servent aux intégrations côté client lorsque le produit l’autorise explicitement. Par défaut, considérez que toute opération sensible passe par votre backend.

Référence API (aperçu)

L’URL de base utilisée dans les exemples est https://api.spiritpay.fr/api. Les chemins sont relatifs à cette racine. Les corps sont en JSON UTF-8 ; les réponses suivent les codes HTTP standards.

Créer un lien de paiement facture

Méthode et chemin : POST /invoice-payments/create-payment-link

POST https://api.spiritpay.fr/api/invoice-payments/create-payment-link
Content-Type: application/json
Authorization: Bearer sk_test_...

{
  "type": "invoice",
  "amount": 10000,
  "currency": "EUR",
  "invoiceRef": "FAC-2024-001",
  "dueDate": "2026-03-30",
  "invoiceAmountHT": 8333,
  "invoiceAmountTVA": 1667,
  "vatBreakdown": [{ "rate": 20, "base": 8333, "vat": 1667 }],
  "payerName": "Client SAS",
  "payerEmail": "client@exemple.com",
  "sendEmail": true,
  "erpProvider": "odoo",
  "erpInvoiceId": "12345"
}

Réponse typique (succès)

HTTP 201 Created
{
  "success": true,
  "paymentId": "pay_abc123",
  "paymentLink": "https://spiritpay.fr/pay/pay_abc123?type=invoice",
  "qrCode": "data:image/png;base64,...",
  "expiresAt": "2026-03-30T23:59:59Z"
}

Paramètres du corps (liaison facture)

D’autres routes (statuts, annulations selon produit, intégrations ERP dédiées) sont disponibles depuis votre tableau de bord une fois le compte activé. Les payloads exacts peuvent évoluer ; votre implémentation doit tolérer des champs additionnels ignorés.

Liens de paiement

Mode A. Spirit Pay envoie l’e-mail au client lorsque vous activez l’option correspondante dans la création de lien. Idéal lorsque vous ne maîtrisez pas encore le canal d’envoi ou lorsque vous voulez homogénéiser le template de message.

Mode B. Vous récupérez uniquement paymentLink et le QR, puis vous les placez dans votre PDF, votre ERP ou votre messagerie. Vous restez maître du wording et du moment d’envoi.

Dans les deux cas, conservez la référence facture et, si possible, l’identifiant ERP pour faciliter le rapprochement automatique après paiement.

POS (caisse)

Le flux caisse vise les paiements présentiels : pas de parcours e-mail classique, QR dynamique lié au montant saisi, confirmation pour votre logiciel de caisse. Utilisez SSE pour mettre à jour l’interface vendeur dès que le statut devient définitif.

Création

POST https://api.spiritpay.fr/api/pos/create-payment
Content-Type: application/json
Authorization: Bearer sk_test_...

{
  "amount": 1500000,
  "currency": "EUR",
  "terminalId": "caisse-1",
  "erpProvider": "odoo",
  "erpOrderId": "SO123",
  "erpInvoiceId": "INV123"
}

Suivi temps réel

GET https://api.spiritpay.fr/api/pos/payments/:paymentId/stream?token=...
Content-Type: text/event-stream

Événements typiques : ready, payment.status (completed indique paiement réussi).

Pour un prototype interactif, vous pouvez aussi passer par l’écran POS du tableau de bord développeur après connexion.

Webhooks

Les webhooks signalent les transitions utiles pour votre ERP ou votre middleware : programmation, réussite, échec. Configurez une URL HTTPS, vérifiez la signature fournie par Spirit Pay lorsque celle-ci est exposée dans votre espace, et répondez rapidement (idéal sous deux secondes).

La configuration détaillée des endpoints et des secrets de signature se fait dans la section Webhooks du dashboard après authentification.

Erreurs HTTP

Les corps d’erreur incluent en général un code métier lisible par machine et un message court. Évitez d’afficher brutalement ces messages aux utilisateurs finaux sans les contextualiser.

SDK et bibliothèques

Le SDK officiel Node.js encapsule l’authentification, la mise en forme des corps JSON et les erreurs réseau de base. Les autres langages peuvent appeler l’API via HTTPS standard en reprenant les exemples de cette page.

npm install @spiritpay/node

Python et PHP sont prévus ; annoncez votre besoin au support si vous souhaitez être informé des préversions.

FAQ développeur

Puis-je tester sans transaction réelle ?

Oui, l’environnement test simule les flux ; aucune instruction bancaire réelle n’est envoyée.

Où trouver mes clés ?

Dans votre espace connecté, menu réservé aux développeurs, entrée « Clés API ». Cette documentation publique n’affiche aucune clé.

Comment fonctionne la tarification côté API ?

La tarification marchande est indépendante du protocole d’appel : elle suit vos conditions contractuelles (offres Starter, Business ou Enterprise). Référez-vous à la page commerciale pour les grilles à jour.

Stockage des données sensibles

Ne persistez pas les IBAN ou jetons bancaires hors des cadres réglementaires. Utilisez les identifiants techniques renvoyés par Spirit Pay pour corréler paiement et facture.

Qualité, CI et exploitation

Le dépôt source est équipé d’une CI GitHub Actions : à chaque push ou pull request sur la branche principale, le frontend passe un build Next.js et le backend une vérification de syntaxe du serveur. Cela réduit le risque de livrer une régression qui ne compile plus.

Côté production, les journaux applicatifs doivent rester sans secrets (pas de clés complètes, pas d’en-têtes d’authentification bruts). Les équipes internes disposent d’un mémo dans le dépôt : fichier docs/exploitation-envergure.md (observabilité, SLA, évolutions possibles).

Les délais de réponse support et la disponibilité au sens contractuel sont fixés dans vos CGV ou dans une offre commerciale nominative (Business, Enterprise). Page Support pour les canaux de contact.