Skip to main content

spiritpay (Python)

SDK Python officiel de Spirit Pay : tout ce qu'un serveur Python a besoin pour intégrer le paiement par virement Open Banking, sans réécrire les appels HTTP.

Vous êtes… Client Clé
Une entreprise avec son propre serveur (site e-commerce, devis, caisse, CRM, facturation maison) Client sk_test_… / sk_live_…
Un éditeur d'ERP ou une coopérative qui gère plusieurs entreprises (enDI, Odoo, Dolibarr…) PartnerClient sp_test_partner_… / sp_live_partner_…
Un logiciel de paie, un cabinet ou un outil interne qui fait payer des salaires PayrollClient clé « salaires » sp_payroll_test_… / sp_payroll_live_…
  • Aucune dépendance (bibliothèque standard uniquement), Python ≥ 3.8.
  • Une clé de test reste en sandbox : aucun euro ne bouge. Les clés se gardent côté serveur uniquement.
  • Équivalent du SDK Node @spiritpay/node.
  • Les paramètres s'écrivent en snake_case (external_invoice_id) et sont convertis au format de l'API (externalInvoiceId).
pip install spiritpay

Client marchand (Client)

import os
from spiritpay import Client

spiritpay = Client(api_key=os.environ["SPIRITPAY_API_KEY"], environment="test")  # sk_test_… / sk_live_…

Checkout e-commerce, devis, bouton de paiement

session = spiritpay.checkout.create(
    line_items=[{"name": "Fauteuil scandinave", "quantity": 1, "unit_price_ht": 100, "vat_rate": 20}],
    customer={"name": "Client SAS", "email": "client@exemple.com"},
    order_ref="WEB-8842",
    success_url="https://boutique.exemple.com/commande/ok",
    cancel_url="https://boutique.exemple.com/commande/annule",
    send_confirmation_email=False,
)
# Redirigez le navigateur du client vers session["bridgeRedirectURL"].

Ne vous fiez pas seulement au retour navigateur : confirmez avec le webhook payment.executed.

Facture avec lien de paiement et e-mail

facture = spiritpay.invoices.create(
    amount=1200, invoice_ref="FAC-2026-001", payer_name="Client SAS",
    payer_email="client@exemple.com", send_email=True,
    invoice_amount_ht=1000, invoice_amount_tva=200,
)
print(facture["paymentLink"])

Caisse (POS) : QR dynamique

vente = spiritpay.pos.create(amount=15000, terminal_id="boutique-paris-01", label="Ticket T-8842")  # 15000 = 150,00 €
print(vente["qrCode"], vente["expiresAt"])

statut = spiritpay.pos.get_status(vente["paymentId"])   # statut["status"] == "completed" : encaissé

CRM : solde et échéancier

spiritpay.crm.pay_balance(crm_order_ref="CMD-7", amount=500, payer_email="client@exemple.com", deposit_paid=100)
plan = spiritpay.crm.create_payment_plan(crm_order_ref="CMD-7", total_amount=900, installments=3,
                                         first_due_date="2026-11-01", payer_email="client@exemple.com")
spiritpay.crm.get_plan(plan["planId"])

Webhooks marchand

# raw_body = corps brut de la requête (bytes, non re-sérialisé)
ok = Client.verify_webhook_signature(secret=os.environ["SPIRITPAY_WEBHOOK_SECRET"],
                                     headers=request.headers, raw_body=raw_body)   # en-tête X-Spirit-Pay-Signature

Client partenaire (PartnerClient)

Pour les ERP et coopératives. Détail ci-dessous.

from spiritpay import PartnerClient

spiritpay = PartnerClient(partner_key=os.environ["SPIRITPAY_PARTNER_KEY"])

Encaisser une facture client

