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
SpiritPayErrorportecode == "INVOICES_NOT_PAYABLE"etdata["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_batchpeut 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
maxTransactionsde 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, rejouerbatches.createavec le mêmeexternal_refrenvoie 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 autreexternal_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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.