shwary-python 1.0.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: shwary-python
|
|
3
|
+
Version: 1.0.1
|
|
4
|
+
Summary: SDK Python moderne (Async/Sync) pour l'API de paiement Shwary.
|
|
5
|
+
Author-email: Josué Luis Panzu <josuepanzu8@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Keywords: africa,fintech,kenya,mobile-money,payment,rdc,shwary,uganda
|
|
8
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
9
|
+
Classifier: Operating System :: OS Independent
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
12
|
+
Requires-Python: >=3.11
|
|
13
|
+
Requires-Dist: httpx>=0.28.1
|
|
14
|
+
Requires-Dist: phonenumbers>=9.0.22
|
|
15
|
+
Requires-Dist: pydantic>=2.12.5
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
|
|
18
|
+
# Shwary Python SDK
|
|
19
|
+
|
|
20
|
+
[](https://pypi.org/project/shwary-python/)
|
|
21
|
+
[](https://pypi.org/project/shwary-python/)
|
|
22
|
+
[](https://opensource.org/licenses/MIT)
|
|
23
|
+
|
|
24
|
+
**Shwary Python** est une bibliothèque cliente moderne, asynchrone et performante (non officielle) pour l'intégration de l'API [Shwary](https://shwary.com). Elle permet d'initier des paiements Mobile Money en **RDC**, au **Kenya** et en **Ouganda** avec une validation stricte des données avant l'envoi.
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
## Caractéristiques
|
|
29
|
+
|
|
30
|
+
* **Gestion d'erreurs native** : Pas besoin de vérifier les `status_code` manuellement. Le SDK lève des exceptions explicites (`AuthenticationError`, `ValidationError`, etc.).
|
|
31
|
+
* **Async-first** : Construit sur `httpx` pour des performances optimales (Pooling de connexions).
|
|
32
|
+
* **Dual-mode** : Support complet des modes Synchrone et Asynchrone.
|
|
33
|
+
* **Validation Robuste** : Vérification des numéros (E.164) et des montants minimums (ex: 2900 CDF pour la RDC).
|
|
34
|
+
* **Type-safe** : Basé sur Pydantic V2 pour une autocomplétion parfaite dans votre IDE.
|
|
35
|
+
* **Ultra-rapide** : Optimisé avec `uv` et `__slots__` pour minimiser l'empreinte mémoire.
|
|
36
|
+
|
|
37
|
+
## Installation
|
|
38
|
+
|
|
39
|
+
Avec `uv` (recommandé) :
|
|
40
|
+
```bash
|
|
41
|
+
uv add shwary-python
|
|
42
|
+
```
|
|
43
|
+
Ou avec `pip`
|
|
44
|
+
```bash
|
|
45
|
+
pip install shwary-python
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Utilisation Rapide
|
|
49
|
+
### Initier un paiement (Async)
|
|
50
|
+
Le SDK gère les erreurs pour vous. Enveloppez simplement votre appel dans un bloc `try...except`.
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
import asyncio
|
|
54
|
+
from shwary import ShwaryAsync
|
|
55
|
+
|
|
56
|
+
async def main():
|
|
57
|
+
async with ShwaryAsync(
|
|
58
|
+
merchant_id="votre-uuid",
|
|
59
|
+
merchant_key="votre-cle-secrete",
|
|
60
|
+
is_sandbox=True
|
|
61
|
+
) as client:
|
|
62
|
+
try:
|
|
63
|
+
# Le SDK lève une exception si l'API répond avec une erreur
|
|
64
|
+
payment = await client.initiate_payment(
|
|
65
|
+
country="DRC",
|
|
66
|
+
amount=5000,
|
|
67
|
+
phone_number="+243972345678",
|
|
68
|
+
callback_url="[https://votre-site.com/webhooks/shwary](https://votre-site.com/webhooks/shwary)"
|
|
69
|
+
)
|
|
70
|
+
print(f"ID Transaction: {payment['id']}")
|
|
71
|
+
except Exception as e:
|
|
72
|
+
print(f"Le paiement a échoué: {e}")
|
|
73
|
+
|
|
74
|
+
asyncio.run(main())
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Initier un paiement (Sync)
|
|
78
|
+
```python
|
|
79
|
+
from shwary import Shwary
|
|
80
|
+
|
|
81
|
+
with Shwary(merchant_id="...", merchant_key="...", is_sandbox=False) as client:
|
|
82
|
+
response = client.initiate_payment(
|
|
83
|
+
country="KE",
|
|
84
|
+
amount=150.5,
|
|
85
|
+
phone_number="+254700000000"
|
|
86
|
+
)
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Vérifier une transaction
|
|
90
|
+
Si vous n'avez pas reçu de webhook ou souhaitez vérifier le statut actuel :
|
|
91
|
+
|
|
92
|
+
```python
|
|
93
|
+
# Mode Synchrone
|
|
94
|
+
from shwary import Shwary
|
|
95
|
+
|
|
96
|
+
with Shwary(merchant_id="...", merchant_key="...") as client:
|
|
97
|
+
tx = client.get_transaction("votre-id-transaction")
|
|
98
|
+
print(f"Statut actuel : {tx['status']}")
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Validation par pays
|
|
102
|
+
Le SDK applique les règles métiers de Shwary localement pour économiser des appels réseau :
|
|
103
|
+
|
|
104
|
+
| Pays | Code | Devise | Montant Min. |
|
|
105
|
+
| :--- | :--- | :--- | :--- |
|
|
106
|
+
| RDC | DRC | CDF | 2900 |
|
|
107
|
+
| Kenya | KE | KES | > 0 |
|
|
108
|
+
| Ouganda | UG | UGX | > 0 |
|
|
109
|
+
|
|
110
|
+
## Gestion des Webhooks (Callbacks)
|
|
111
|
+
Lorsque le statut d'un paiement change (ex: pending -> completed), Shwary envoie un POST JSON à votre callbackUrl. Voici comment traiter la charge utile avec les modèles du SDK (exemple FastAPI) :
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
from fastapi import FastAPI, Request
|
|
115
|
+
|
|
116
|
+
app = FastAPI()
|
|
117
|
+
|
|
118
|
+
@app.post("/webhooks/shwary")
|
|
119
|
+
async def shwary_webhook(data: dict):
|
|
120
|
+
# Shwary envoie le même format que la réponse initiate_payment
|
|
121
|
+
status = data.get("status")
|
|
122
|
+
transaction_id = data.get("id")
|
|
123
|
+
|
|
124
|
+
if status == "completed":
|
|
125
|
+
# Livrez votre service ici
|
|
126
|
+
pass
|
|
127
|
+
|
|
128
|
+
return {"status": "ok"}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
## Gestion des Erreurs
|
|
132
|
+
Le SDK transforme les erreurs HTTP en exceptions Python. Vous n'avez pas besoin de vérifier manuellement les codes de statut, gérez simplement les exceptions :
|
|
133
|
+
|
|
134
|
+
| Exception | Cause |
|
|
135
|
+
| :--- | :--- |
|
|
136
|
+
| **ValidationError** | Données invalides (ex: montant < 2900 CDF en RDC, numéro mal formé). |
|
|
137
|
+
| **AuthenticationError** | Identifiants `merchant_id` ou `merchant_key` incorrects. |
|
|
138
|
+
| **ShwaryAPIError** | Erreur côté serveur Shwary ou problème réseau. |
|
|
139
|
+
| **ShwaryError** | Classe de base pour toutes les exceptions du SDK. |
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
```python
|
|
143
|
+
from shwary.exceptions import ValidationError, AuthenticationError, ShwaryAPIError
|
|
144
|
+
|
|
145
|
+
try:
|
|
146
|
+
client.initiate_payment(...)
|
|
147
|
+
except ValidationError as e:
|
|
148
|
+
# Erreur de format téléphone ou montant insuffisant
|
|
149
|
+
print(f"Données invalides : {e}")
|
|
150
|
+
except AuthenticationError:
|
|
151
|
+
# Identifiants merchant_id / merchant_key invalides
|
|
152
|
+
print("Erreur d'authentification Shwary")
|
|
153
|
+
except ShwaryAPIError as e:
|
|
154
|
+
# Autres erreurs API (404, 500, etc.)
|
|
155
|
+
print(f"Erreur API {e.status_code}: {e.message}")
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
## Développement
|
|
159
|
+
|
|
160
|
+
Pour contribuer au SDK :
|
|
161
|
+
|
|
162
|
+
1. Installez uv : curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
163
|
+
|
|
164
|
+
2. Installez les dépendances : uv sync
|
|
165
|
+
|
|
166
|
+
3. Lancez les tests : uv run pytest
|
|
167
|
+
|
|
168
|
+
### Licence
|
|
169
|
+
|
|
170
|
+
Distribué sous la licence MIT. Voir [](https://opensource.org/licenses/MIT) pour plus d'informations.
|