@spiritpay/node

SDK officiel Spirit Pay (Node.js) : factures B2B, caisse (POS) et webhooks.

Installation

npm install @spiritpay/node

Prérequis marchand

• Compte Spirit Pay + clé sk_test_… / sk_live_… (page « Clés API », serveur uniquement).
• IBAN de reversement valide sur le profil marchand (obligatoire en production pour POS et encaissement).
• Pour le POS : votre logiciel de caisse appelle l’API ; Spirit Pay gère Bridge et le QR.

Cas d’usage

| Intégration | SDK | Cible typique | |-------------|-----|----------------| | Checkout e-commerce | checkout.create | Site custom, panier multi-lignes → Bridge | | Devis / app métier (bouton paiement) | checkout.create | Devis validé → Bridge direct (hors panier) | | Factures + e-mail payeur | invoices.create | ERP custom, middleware, Odoo via code | | Caisse / QR dynamique | pos.create | Grands comptes, retail, tablette kiosque | | Confirmation serveur | webhooks.verifySignature | Tous flux API |

Les connecteurs ERP du dashboard (INFast, Abby, Odoo module zip…) ne passent pas par ce npm : le marchand configure l’ERP dans Spirit Pay.

Checkout e-commerce : panier → Bridge

Flux recommandé pour un site codé de A à Z (sans Shopify) : votre backend appelle Spirit Pay au clic « Payer », le client est redirigé directement vers sa banque (Bridge).

import { createClient } from '@spiritpay/node';

const spiritpay = createClient({
  apiKey: process.env.SPIRITPAY_API_KEY, // sk_test_... / sk_live_...
  environment: 'test'
});

// Depuis votre route POST /checkout (serveur)
const session = await spiritpay.checkout.create({
  lineItems: [
    { name: 'Fauteuil scandinave', quantity: 1, unitPriceHt: 100, vatRate: 20 }
  ],
  customer: {
    name: req.body.customerName,   // déjà saisi sur VOTRE page checkout
    email: req.body.customerEmail
  },
  orderRef: 'WEB-8842',
  currency: 'EUR',
  successUrl: 'https://boutique.exemple.com/commande/ok',
  cancelUrl: 'https://boutique.exemple.com/commande/annule',
  sendConfirmationEmail: false   // pas d'e-mail Spirit Pay au payeur
});

// Rediriger le navigateur du client
res.redirect(session.bridgeRedirectURL);

• Nom + e-mail : à collecter sur votre page checkout (compte client ou invité), sans modal Spirit Pay intermédiaire.
• successUrl / cancelUrl (HTTPS, optionnels) : retour sur votre portail après paiement validé ou annulé côté Bridge. Spirit Pay ajoute paymentId, status, orderRef, sig en query. Sans ces URLs → page Spirit Pay /payment-success.
• sendConfirmationEmail: false : pas d’e-mail de confirmation au payeur (webhook marchand inchangé).
• Webhook : écoutez payment.executed pour marquer la commande ou le devis payé côté serveur (dashboard → Webhooks). Ne vous fiez pas uniquement au retour navigateur.
• Limite Bridge : si le client ferme l’onglet sans retour Bridge, cancelUrl n’est pas appelée — webhook ou polling statut.
• Boutique démo : /boutique-eu/[spiritId] sur spiritpay.fr.

Endpoint API : POST /api/ecommerce/checkout-session (auth Authorization: Bearer sk_…).

Devis & bouton paiement (hors e-commerce)

Pour un devis signé dans votre outil (CRM, logiciel sur mesure) : au clic « Payer », votre backend appelle checkout.create et redirige vers bridgeRedirectURL, même API que l’e-commerce, sans panier ni connecteur ERP dashboard.

const session = await spiritpay.checkout.create({
  lineItems: [
    { name: 'Devis DEV-2026-042', quantity: 1, unitPriceHt: 2500, vatRate: 20 }
  ],
  customer: { name: 'Client SAS', email: '[email protected]' },
  orderRef: 'DEV-2026-042',
  currency: 'EUR',
  successUrl: 'https://portail.exemple.com/devis/DEV-2026-042/paiement-ok',
  cancelUrl: 'https://portail.exemple.com/devis/DEV-2026-042/paiement-annule',
  sendConfirmationEmail: false
});