link = spiritpay.invoices.create(
    external_invoice_id="497582",          # id de la facture dans votre ERP (idempotence)
    payer_name="Camille Martin",
    payer_email="client@exemple.com",
    amount=840,                            # euros
    invoice_ref="FC763-2610",
    immediate_only=True,
    issuer_external_id="12",               # enseigne qui émet la facture
    issuer_name="Auprès Fauteuil Remplacer.",  # affichée comme « sous-marchand » chez Spirit Pay
)
# Insérez link["paymentUrl"] dans l'e-mail (bouton « Payer »).

status = spiritpay.invoices.get(link["paymentId"])

Sans issuer_name, Spirit Pay affiche le nom du compte de règlement. Confirmez le paiement avec le webhook invoice.paid :

# raw_body = corps brut de la requête (bytes, non re-sérialisé)
ok = spiritpay.verify_webhook_signature(
    secret=os.environ["SPIRITPAY_WEBHOOK_SECRET"],   # whsec_…
    headers=request.headers,
    raw_body=raw_body,
)

Payer des factures fournisseur

pay = spiritpay.purchases.pay(
    return_url="https://erp.exemple.com/spiritpay/retour",  # HTTPS (http://localhost accepté avec une clé de test)
    invoices=[{
        "external_invoice_id": "497580",
        "supplier_name": "Richard SARL",
        "supplier_iban": "FR76…",
        "supplier_bic": "BNPAFRPP",
        "amount_ttc": 330,
        "invoice_ref": "TEST-2026-0928-01",
        "issuer_external_id": "12",
        "issuer_name": "Auprès Fauteuil Remplacer.",
    }],
)
# Redirigez le navigateur du payeur vers pay["bridgeRedirectURL"].

# Au retour sur return_url (?ref=<batchRef>) : état confirmé auprès de Bridge.
batch = spiritpay.purchases.get_batch(pay["batchRef"])
for invoice in batch["invoices"]:
    if invoice["status"] == "paid":
        ...  # enregistrez le règlement dans votre ERP
  • Tout ou rien : si une facture est refusée, aucune n'est payée. L'exception SpiritPayError porte code == "INVOICES_NOT_PAYABLE" et data["problems"] (une raison par facture).
  • N'enregistrez un règlement que pour status == "paid". Un lot en cours ou abandonné ne doit rien écrire.
  • Un fournisseur (même avec plusieurs factures) = un seul virement, toutes banques. Plusieurs fournisseurs = paiement groupé (une validation bancaire), seulement si la banque du payeur le permet. Spirit Pay ne bascule pas automatiquement : sinon, faites un appel par fournisseur.
  • get_batch peut prendre jusqu'à ~7 s (Spirit Pay interroge Bridge) : gardez le délai par défaut (30 s).

Banques compatibles avec le paiement groupé

banks = spiritpay.bulk_banks()["banks"]   # liste publique, aucune clé nécessaire

Client salaires (PayrollClient)

Votre logiciel envoie les salaires déjà calculés et validés ; Spirit Pay prépare le virement groupé et renvoie le lien de la banque ; l'employeur valide dans l'application de sa banque. Spirit Pay ne calcule pas la paie et ne peut rien payer sans cette validation.

Chaque employeur paie depuis sa propre banque : il crée son compte Spirit Pay, puis sa clé « salaires » (Salaires → Intégration) et la colle dans votre logiciel. Cette clé ne sert qu'à préparer des lots de salaires pour son entreprise.

import os
from spiritpay import PayrollClient, SpiritPayError

payroll = PayrollClient(payroll_key=os.environ["SPIRITPAY_PAYROLL_KEY"])   # sp_payroll_test_… / sp_payroll_live_…

# 0. Avant d'intégrer : la banque de l'employeur accepte-t-elle le paiement groupé ? (liste publique)
banks = payroll.banks("FR")   # banks["banks"] : providerId, name, maxTransactions ; banks["sandbox"] pour les tests

