wourapay 0.1.0__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.
- wourapay/__init__.py +51 -0
- wourapay/client.py +166 -0
- wourapay/exceptions.py +57 -0
- wourapay/models.py +47 -0
- wourapay/webhooks.py +119 -0
- wourapay-0.1.0.dist-info/METADATA +189 -0
- wourapay-0.1.0.dist-info/RECORD +8 -0
- wourapay-0.1.0.dist-info/WHEEL +4 -0
wourapay/__init__.py
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"""
|
|
2
|
+
SDK Python de Wourapay.
|
|
3
|
+
|
|
4
|
+
Deux usages, et rien d'autre :
|
|
5
|
+
|
|
6
|
+
1. **Vérifier un paiement côté serveur** avant de livrer une commande.
|
|
7
|
+
2. **Vérifier la signature d'un callback** avant de traiter son contenu.
|
|
8
|
+
|
|
9
|
+
.. code-block:: python
|
|
10
|
+
|
|
11
|
+
from wourapay import Wourapay, verify_webhook_signature
|
|
12
|
+
|
|
13
|
+
client = Wourapay(api_key="kpy_…")
|
|
14
|
+
if client.verify(reference="ORDER-1").verified:
|
|
15
|
+
deliver_order()
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from .client import AsyncWourapay, DEFAULT_BASE_URL, Wourapay
|
|
19
|
+
from .exceptions import (
|
|
20
|
+
APIError,
|
|
21
|
+
AuthenticationError,
|
|
22
|
+
InvalidSignature,
|
|
23
|
+
NetworkError,
|
|
24
|
+
WourapayError,
|
|
25
|
+
)
|
|
26
|
+
from .models import VerificationResult
|
|
27
|
+
from .webhooks import (
|
|
28
|
+
DEFAULT_TOLERANCE_SECONDS,
|
|
29
|
+
SIGNATURE_HEADER,
|
|
30
|
+
parse_signature_header,
|
|
31
|
+
verify_webhook_signature,
|
|
32
|
+
)
|
|
33
|
+
|
|
34
|
+
__version__ = "0.1.0"
|
|
35
|
+
|
|
36
|
+
__all__ = [
|
|
37
|
+
"Wourapay",
|
|
38
|
+
"AsyncWourapay",
|
|
39
|
+
"DEFAULT_BASE_URL",
|
|
40
|
+
"VerificationResult",
|
|
41
|
+
"verify_webhook_signature",
|
|
42
|
+
"parse_signature_header",
|
|
43
|
+
"SIGNATURE_HEADER",
|
|
44
|
+
"DEFAULT_TOLERANCE_SECONDS",
|
|
45
|
+
"WourapayError",
|
|
46
|
+
"AuthenticationError",
|
|
47
|
+
"APIError",
|
|
48
|
+
"NetworkError",
|
|
49
|
+
"InvalidSignature",
|
|
50
|
+
"__version__",
|
|
51
|
+
]
|
wourapay/client.py
ADDED
|
@@ -0,0 +1,166 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Client HTTP du SDK Wourapay.
|
|
3
|
+
|
|
4
|
+
Périmètre volontairement étroit : ce SDK sert à **vérifier côté serveur** qu'un
|
|
5
|
+
paiement a bien eu lieu. Il n'expose pas l'API marchande complète — encaisser,
|
|
6
|
+
créer des liens, gérer des sous-comptes se fait directement en HTTP, et un
|
|
7
|
+
wrapper y ajouterait une surface à maintenir sans rien simplifier.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import os
|
|
13
|
+
from types import TracebackType
|
|
14
|
+
from typing import Any, Mapping
|
|
15
|
+
|
|
16
|
+
import httpx
|
|
17
|
+
|
|
18
|
+
from .exceptions import APIError, AuthenticationError, NetworkError
|
|
19
|
+
from .models import VerificationResult
|
|
20
|
+
|
|
21
|
+
__all__ = ["Wourapay", "AsyncWourapay", "DEFAULT_BASE_URL"]
|
|
22
|
+
|
|
23
|
+
DEFAULT_BASE_URL = "https://api.wourapay.com"
|
|
24
|
+
_USER_AGENT = "wourapay-python/0.1.0"
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def _resolve_api_key(api_key: str | None) -> str:
|
|
28
|
+
key = api_key or os.environ.get("WOURAPAY_API_KEY")
|
|
29
|
+
if not key:
|
|
30
|
+
raise AuthenticationError(
|
|
31
|
+
"Clé API manquante. Passez `api_key=` ou définissez WOURAPAY_API_KEY."
|
|
32
|
+
)
|
|
33
|
+
return key
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _verify_params(transaction_id: str | None, reference: str | None) -> dict[str, str]:
|
|
37
|
+
if not transaction_id and not reference:
|
|
38
|
+
raise ValueError("Fournissez `transaction_id` ou `reference`.")
|
|
39
|
+
return {"transaction_id": transaction_id} if transaction_id else {"reference": reference} # type: ignore[dict-item]
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _auth_headers(api_key: str) -> dict[str, str]:
|
|
43
|
+
return {"X-Api-Key": api_key, "User-Agent": _USER_AGENT}
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
def _handle(response: httpx.Response) -> VerificationResult:
|
|
47
|
+
if response.status_code in (401, 403):
|
|
48
|
+
raise AuthenticationError("Clé API invalide ou non autorisée.")
|
|
49
|
+
if response.status_code >= 400:
|
|
50
|
+
payload: Any
|
|
51
|
+
try:
|
|
52
|
+
payload = response.json()
|
|
53
|
+
except ValueError:
|
|
54
|
+
payload = response.text
|
|
55
|
+
detail = payload.get("detail") if isinstance(payload, Mapping) else None
|
|
56
|
+
raise APIError(
|
|
57
|
+
str(detail or f"Erreur API (HTTP {response.status_code})"),
|
|
58
|
+
status_code=response.status_code,
|
|
59
|
+
payload=payload,
|
|
60
|
+
)
|
|
61
|
+
return VerificationResult.from_payload(response.json())
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class Wourapay:
|
|
65
|
+
"""
|
|
66
|
+
Client synchrone.
|
|
67
|
+
|
|
68
|
+
.. code-block:: python
|
|
69
|
+
|
|
70
|
+
from wourapay import Wourapay
|
|
71
|
+
|
|
72
|
+
client = Wourapay(api_key="kpy_…")
|
|
73
|
+
result = client.verify(reference="ORDER-2026-001")
|
|
74
|
+
if result.verified:
|
|
75
|
+
deliver_order()
|
|
76
|
+
|
|
77
|
+
⚠️ **Ne livrez jamais sur la seule foi du front.** Le navigateur peut affirmer
|
|
78
|
+
n'importe quoi ; seul cet appel serveur fait autorité. Si la transaction n'est
|
|
79
|
+
pas encore terminale, l'API la revérifie en direct auprès de l'agrégateur.
|
|
80
|
+
"""
|
|
81
|
+
|
|
82
|
+
def __init__(
|
|
83
|
+
self,
|
|
84
|
+
api_key: str | None = None,
|
|
85
|
+
*,
|
|
86
|
+
base_url: str = DEFAULT_BASE_URL,
|
|
87
|
+
timeout: float = 30.0,
|
|
88
|
+
client: httpx.Client | None = None,
|
|
89
|
+
) -> None:
|
|
90
|
+
self._api_key = _resolve_api_key(api_key)
|
|
91
|
+
self._base_url = base_url.rstrip("/")
|
|
92
|
+
self._owns_client = client is None
|
|
93
|
+
self._client = client or httpx.Client(base_url=self._base_url, timeout=timeout)
|
|
94
|
+
# Les en-têtes sont posés dans TOUS les cas : sur un client fourni par
|
|
95
|
+
# l'appelant, les fixer uniquement à la construction laisserait partir des
|
|
96
|
+
# requêtes non authentifiées.
|
|
97
|
+
self._client.headers.update(_auth_headers(self._api_key))
|
|
98
|
+
|
|
99
|
+
def verify(
|
|
100
|
+
self, *, transaction_id: str | None = None, reference: str | None = None
|
|
101
|
+
) -> VerificationResult:
|
|
102
|
+
"""Vérifie un paiement par son identifiant Wourapay ou par VOTRE référence."""
|
|
103
|
+
params = _verify_params(transaction_id, reference)
|
|
104
|
+
try:
|
|
105
|
+
response = self._client.get("/checkout/verify", params=params)
|
|
106
|
+
except httpx.HTTPError as exc:
|
|
107
|
+
# Sans cette enveloppe, une coupure réseau remonterait en httpx.*, hors
|
|
108
|
+
# de la hiérarchie du SDK : un `except WourapayError` la manquerait.
|
|
109
|
+
raise NetworkError(f"API injoignable : {exc}") from exc
|
|
110
|
+
return _handle(response)
|
|
111
|
+
|
|
112
|
+
def close(self) -> None:
|
|
113
|
+
if self._owns_client:
|
|
114
|
+
self._client.close()
|
|
115
|
+
|
|
116
|
+
def __enter__(self) -> "Wourapay":
|
|
117
|
+
return self
|
|
118
|
+
|
|
119
|
+
def __exit__(self, *exc: object) -> None:
|
|
120
|
+
self.close()
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
class AsyncWourapay:
|
|
124
|
+
"""Client asynchrone — même contrat que :class:`Wourapay`."""
|
|
125
|
+
|
|
126
|
+
def __init__(
|
|
127
|
+
self,
|
|
128
|
+
api_key: str | None = None,
|
|
129
|
+
*,
|
|
130
|
+
base_url: str = DEFAULT_BASE_URL,
|
|
131
|
+
timeout: float = 30.0,
|
|
132
|
+
client: httpx.AsyncClient | None = None,
|
|
133
|
+
) -> None:
|
|
134
|
+
self._api_key = _resolve_api_key(api_key)
|
|
135
|
+
self._base_url = base_url.rstrip("/")
|
|
136
|
+
self._owns_client = client is None
|
|
137
|
+
self._client = client or httpx.AsyncClient(base_url=self._base_url, timeout=timeout)
|
|
138
|
+
# Les en-têtes sont posés dans TOUS les cas : sur un client fourni par
|
|
139
|
+
# l'appelant, les fixer uniquement à la construction laisserait partir des
|
|
140
|
+
# requêtes non authentifiées.
|
|
141
|
+
self._client.headers.update(_auth_headers(self._api_key))
|
|
142
|
+
|
|
143
|
+
async def verify(
|
|
144
|
+
self, *, transaction_id: str | None = None, reference: str | None = None
|
|
145
|
+
) -> VerificationResult:
|
|
146
|
+
params = _verify_params(transaction_id, reference)
|
|
147
|
+
try:
|
|
148
|
+
response = await self._client.get("/checkout/verify", params=params)
|
|
149
|
+
except httpx.HTTPError as exc:
|
|
150
|
+
raise NetworkError(f"API injoignable : {exc}") from exc
|
|
151
|
+
return _handle(response)
|
|
152
|
+
|
|
153
|
+
async def aclose(self) -> None:
|
|
154
|
+
if self._owns_client:
|
|
155
|
+
await self._client.aclose()
|
|
156
|
+
|
|
157
|
+
async def __aenter__(self) -> "AsyncWourapay":
|
|
158
|
+
return self
|
|
159
|
+
|
|
160
|
+
async def __aexit__(
|
|
161
|
+
self,
|
|
162
|
+
exc_type: type[BaseException] | None,
|
|
163
|
+
exc: BaseException | None,
|
|
164
|
+
tb: TracebackType | None,
|
|
165
|
+
) -> None:
|
|
166
|
+
await self.aclose()
|
wourapay/exceptions.py
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Hiérarchie d'erreurs du SDK.
|
|
3
|
+
|
|
4
|
+
**Une seule racine.** Un intégrateur qui écrit ``except WourapayError`` doit
|
|
5
|
+
attraper TOUT ce que le SDK peut lever — signature invalide et panne réseau
|
|
6
|
+
comprises. Une exception qui échappe à cette base est un piège : elle remonte
|
|
7
|
+
jusqu'au handler générique du framework, où elle devient une 500 muette.
|
|
8
|
+
|
|
9
|
+
Ce module ne dépend que de la bibliothèque standard : il est importable depuis
|
|
10
|
+
`webhooks`, qui doit rester utilisable sans `httpx`.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
from __future__ import annotations
|
|
14
|
+
|
|
15
|
+
__all__ = [
|
|
16
|
+
"WourapayError",
|
|
17
|
+
"AuthenticationError",
|
|
18
|
+
"APIError",
|
|
19
|
+
"NetworkError",
|
|
20
|
+
"InvalidSignature",
|
|
21
|
+
]
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class WourapayError(Exception):
|
|
25
|
+
"""Base de toutes les erreurs du SDK."""
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class AuthenticationError(WourapayError):
|
|
29
|
+
"""Clé API absente, invalide ou révoquée."""
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class NetworkError(WourapayError):
|
|
33
|
+
"""
|
|
34
|
+
L'API n'a pas pu être jointe (DNS, TLS, timeout, coupure).
|
|
35
|
+
|
|
36
|
+
Distincte d'`APIError` : ici on ne sait PAS si la requête a été traitée.
|
|
37
|
+
Sur une vérification de paiement, cela veut dire « réessayez », pas
|
|
38
|
+
« le paiement a échoué ».
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class APIError(WourapayError):
|
|
43
|
+
"""
|
|
44
|
+
L'API a répondu une erreur.
|
|
45
|
+
|
|
46
|
+
`status_code` et `payload` sont conservés : sur un paiement, savoir *pourquoi*
|
|
47
|
+
l'appel a échoué détermine s'il faut réessayer ou alerter.
|
|
48
|
+
"""
|
|
49
|
+
|
|
50
|
+
def __init__(self, message: str, *, status_code: int, payload: object = None):
|
|
51
|
+
super().__init__(message)
|
|
52
|
+
self.status_code = status_code
|
|
53
|
+
self.payload = payload
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
class InvalidSignature(WourapayError):
|
|
57
|
+
"""Signature absente, malformée, expirée ou ne correspondant pas au corps."""
|
wourapay/models.py
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
"""Objets retournés par le SDK."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import dataclass
|
|
6
|
+
from typing import Any, Mapping
|
|
7
|
+
|
|
8
|
+
__all__ = ["VerificationResult"]
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
@dataclass(frozen=True)
|
|
12
|
+
class VerificationResult:
|
|
13
|
+
"""
|
|
14
|
+
Résultat d'une vérification serveur de paiement.
|
|
15
|
+
|
|
16
|
+
`verified` est la SEULE valeur sur laquelle livrer : elle vaut ``True``
|
|
17
|
+
uniquement si la transaction vous appartient ET qu'elle est réellement
|
|
18
|
+
`successful`. Un `status` renseigné ne suffit pas.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
verified: bool
|
|
22
|
+
status: str
|
|
23
|
+
transaction_id: str | None = None
|
|
24
|
+
display_id: str | None = None
|
|
25
|
+
reference: str | None = None
|
|
26
|
+
amount: float | None = None
|
|
27
|
+
currency: str | None = None
|
|
28
|
+
network_code: str | None = None
|
|
29
|
+
client_id: str | None = None
|
|
30
|
+
paid_at: str | None = None
|
|
31
|
+
raw: Mapping[str, Any] | None = None
|
|
32
|
+
|
|
33
|
+
@classmethod
|
|
34
|
+
def from_payload(cls, payload: Mapping[str, Any]) -> "VerificationResult":
|
|
35
|
+
return cls(
|
|
36
|
+
verified=bool(payload.get("verified")),
|
|
37
|
+
status=str(payload.get("status", "unknown")),
|
|
38
|
+
transaction_id=payload.get("transaction_id"),
|
|
39
|
+
display_id=payload.get("display_id"),
|
|
40
|
+
reference=payload.get("reference"),
|
|
41
|
+
amount=payload.get("amount"),
|
|
42
|
+
currency=payload.get("currency"),
|
|
43
|
+
network_code=payload.get("network_code"),
|
|
44
|
+
client_id=payload.get("client_id"),
|
|
45
|
+
paid_at=payload.get("paid_at"),
|
|
46
|
+
raw=payload,
|
|
47
|
+
)
|
wourapay/webhooks.py
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Vérification des callbacks Wourapay.
|
|
3
|
+
|
|
4
|
+
**Ce module ne dépend que de la bibliothèque standard.** Il reste donc utilisable
|
|
5
|
+
dans un projet qui n'installe pas `httpx`, et dans une fonction serverless minimale.
|
|
6
|
+
|
|
7
|
+
Format de l'en-tête reçu :
|
|
8
|
+
|
|
9
|
+
X-Wourapay-Signature: t=1753632000,v1=5257a869e7ec…
|
|
10
|
+
|
|
11
|
+
La charge signée est ``f"{timestamp}.{corps_brut}"`` en HMAC-SHA256. L'horodatage
|
|
12
|
+
étant DANS la signature, une capture réseau ne peut pas être rejouée au-delà de la
|
|
13
|
+
fenêtre de tolérance.
|
|
14
|
+
|
|
15
|
+
Deux pièges à éviter côté intégrateur :
|
|
16
|
+
|
|
17
|
+
1. **Signer le corps brut.** Passez les octets reçus tels quels, jamais un JSON
|
|
18
|
+
re-sérialisé : un espace ou un ordre de clés différent invalide la signature.
|
|
19
|
+
2. **Vérifier avant de traiter.** Un callback non vérifié n'est qu'une assertion
|
|
20
|
+
d'un inconnu sur l'état de votre argent.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
from __future__ import annotations
|
|
24
|
+
|
|
25
|
+
import hashlib
|
|
26
|
+
import hmac
|
|
27
|
+
import time
|
|
28
|
+
from typing import List, Tuple
|
|
29
|
+
|
|
30
|
+
from .exceptions import InvalidSignature
|
|
31
|
+
|
|
32
|
+
__all__ = [
|
|
33
|
+
"SIGNATURE_HEADER",
|
|
34
|
+
"DEFAULT_TOLERANCE_SECONDS",
|
|
35
|
+
"InvalidSignature",
|
|
36
|
+
"parse_signature_header",
|
|
37
|
+
"verify_webhook_signature",
|
|
38
|
+
]
|
|
39
|
+
|
|
40
|
+
SIGNATURE_HEADER = "X-Wourapay-Signature"
|
|
41
|
+
SCHEME = "v1"
|
|
42
|
+
|
|
43
|
+
#: Fenêtre d'acceptation d'un horodatage. 5 minutes absorbent une dérive d'horloge
|
|
44
|
+
#: raisonnable sans ouvrir de véritable fenêtre de rejeu.
|
|
45
|
+
DEFAULT_TOLERANCE_SECONDS = 300
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def parse_signature_header(header: str) -> Tuple[int | None, List[str]]:
|
|
49
|
+
"""
|
|
50
|
+
Extrait ``(timestamp, signatures)`` d'un en-tête.
|
|
51
|
+
|
|
52
|
+
Les champs inconnus sont ignorés : un futur ``v2=`` ne doit pas casser un
|
|
53
|
+
vérificateur ``v1``.
|
|
54
|
+
"""
|
|
55
|
+
timestamp: int | None = None
|
|
56
|
+
signatures: List[str] = []
|
|
57
|
+
|
|
58
|
+
for item in (header or "").split(","):
|
|
59
|
+
key, _, value = item.strip().partition("=")
|
|
60
|
+
if key == "t":
|
|
61
|
+
try:
|
|
62
|
+
timestamp = int(value)
|
|
63
|
+
except ValueError:
|
|
64
|
+
return None, []
|
|
65
|
+
elif key == SCHEME:
|
|
66
|
+
signatures.append(value)
|
|
67
|
+
|
|
68
|
+
return timestamp, signatures
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def _compute(body: bytes, secret: str, timestamp: int) -> str:
|
|
72
|
+
signed_payload = f"{timestamp}.".encode("utf-8") + body
|
|
73
|
+
return hmac.new(secret.encode("utf-8"), signed_payload, hashlib.sha256).hexdigest()
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def verify_webhook_signature(
|
|
77
|
+
payload: bytes | str,
|
|
78
|
+
header: str,
|
|
79
|
+
secret: str,
|
|
80
|
+
tolerance: int = DEFAULT_TOLERANCE_SECONDS,
|
|
81
|
+
*,
|
|
82
|
+
raise_on_error: bool = False,
|
|
83
|
+
) -> bool:
|
|
84
|
+
"""
|
|
85
|
+
Vérifie un callback reçu.
|
|
86
|
+
|
|
87
|
+
:param payload: Corps **brut** de la requête. Une ``str`` est encodée en UTF-8 ;
|
|
88
|
+
préférez les octets, seuls fidèles à ce qui a été signé.
|
|
89
|
+
:param header: Valeur de l'en-tête ``X-Wourapay-Signature``.
|
|
90
|
+
:param secret: Votre secret de webhook (``whsec_…``), lisible dans votre espace.
|
|
91
|
+
:param tolerance: Écart d'horodatage toléré, en secondes. ``0`` désactive le
|
|
92
|
+
contrôle — à réserver aux tests : cela rouvre la fenêtre de rejeu.
|
|
93
|
+
:param raise_on_error: ``True`` lève :class:`InvalidSignature` au lieu de
|
|
94
|
+
retourner ``False``, pratique pour laisser remonter une 400.
|
|
95
|
+
|
|
96
|
+
Plusieurs signatures peuvent cohabiter dans l'en-tête pendant une rotation de
|
|
97
|
+
secret : il suffit qu'une seule corresponde.
|
|
98
|
+
"""
|
|
99
|
+
body = payload.encode("utf-8") if isinstance(payload, str) else payload
|
|
100
|
+
|
|
101
|
+
def fail(reason: str) -> bool:
|
|
102
|
+
if raise_on_error:
|
|
103
|
+
raise InvalidSignature(reason)
|
|
104
|
+
return False
|
|
105
|
+
|
|
106
|
+
timestamp, signatures = parse_signature_header(header)
|
|
107
|
+
if timestamp is None or not signatures:
|
|
108
|
+
return fail("En-tête de signature absent ou malformé.")
|
|
109
|
+
|
|
110
|
+
if tolerance and abs(int(time.time()) - timestamp) > tolerance:
|
|
111
|
+
return fail("Horodatage hors de la fenêtre de tolérance (rejeu probable).")
|
|
112
|
+
|
|
113
|
+
expected = _compute(body, secret, timestamp)
|
|
114
|
+
# compare_digest sur chaque candidat : comparaison à temps constant, pas de
|
|
115
|
+
# fuite d'information par timing.
|
|
116
|
+
if any(hmac.compare_digest(expected, candidate) for candidate in signatures):
|
|
117
|
+
return True
|
|
118
|
+
|
|
119
|
+
return fail("La signature ne correspond pas au corps reçu.")
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: wourapay
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: SDK Python officiel de Wourapay — vérification serveur des paiements et des webhooks
|
|
5
|
+
Project-URL: Homepage, https://wourapay.com
|
|
6
|
+
Project-URL: Documentation, https://api.wourapay.com/docs
|
|
7
|
+
Project-URL: Source, https://github.com/woura-it/wourapay-python
|
|
8
|
+
Author: Wourapay
|
|
9
|
+
License: MIT
|
|
10
|
+
Keywords: afrique,mobile money,paiement,webhook,wourapay
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Topic :: Office/Business :: Financial
|
|
16
|
+
Requires-Python: >=3.9
|
|
17
|
+
Requires-Dist: httpx>=0.24
|
|
18
|
+
Provides-Extra: dev
|
|
19
|
+
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
|
|
20
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
21
|
+
Description-Content-Type: text/markdown
|
|
22
|
+
|
|
23
|
+
# wourapay — SDK Python
|
|
24
|
+
|
|
25
|
+
SDK officiel de [Wourapay](https://wourapay.com) pour les **backends**.
|
|
26
|
+
|
|
27
|
+
Deux usages, et rien d'autre :
|
|
28
|
+
|
|
29
|
+
1. **Vérifier un paiement** avant de livrer une commande.
|
|
30
|
+
2. **Vérifier la signature d'un callback** avant de traiter son contenu.
|
|
31
|
+
|
|
32
|
+
Encaisser, créer des liens de paiement ou gérer des sous-comptes se fait
|
|
33
|
+
directement en HTTP — un wrapper y ajouterait une surface à maintenir sans rien
|
|
34
|
+
simplifier. Voir [la documentation API](https://api.wourapay.com/docs).
|
|
35
|
+
|
|
36
|
+
```bash
|
|
37
|
+
pip install wourapay
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## 1. Vérifier un paiement
|
|
43
|
+
|
|
44
|
+
Après que votre front a affiché « paiement réussi », **vérifiez côté serveur**.
|
|
45
|
+
Le navigateur peut affirmer n'importe quoi ; seul cet appel fait autorité.
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
from wourapay import Wourapay
|
|
49
|
+
|
|
50
|
+
client = Wourapay(api_key="kpy_…") # ou variable WOURAPAY_API_KEY
|
|
51
|
+
|
|
52
|
+
result = client.verify(reference="ORDER-2026-001")
|
|
53
|
+
if result.verified:
|
|
54
|
+
deliver_order()
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`verified` est la **seule** valeur sur laquelle livrer : elle vaut `True`
|
|
58
|
+
uniquement si la transaction vous appartient **et** qu'elle est réellement
|
|
59
|
+
`successful`. Un `status` renseigné ne suffit pas.
|
|
60
|
+
|
|
61
|
+
Si la transaction n'est pas encore terminale, l'API la revérifie en direct auprès
|
|
62
|
+
de l'agrégateur avant de répondre.
|
|
63
|
+
|
|
64
|
+
<details>
|
|
65
|
+
<summary>Recherche par identifiant Wourapay</summary>
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
result = client.verify(transaction_id="e5f2…")
|
|
69
|
+
```
|
|
70
|
+
</details>
|
|
71
|
+
|
|
72
|
+
<details>
|
|
73
|
+
<summary>Version asynchrone</summary>
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
from wourapay import AsyncWourapay
|
|
77
|
+
|
|
78
|
+
async with AsyncWourapay(api_key="kpy_…") as client:
|
|
79
|
+
result = await client.verify(reference="ORDER-1")
|
|
80
|
+
```
|
|
81
|
+
</details>
|
|
82
|
+
|
|
83
|
+
### Le résultat
|
|
84
|
+
|
|
85
|
+
| Champ | Description |
|
|
86
|
+
|---|---|
|
|
87
|
+
| `verified` | `True` ⇔ transaction à vous **et** `successful` |
|
|
88
|
+
| `status` | `pending` · `processing` · `successful` · `failed` · `expired` · `not_found` |
|
|
89
|
+
| `transaction_id`, `display_id`, `reference` | Identifiants |
|
|
90
|
+
| `amount`, `currency`, `network_code` | Montant et réseau |
|
|
91
|
+
| `client_id` | Sous-compte crédité, le cas échéant |
|
|
92
|
+
| `paid_at` | Horodatage du succès |
|
|
93
|
+
| `raw` | Réponse brute, pour les champs ajoutés après cette version |
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## 2. Vérifier un callback
|
|
98
|
+
|
|
99
|
+
Wourapay signe chaque callback. **Vérifiez la signature avant de traiter le
|
|
100
|
+
contenu** : un callback non vérifié n'est qu'une assertion d'un inconnu sur
|
|
101
|
+
l'état de votre argent.
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
from wourapay import verify_webhook_signature
|
|
105
|
+
|
|
106
|
+
@app.post("/webhooks/wourapay")
|
|
107
|
+
async def handle(request):
|
|
108
|
+
body = await request.body() # OCTETS BRUTS
|
|
109
|
+
header = request.headers["X-Wourapay-Signature"]
|
|
110
|
+
|
|
111
|
+
if not verify_webhook_signature(body, header, secret=WEBHOOK_SECRET):
|
|
112
|
+
return Response(status_code=400)
|
|
113
|
+
|
|
114
|
+
event = json.loads(body)
|
|
115
|
+
...
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Votre secret (`whsec_…`) est lisible dans votre espace marchand, section
|
|
119
|
+
**Webhooks**.
|
|
120
|
+
|
|
121
|
+
### Deux pièges à éviter
|
|
122
|
+
|
|
123
|
+
**Passez le corps brut.** Jamais un JSON re-sérialisé : un espace ou un ordre de
|
|
124
|
+
clés différent invalide la signature.
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
verify_webhook_signature(await request.body(), header, secret) # ✅
|
|
128
|
+
verify_webhook_signature(json.dumps(request.json()), header, secret) # ❌
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
**Ne désactivez pas la tolérance en production.** L'horodatage fait partie de la
|
|
132
|
+
signature : c'est ce qui empêche le rejeu d'une capture réseau. `tolerance=0`
|
|
133
|
+
est réservé aux tests.
|
|
134
|
+
|
|
135
|
+
### Rotation de secret
|
|
136
|
+
|
|
137
|
+
Quand vous régénérez votre secret, Wourapay signe pendant **24 h** avec l'ancien
|
|
138
|
+
**et** le nouveau. Déployez votre nouveau secret quand vous voulez dans cette
|
|
139
|
+
fenêtre : aucun callback n'est perdu.
|
|
140
|
+
|
|
141
|
+
### Laisser remonter l'erreur
|
|
142
|
+
|
|
143
|
+
```python
|
|
144
|
+
from wourapay import verify_webhook_signature, InvalidSignature
|
|
145
|
+
|
|
146
|
+
try:
|
|
147
|
+
verify_webhook_signature(body, header, secret, raise_on_error=True)
|
|
148
|
+
except InvalidSignature as exc:
|
|
149
|
+
return Response(str(exc), status_code=400)
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
Le module de signature ne dépend que de la bibliothèque standard : il reste
|
|
153
|
+
utilisable dans une fonction serverless qui n'installe rien d'autre.
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Erreurs
|
|
158
|
+
|
|
159
|
+
Toutes dérivent de `WourapayError` : un seul `except` suffit à ne rien laisser
|
|
160
|
+
passer.
|
|
161
|
+
|
|
162
|
+
| Exception | Quand |
|
|
163
|
+
|---|---|
|
|
164
|
+
| `AuthenticationError` | Clé absente, invalide ou révoquée |
|
|
165
|
+
| `APIError` | L'API a répondu une erreur — porte `status_code` et `payload` |
|
|
166
|
+
| `NetworkError` | API injoignable : DNS, TLS, timeout, coupure |
|
|
167
|
+
| `InvalidSignature` | Signature absente, expirée ou ne correspondant pas |
|
|
168
|
+
| `WourapayError` | Base commune |
|
|
169
|
+
|
|
170
|
+
`NetworkError` mérite une attention particulière : contrairement à `APIError`,
|
|
171
|
+
elle veut dire **« on ne sait pas »**, pas « le paiement a échoué ». Sur une
|
|
172
|
+
vérification, c'est un signal de réessai, jamais de refus de commande.
|
|
173
|
+
|
|
174
|
+
---
|
|
175
|
+
|
|
176
|
+
## Développement
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
pip install -e ".[dev]"
|
|
180
|
+
pytest
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
Les vecteurs de `tests/test_webhooks.py` font foi : ils doivent rester alignés
|
|
184
|
+
sur l'implémentation de référence côté API. Un test qui diverge signifie qu'un
|
|
185
|
+
marchand rejettera des callbacks légitimes — ou pire, en acceptera de falsifiés.
|
|
186
|
+
|
|
187
|
+
## Licence
|
|
188
|
+
|
|
189
|
+
MIT
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
wourapay/__init__.py,sha256=C3UDcLf9ZgEal79kOg2Noso5E4XKcUBMqD_2Gwktfeo,1152
|
|
2
|
+
wourapay/client.py,sha256=uJKAlkG-vkxwcnWMBArXrNpn_eRN0xnUgeAqw8FmHKY,5871
|
|
3
|
+
wourapay/exceptions.py,sha256=hyL_D_QBD-tdkSV8cGkd6YAHJ-maNkaoky-bAbR979I,1679
|
|
4
|
+
wourapay/models.py,sha256=KNJv2mOw5dsSWLGWUOCc3vMuk48Dftp3ZU6UlMmWbho,1503
|
|
5
|
+
wourapay/webhooks.py,sha256=jiuigXztjLAy1gatCxxDjnI0BE2gqS9VPwo6C65hscg,4118
|
|
6
|
+
wourapay-0.1.0.dist-info/METADATA,sha256=5sE0eZ_D-m_XUY1RL50YX1OUTGQ7xy6dXigiZtZpDho,5874
|
|
7
|
+
wourapay-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
|
|
8
|
+
wourapay-0.1.0.dist-info/RECORD,,
|