res.redirect(session.bridgeRedirectURL);

Redirection (successUrl / cancelUrl) = UX navigateur quand Bridge renvoie l’utilisateur. Webhook payment.executed = vérité serveur pour marquer le devis payé. Si le client ferme l’onglet sans retour Bridge, cancelUrl n’est pas appelée.

Si vous préférez une référence facture, une échéance ou un e-mail Spirit Pay : utilisez invoices.create (voir ci-dessous). Doc complète : spiritpay.fr/docs#devis-encaissement.

POS : caisse et QR (grand groupe / retail)

Flux : votre caisse envoie le montant → Spirit Pay renvoie un QR (URL Bridge) → le client scanne et paie par virement instantané vers le compte du marchand (pas de TPE carte).

import { createClient } from '@spiritpay/node';

const spiritpay = createClient({
  apiKey: process.env.SPIRITPAY_API_KEY, // sk_live_...
  environment: 'production'
});

// Montant en centimes pour EUR (15000 = 150,00 €)
const sale = await spiritpay.pos.create({
  amount: 15000,
  currency: 'EUR',
  terminalId: 'boutique-paris-01',
  label: 'Ticket caisse T-8842',
  erpOrderId: 'SO-2026-8842' // optionnel, rapprochement ERP
});

// Afficher le QR sur tablette (data URL PNG)
console.log(sale.qrCode);       // data:image/png;base64,...
console.log(sale.paymentLink);  // URL Bridge (même contenu que le QR)
console.log(sale.expiresAt);    // expiration courte (~5 min)
console.log(sale.paymentId);

// Option A : polling depuis le middleware caisse
const poll = async () => {
  const st = await spiritpay.pos.getStatus(sale.paymentId);
  if (st.status === 'completed') {
    console.log('Payé', st.executedAt);
    return true;
  }
  return false;
};

// Option B : SSE sur navigateur kiosque (poste sécurisé uniquement)
// const url = spiritpay.pos.getEventSourceUrl(sale.paymentId);
// const es = new EventSource(url); // ready + payment.status

Sécurité POS

• Ne mettez jamais sk_live_… dans une app mobile ou web grand public.
• Intégration recommandée : serveur caisse ou kiosque verrouillé qui appelle l’API, puis affiche le QR.
• getEventSourceUrl expose la clé en query (?token=) : réservé au kiosque dédié (comme l’écran POS du dashboard développeur).

Factures : lien de paiement

const payment = await spiritpay.invoices.create({
  amount: 10000,
  currency: 'EUR',
  invoiceRef: 'FAC-2026-001',
  dueDate: '2026-05-06',
  payerName: 'Client SAS',
  payerEmail: '[email protected]',
  sendEmail: true,
  erpProvider: 'odoo',
  erpInvoiceId: '12345'
});

console.log(payment.paymentLink);

Webhooks

Configurez l’URL HTTPS dans le dashboard Spirit Pay (menu Webhooks). Spirit Pay envoie un suffixe /spirit_pay/webhook si absent (ex. https://api.votre-app.com/hooks → …/hooks/spirit_pay/webhook).

Événements utiles : payment.executed (payé), payment.scheduled (programmé), payment.failed (échec).

import express from 'express';
import { createClient } from '@spiritpay/node';

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

// Corps brut obligatoire pour la signature
app.post(
  '/spirit_pay/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const ok = spiritpay.webhooks.verifySignature({
      secret: process.env.SPIRITPAY_WEBHOOK_SECRET, // whsec_… (affiché une fois à la création)
      headers: req.headers,
      rawBody: req.body
    });
    if (!ok) return res.status(401).send('Invalid signature');

    const payload = JSON.parse(req.body.toString('utf8'));
    if (payload.event === 'payment.executed') {
      // Marquer commande / devis payé (payload.payment_id, payload.invoice_ref, payload.amount)
    }
    res.json({ received: true });
  }
);

Documentation

• API publique : spiritpay.fr/docs (section POS + SDK).
• Support : [email protected]