# 1. Envoyer le lot validé dans votre logiciel
result = payroll.batches.create(
    period="2026-10",
    external_ref="PAIE-2026-10",                      # votre référence : rejouer la requête ne crée jamais un second lot
    return_url="https://logiciel.exemple.com/paie/retour",
    provider_id=bank_provider_id,                      # banque de l'employeur (en test : banks["sandbox"]["providerId"])
    lines=[
        {"employee_ref": "E1", "display_name": "Camille Martin", "iban": "FR76…", "amount": 1500.50},
        {"employee_ref": "E2", "display_name": "Alex Durand", "iban": "FR76…", "amount": 1800},
    ],
)
# Redirigez l'employeur vers result["bridgeRedirectURL"] : il valide dans sa banque.

# 2. Au retour sur return_url (?ref=<batchRef>), ou à tout moment : état de chaque virement, confirmé auprès de Bridge
state = payroll.batches.get(result["batch"]["batchRef"])   # ou payroll.batches.get("PAIE-2026-10")
  • Tout ou rien : si une ligne est invalide, rien n'est créé (err.code == "PAYROLL_LINES_REJECTED", err.data["problems"]).
  • Un IBAN déjà utilisé ne change pas par l'API : un salarié déjà payé dont l'IBAN diffère est refusé (iban_changed) ; l'employeur confirme le changement dans son tableau de bord, par un code envoyé à son e-mail.
  • Banque et maximum : le paiement groupé est obligatoire dès 2 salariés, dans la limite maxTransactions de la banque ; sans banque compatible, le lot est refusé (aucun repli virement par virement).
  • Lot abandonné (l'employeur n'a pas validé à la banque) : relisez le lot avec payroll.batches.get(...) ; tant que le lien de la banque est valable, rejouer batches.create avec le même external_ref renvoie le même lien. Pour repartir de zéro : payroll.batches.cancel(ref) désactive le lien, puis créez un nouveau lot avec un autre external_ref. L'annulation est refusée si un virement est en cours ou effectué (PAYROLL_PAYMENT_IN_FLIGHT) ou si la banque ne répond pas (BRIDGE_UNAVAILABLE) : aucun risque de double paiement.
  • Webhooks (même URL et même secret que vos autres webhooks) : payroll.batch.paid, payroll.batch.partially_paid, payroll.batch.failed, payroll.batch.cancelled, un envoi par statut, sans IBAN. Vérification : PayrollClient.verify_webhook_signature(secret, headers, raw_body).

Erreurs

from spiritpay import SpiritPayError

try:
    spiritpay.purchases.pay(return_url, invoices)
except SpiritPayError as err:
    err.status   # code HTTP, None si réseau indisponible
    err.code     # code stable (INVOICES_NOT_PAYABLE, NETWORK, …)
    err.data     # corps JSON de la réponse

Documentation complète : spiritpay.fr/docs#paiements-fournisseurs.

Metadata

Release files for spiritpay 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spiritpay 0.2.0
File Size Uploaded Provenance Actions
spiritpay-0.2.0.tar.gz 20.7 kB Without provenance Details for spiritpay-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for spiritpay 0.2.0
File Interpreter ABI Platform Actions
spiritpay-0.2.0-py3-none-any.whl Python 3 none any Details for spiritpay-0.2.0-py3-none-any.whl

Total release size: 36.8 kB

Release files / spiritpay-0.2.0.tar.gz

Download URL spiritpay-0.2.0.tar.gz
Size 20.7 kB
Tags Source
SHA-256 checksum
How to use checksums
3e66d6001f14f5a45fb5884bdf4ad42b74e6faa27fed5f76abfd0780871f4ff5
BLAKE2b-256 checksum
How to use checksums
530c102bfdc0c3e9f715907f0916a5f7252c993cf69cc767dae15b5476638bbe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Release files / spiritpay-0.2.0-py3-none-any.whl

Download URL spiritpay-0.2.0-py3-none-any.whl
Size 16.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c889463c88be1307da253bf4d22ac00d7c3eb1dbc6d4dafc9ffcf468c7c62a85
BLAKE2b-256 checksum
How to use checksums
42a0682ff3ca705681adbbfc078eb06307f0ac75da3a0ffd6c2583106253eef1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Security for spiritpay 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page