yoonpay 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.
- yoonpay/__init__.py +38 -0
- yoonpay/_version.py +2 -0
- yoonpay/client.py +210 -0
- yoonpay/django.py +73 -0
- yoonpay/errors.py +68 -0
- yoonpay/fastapi.py +67 -0
- yoonpay/flask.py +67 -0
- yoonpay/generated/__init__.py +134 -0
- yoonpay/generated/api/__init__.py +11 -0
- yoonpay/generated/api/events_api.py +937 -0
- yoonpay/generated/api/exports_api.py +1219 -0
- yoonpay/generated/api/ledger_api.py +640 -0
- yoonpay/generated/api/meta_api.py +530 -0
- yoonpay/generated/api/payments_api.py +1296 -0
- yoonpay/generated/api/payouts_api.py +1210 -0
- yoonpay/generated/api/refunds_api.py +1459 -0
- yoonpay/generated/api_client.py +804 -0
- yoonpay/generated/api_response.py +21 -0
- yoonpay/generated/configuration.py +589 -0
- yoonpay/generated/exceptions.py +216 -0
- yoonpay/generated/models/__init__.py +53 -0
- yoonpay/generated/models/admin_replay_dead_letter202_response.py +96 -0
- yoonpay/generated/models/admin_resolve_payout_request.py +97 -0
- yoonpay/generated/models/create_payment_request.py +122 -0
- yoonpay/generated/models/create_payment_request_customer.py +90 -0
- yoonpay/generated/models/create_payout_request.py +118 -0
- yoonpay/generated/models/create_payout_request_recipient.py +90 -0
- yoonpay/generated/models/create_refund_request.py +90 -0
- yoonpay/generated/models/delivery_status.py +48 -0
- yoonpay/generated/models/event.py +125 -0
- yoonpay/generated/models/event_delivery.py +119 -0
- yoonpay/generated/models/event_page.py +104 -0
- yoonpay/generated/models/event_payload.py +108 -0
- yoonpay/generated/models/event_payload_data.py +91 -0
- yoonpay/generated/models/event_payload_data_object.py +151 -0
- yoonpay/generated/models/event_type.py +52 -0
- yoonpay/generated/models/failure.py +89 -0
- yoonpay/generated/models/get_about200_response.py +93 -0
- yoonpay/generated/models/get_balances200_response.py +106 -0
- yoonpay/generated/models/get_balances200_response_data_inner.py +93 -0
- yoonpay/generated/models/ledger_entry.py +100 -0
- yoonpay/generated/models/ledger_entry_page.py +104 -0
- yoonpay/generated/models/list_providers200_response_inner.py +101 -0
- yoonpay/generated/models/list_providers200_response_inner_capabilities_inner.py +100 -0
- yoonpay/generated/models/payment.py +175 -0
- yoonpay/generated/models/payment_customer.py +92 -0
- yoonpay/generated/models/payment_page.py +104 -0
- yoonpay/generated/models/payment_status.py +49 -0
- yoonpay/generated/models/payout.py +149 -0
- yoonpay/generated/models/payout_page.py +104 -0
- yoonpay/generated/models/payout_recipient.py +92 -0
- yoonpay/generated/models/payout_status.py +49 -0
- yoonpay/generated/models/problem.py +97 -0
- yoonpay/generated/models/receive_provider_callback200_response.py +87 -0
- yoonpay/generated/models/refund.py +132 -0
- yoonpay/generated/models/refund_page.py +104 -0
- yoonpay/generated/models/refund_status.py +49 -0
- yoonpay/generated/models/status_event.py +129 -0
- yoonpay/generated/py.typed +0 -0
- yoonpay/generated/rest.py +258 -0
- yoonpay/py.typed +0 -0
- yoonpay/webhook.py +181 -0
- yoonpay-0.1.0.dist-info/METADATA +197 -0
- yoonpay-0.1.0.dist-info/RECORD +66 -0
- yoonpay-0.1.0.dist-info/WHEEL +4 -0
- yoonpay-0.1.0.dist-info/licenses/LICENSE +202 -0
yoonpay/__init__.py
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
"""Python client for Yoon, the self-hosted payment gateway for African payment providers.
|
|
2
|
+
|
|
3
|
+
The generated code lives in ``yoonpay.generated`` (``clients/python/generated`` in the
|
|
4
|
+
repository, merged into this package when it is built); the hand-written layer is here.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
# The generated sub-package sits in a separate source tree in the repository: let both trees
|
|
8
|
+
# contribute to the `yoonpay` package during development (a built wheel has one tree).
|
|
9
|
+
from pkgutil import extend_path
|
|
10
|
+
|
|
11
|
+
__path__ = extend_path(__path__, __name__)
|
|
12
|
+
|
|
13
|
+
from yoonpay._version import USER_AGENT, __version__ # noqa: E402
|
|
14
|
+
from yoonpay.client import Yoon # noqa: E402
|
|
15
|
+
from yoonpay.errors import YoonException # noqa: E402
|
|
16
|
+
from yoonpay.webhook import ( # noqa: E402
|
|
17
|
+
SIGNATURE_HEADER,
|
|
18
|
+
CacheEventStore,
|
|
19
|
+
Event,
|
|
20
|
+
EventStore,
|
|
21
|
+
MemoryEventStore,
|
|
22
|
+
sign_signature,
|
|
23
|
+
verify_signature,
|
|
24
|
+
)
|
|
25
|
+
|
|
26
|
+
__all__ = [
|
|
27
|
+
"SIGNATURE_HEADER",
|
|
28
|
+
"USER_AGENT",
|
|
29
|
+
"CacheEventStore",
|
|
30
|
+
"Event",
|
|
31
|
+
"EventStore",
|
|
32
|
+
"MemoryEventStore",
|
|
33
|
+
"Yoon",
|
|
34
|
+
"YoonException",
|
|
35
|
+
"__version__",
|
|
36
|
+
"sign_signature",
|
|
37
|
+
"verify_signature",
|
|
38
|
+
]
|
yoonpay/_version.py
ADDED
yoonpay/client.py
ADDED
|
@@ -0,0 +1,210 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import re
|
|
5
|
+
from datetime import datetime
|
|
6
|
+
from typing import Any, Callable, Literal, Mapping, Optional, TypeVar, Union
|
|
7
|
+
|
|
8
|
+
import urllib3
|
|
9
|
+
|
|
10
|
+
from yoonpay._version import USER_AGENT
|
|
11
|
+
from yoonpay.errors import YoonException
|
|
12
|
+
from yoonpay.generated import (
|
|
13
|
+
ApiClient,
|
|
14
|
+
ApiException,
|
|
15
|
+
Configuration,
|
|
16
|
+
CreatePaymentRequest,
|
|
17
|
+
CreatePayoutRequest,
|
|
18
|
+
CreateRefundRequest,
|
|
19
|
+
EventsApi,
|
|
20
|
+
LedgerApi,
|
|
21
|
+
MetaApi,
|
|
22
|
+
Payment,
|
|
23
|
+
PaymentsApi,
|
|
24
|
+
PayoutsApi,
|
|
25
|
+
Payout,
|
|
26
|
+
Refund,
|
|
27
|
+
RefundsApi,
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
from yoonpay.generated.api.exports_api import ExportsApi
|
|
31
|
+
|
|
32
|
+
T = TypeVar("T")
|
|
33
|
+
Export = Literal["payments", "refunds", "payouts", "ledger"]
|
|
34
|
+
|
|
35
|
+
_JSON = re.compile(r"^application/([\w.+-]+\+)?json\s*(;|$)", re.IGNORECASE)
|
|
36
|
+
_CSV = re.compile(r"^text/csv\s*(;|$)", re.IGNORECASE)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class _ApiClient(ApiClient):
|
|
40
|
+
"""The generated ApiClient with Yoon's defaults: timeouts on every call, and a 2xx that
|
|
41
|
+
cannot be read reported as ``unreadable_response`` instead of a parsing error."""
|
|
42
|
+
|
|
43
|
+
def __init__(self, configuration: Configuration, timeout: tuple[float, float]) -> None:
|
|
44
|
+
super().__init__(configuration)
|
|
45
|
+
self.user_agent = USER_AGENT
|
|
46
|
+
self._default_timeout = timeout
|
|
47
|
+
|
|
48
|
+
def call_api(self, method, url, header_params=None, body=None, post_params=None, _request_timeout=None): # type: ignore[no-untyped-def]
|
|
49
|
+
return super().call_api(
|
|
50
|
+
method,
|
|
51
|
+
url,
|
|
52
|
+
header_params=header_params,
|
|
53
|
+
body=body,
|
|
54
|
+
post_params=post_params,
|
|
55
|
+
_request_timeout=_request_timeout or self._default_timeout,
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
def response_deserialize(self, response_data, response_types_map=None): # type: ignore[no-untyped-def]
|
|
59
|
+
status = response_data.status
|
|
60
|
+
if not 200 <= status <= 299:
|
|
61
|
+
return super().response_deserialize(response_data, response_types_map)
|
|
62
|
+
content_type = response_data.getheader("content-type") or ""
|
|
63
|
+
expected = (response_types_map or {}).get(str(status))
|
|
64
|
+
if expected == "str":
|
|
65
|
+
if not _CSV.match(content_type):
|
|
66
|
+
raise YoonException.unreadable(status, f"expected CSV, content-type was {content_type or 'none'}")
|
|
67
|
+
elif (expected is not None or response_data.data) and not _JSON.match(content_type):
|
|
68
|
+
raise YoonException.unreadable(status, f"content-type was {content_type or 'none'}")
|
|
69
|
+
try:
|
|
70
|
+
return super().response_deserialize(response_data, response_types_map)
|
|
71
|
+
except (ValueError, ApiException) as error: # JSON or model validation failed
|
|
72
|
+
raise YoonException.unreadable(status, type(error).__name__) from error
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
class Yoon:
|
|
76
|
+
"""Entry point.
|
|
77
|
+
|
|
78
|
+
Common calls have helpers; every operation of the API contract is available on the
|
|
79
|
+
generated API objects (:meth:`payments`, :meth:`events`, …), wrapped with :meth:`call` to
|
|
80
|
+
get :class:`YoonException`. The client never retries: the caller retries with the same
|
|
81
|
+
idempotency key.
|
|
82
|
+
|
|
83
|
+
Every create call takes an idempotency key: use something tied to your intent (your
|
|
84
|
+
order id) so that a retry after a timeout returns the original result instead of
|
|
85
|
+
charging twice.
|
|
86
|
+
"""
|
|
87
|
+
|
|
88
|
+
def __init__(
|
|
89
|
+
self,
|
|
90
|
+
base_url: str,
|
|
91
|
+
api_key: str,
|
|
92
|
+
*,
|
|
93
|
+
timeout: float = 30.0,
|
|
94
|
+
connect_timeout: float = 5.0,
|
|
95
|
+
) -> None:
|
|
96
|
+
"""
|
|
97
|
+
:param base_url: where Yoon runs, e.g. ``https://pay.example.com``
|
|
98
|
+
:param api_key: the application key (``yk_…``)
|
|
99
|
+
:param timeout: seconds to wait for each read of the answer (default 30)
|
|
100
|
+
:param connect_timeout: seconds to establish the connection (default 5)
|
|
101
|
+
"""
|
|
102
|
+
if not isinstance(base_url, str) or not base_url:
|
|
103
|
+
raise ValueError("base_url must be a non-empty string, e.g. https://pay.example.com")
|
|
104
|
+
if not isinstance(api_key, str) or not api_key:
|
|
105
|
+
raise ValueError("api_key must be a non-empty string (yk_…)")
|
|
106
|
+
self.base_url = base_url.rstrip("/")
|
|
107
|
+
# retries=False: urllib3 would otherwise retry on its own. A retried payment must
|
|
108
|
+
# be the caller's decision, with the same idempotency key.
|
|
109
|
+
configuration = Configuration(host=self.base_url, access_token=api_key, retries=False)
|
|
110
|
+
self._client = _ApiClient(configuration, (float(connect_timeout), float(timeout)))
|
|
111
|
+
|
|
112
|
+
def __repr__(self) -> str: # never shows the API key
|
|
113
|
+
return f"Yoon({self.base_url!r})"
|
|
114
|
+
|
|
115
|
+
# ------------------------------------------------------------------ helpers
|
|
116
|
+
|
|
117
|
+
def create_payment(
|
|
118
|
+
self, payment: Union[CreatePaymentRequest, Mapping[str, Any]], idempotency_key: str
|
|
119
|
+
) -> Payment:
|
|
120
|
+
request = payment if isinstance(payment, CreatePaymentRequest) else CreatePaymentRequest.from_dict(dict(payment))
|
|
121
|
+
return self.call(lambda: self.payments().create_payment(_key(idempotency_key), request))
|
|
122
|
+
|
|
123
|
+
def get_payment(self, id: str) -> Payment:
|
|
124
|
+
return self.call(lambda: self.payments().get_payment(id))
|
|
125
|
+
|
|
126
|
+
def refund(
|
|
127
|
+
self,
|
|
128
|
+
payment_id: str,
|
|
129
|
+
idempotency_key: str,
|
|
130
|
+
amount: Optional[int] = None,
|
|
131
|
+
reason: Optional[str] = None,
|
|
132
|
+
) -> Refund:
|
|
133
|
+
"""``amount=None`` refunds whatever is left."""
|
|
134
|
+
request = CreateRefundRequest(amount=amount, reason=reason)
|
|
135
|
+
return self.call(lambda: self.refunds().create_refund(payment_id, _key(idempotency_key), request))
|
|
136
|
+
|
|
137
|
+
def create_payout(
|
|
138
|
+
self, payout: Union[CreatePayoutRequest, Mapping[str, Any]], idempotency_key: str
|
|
139
|
+
) -> Payout:
|
|
140
|
+
request = payout if isinstance(payout, CreatePayoutRequest) else CreatePayoutRequest.from_dict(dict(payout))
|
|
141
|
+
return self.call(lambda: self.payouts().create_payout(_key(idempotency_key), request))
|
|
142
|
+
|
|
143
|
+
def export_csv(
|
|
144
|
+
self, kind: Export, from_: Optional[datetime] = None, to: Optional[datetime] = None
|
|
145
|
+
) -> str:
|
|
146
|
+
"""A CSV export: amounts in minor units, UTC timestamps, phones masked.
|
|
147
|
+
|
|
148
|
+
:param kind: ``payments``, ``refunds``, ``payouts`` or ``ledger``
|
|
149
|
+
:param from_: inclusive, or ``None``
|
|
150
|
+
:param to: exclusive, or ``None``
|
|
151
|
+
"""
|
|
152
|
+
exports = ExportsApi(self._client)
|
|
153
|
+
calls: dict[str, Callable[..., str]] = {
|
|
154
|
+
"payments": exports.export_payments,
|
|
155
|
+
"refunds": exports.export_refunds,
|
|
156
|
+
"payouts": exports.export_payouts,
|
|
157
|
+
"ledger": exports.export_ledger,
|
|
158
|
+
}
|
|
159
|
+
if kind not in calls:
|
|
160
|
+
raise ValueError(f"Unknown export {kind!r}: payments, refunds, payouts or ledger")
|
|
161
|
+
return self.call(lambda: calls[kind](var_from=from_, to=to))
|
|
162
|
+
|
|
163
|
+
def call(self, fn: Callable[[], T]) -> T:
|
|
164
|
+
"""Runs any generated API call, turning errors into :class:`YoonException`."""
|
|
165
|
+
try:
|
|
166
|
+
return fn()
|
|
167
|
+
except YoonException:
|
|
168
|
+
raise
|
|
169
|
+
except ApiException as error:
|
|
170
|
+
if not error.status: # raised before an HTTP answer (e.g. a TLS failure)
|
|
171
|
+
raise YoonException.transport(error) from error
|
|
172
|
+
body = error.body if isinstance(error.body, str) else _decode(error.body)
|
|
173
|
+
raise YoonException.from_response(error.status, body) from error
|
|
174
|
+
except urllib3.exceptions.HTTPError as error: # connection refused, timeout, …
|
|
175
|
+
raise YoonException.transport(error) from error
|
|
176
|
+
|
|
177
|
+
# ------------------------------------------------------------------ generated APIs
|
|
178
|
+
|
|
179
|
+
def payments(self) -> PaymentsApi:
|
|
180
|
+
return PaymentsApi(self._client)
|
|
181
|
+
|
|
182
|
+
def refunds(self) -> RefundsApi:
|
|
183
|
+
return RefundsApi(self._client)
|
|
184
|
+
|
|
185
|
+
def payouts(self) -> PayoutsApi:
|
|
186
|
+
return PayoutsApi(self._client)
|
|
187
|
+
|
|
188
|
+
def events(self) -> EventsApi:
|
|
189
|
+
return EventsApi(self._client)
|
|
190
|
+
|
|
191
|
+
def ledger(self) -> LedgerApi:
|
|
192
|
+
return LedgerApi(self._client)
|
|
193
|
+
|
|
194
|
+
def meta(self) -> MetaApi:
|
|
195
|
+
return MetaApi(self._client)
|
|
196
|
+
|
|
197
|
+
|
|
198
|
+
def _key(idempotency_key: str) -> str:
|
|
199
|
+
if not isinstance(idempotency_key, str) or not idempotency_key:
|
|
200
|
+
raise ValueError("idempotency_key is required: tie it to your intent, e.g. your order id")
|
|
201
|
+
return idempotency_key
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
def _decode(body: Any) -> Optional[str]:
|
|
205
|
+
if isinstance(body, (bytes, bytearray)):
|
|
206
|
+
return body.decode("utf-8", "replace")
|
|
207
|
+
return None if body is None else json.dumps(body)
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
__all__ = ["Export", "Yoon"]
|
yoonpay/django.py
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
"""Django integration: ``pip install yoonpay[django]``.
|
|
2
|
+
|
|
3
|
+
::
|
|
4
|
+
|
|
5
|
+
# settings.py
|
|
6
|
+
YOON_WEBHOOK_SECRET = os.environ["YOON_WEBHOOK_SECRET"]
|
|
7
|
+
|
|
8
|
+
# views.py
|
|
9
|
+
from yoonpay.django import yoon_webhook
|
|
10
|
+
|
|
11
|
+
@yoon_webhook
|
|
12
|
+
def yoon_events(request, event):
|
|
13
|
+
if event.type == "payment.succeeded":
|
|
14
|
+
...
|
|
15
|
+
return HttpResponse(status=204)
|
|
16
|
+
|
|
17
|
+
The decorator exempts the view from CSRF, verifies the signature over ``request.body`` (401),
|
|
18
|
+
answers an already-handled event with 200 without calling the view, and remembers the id in
|
|
19
|
+
Django's cache only after the view answered 2xx.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from __future__ import annotations
|
|
23
|
+
|
|
24
|
+
import functools
|
|
25
|
+
from typing import Any, Callable, Optional
|
|
26
|
+
|
|
27
|
+
from django.conf import settings
|
|
28
|
+
from django.http import HttpRequest, HttpResponse, HttpResponseNotAllowed, JsonResponse
|
|
29
|
+
from django.views.decorators.csrf import csrf_exempt
|
|
30
|
+
|
|
31
|
+
from yoonpay.webhook import DEDUPE_SECONDS, SIGNATURE_HEADER, CacheEventStore, EventStore, check_delivery
|
|
32
|
+
|
|
33
|
+
View = Callable[..., HttpResponse]
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _default_store() -> EventStore:
|
|
37
|
+
from django.core.cache import caches
|
|
38
|
+
|
|
39
|
+
alias = getattr(settings, "YOON_WEBHOOK_CACHE", "default")
|
|
40
|
+
ttl = int(getattr(settings, "YOON_WEBHOOK_DEDUPE_SECONDS", DEDUPE_SECONDS))
|
|
41
|
+
return CacheEventStore(caches[alias], ttl)
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
def yoon_webhook(
|
|
45
|
+
view: Optional[View] = None, *, secret: Optional[str] = None, store: Optional[EventStore] = None
|
|
46
|
+
) -> Any:
|
|
47
|
+
"""Decorates a view ``(request, event, *args, **kwargs)``. ``secret`` defaults to
|
|
48
|
+
``settings.YOON_WEBHOOK_SECRET``; ``store`` to Django's ``default`` cache (or the alias in
|
|
49
|
+
``settings.YOON_WEBHOOK_CACHE``)."""
|
|
50
|
+
|
|
51
|
+
def decorate(view: View) -> View:
|
|
52
|
+
@csrf_exempt
|
|
53
|
+
@functools.wraps(view)
|
|
54
|
+
def wrapper(request: HttpRequest, *args: Any, **kwargs: Any) -> HttpResponse:
|
|
55
|
+
if request.method != "POST":
|
|
56
|
+
return HttpResponseNotAllowed(["POST"])
|
|
57
|
+
events = store or _default_store()
|
|
58
|
+
verdict = check_delivery(
|
|
59
|
+
request.body,
|
|
60
|
+
request.headers.get(SIGNATURE_HEADER),
|
|
61
|
+
secret if secret is not None else getattr(settings, "YOON_WEBHOOK_SECRET", None),
|
|
62
|
+
events,
|
|
63
|
+
)
|
|
64
|
+
if verdict.event is None:
|
|
65
|
+
return JsonResponse(verdict.body, status=verdict.status)
|
|
66
|
+
response = view(request, verdict.event, *args, **kwargs)
|
|
67
|
+
if 200 <= response.status_code < 300:
|
|
68
|
+
events.add(verdict.event.id)
|
|
69
|
+
return response
|
|
70
|
+
|
|
71
|
+
return wrapper
|
|
72
|
+
|
|
73
|
+
return decorate(view) if view is not None else decorate
|
yoonpay/errors.py
ADDED
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
from typing import Any, Optional
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
class YoonException(Exception):
|
|
8
|
+
"""An error answered by Yoon (``application/problem+json``), or a transport failure.
|
|
9
|
+
|
|
10
|
+
- ``problem_code`` is Yoon's stable code, e.g. ``no_provider_for_method``; ``None`` when
|
|
11
|
+
Yoon could not be reached — then retry with the same idempotency key;
|
|
12
|
+
``unreadable_response`` when Yoon answered 2xx with something this client could not
|
|
13
|
+
read (not retryable: the call may have succeeded, look it up before trying again).
|
|
14
|
+
- ``http_status`` is ``None`` when Yoon was not reached.
|
|
15
|
+
- ``problem`` is the full problem document when Yoon sent one.
|
|
16
|
+
|
|
17
|
+
The API key never appears in the message or the problem document.
|
|
18
|
+
"""
|
|
19
|
+
|
|
20
|
+
def __init__(
|
|
21
|
+
self,
|
|
22
|
+
message: str,
|
|
23
|
+
*,
|
|
24
|
+
http_status: Optional[int] = None,
|
|
25
|
+
problem_code: Optional[str] = None,
|
|
26
|
+
problem: Optional[dict[str, Any]] = None,
|
|
27
|
+
) -> None:
|
|
28
|
+
super().__init__(message)
|
|
29
|
+
self.http_status = http_status
|
|
30
|
+
self.problem_code = problem_code
|
|
31
|
+
self.problem = problem
|
|
32
|
+
|
|
33
|
+
def is_retryable(self) -> bool:
|
|
34
|
+
"""True when retrying with the same idempotency key is the right move."""
|
|
35
|
+
return (
|
|
36
|
+
self.problem_code is None
|
|
37
|
+
or self.problem_code == "idempotency_in_progress"
|
|
38
|
+
or (self.http_status is not None and self.http_status >= 500)
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
@classmethod
|
|
42
|
+
def transport(cls, cause: BaseException) -> "YoonException":
|
|
43
|
+
return cls(f"Yoon unreachable: {cause}")
|
|
44
|
+
|
|
45
|
+
@classmethod
|
|
46
|
+
def unreadable(cls, http_status: int, reason: str) -> "YoonException":
|
|
47
|
+
return cls(
|
|
48
|
+
f"Unreadable answer from Yoon: {reason}",
|
|
49
|
+
http_status=http_status,
|
|
50
|
+
problem_code="unreadable_response",
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
@classmethod
|
|
54
|
+
def from_response(cls, http_status: int, body: Optional[str]) -> "YoonException":
|
|
55
|
+
problem: Optional[dict[str, Any]] = None
|
|
56
|
+
try:
|
|
57
|
+
parsed = json.loads(body) if body else None
|
|
58
|
+
problem = parsed if isinstance(parsed, dict) else None
|
|
59
|
+
except ValueError:
|
|
60
|
+
pass # not a problem document (e.g. a proxy's HTML error page)
|
|
61
|
+
code = problem.get("code") if problem else None
|
|
62
|
+
detail = problem.get("detail") if problem else None
|
|
63
|
+
return cls(
|
|
64
|
+
detail if isinstance(detail, str) else f"Yoon answered HTTP {http_status}",
|
|
65
|
+
http_status=http_status,
|
|
66
|
+
problem_code=code if isinstance(code, str) else None,
|
|
67
|
+
problem=problem,
|
|
68
|
+
)
|
yoonpay/fastapi.py
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
"""FastAPI integration: ``pip install yoonpay[fastapi]``.
|
|
2
|
+
|
|
3
|
+
::
|
|
4
|
+
|
|
5
|
+
from fastapi import APIRouter, Depends
|
|
6
|
+
from yoonpay import Event
|
|
7
|
+
from yoonpay.fastapi import yoon_event, yoon_webhook_route
|
|
8
|
+
|
|
9
|
+
webhooks = APIRouter(route_class=yoon_webhook_route(secret=os.environ["YOON_WEBHOOK_SECRET"]))
|
|
10
|
+
|
|
11
|
+
@webhooks.post("/yoon/webhook", status_code=204)
|
|
12
|
+
def yoon_events(event: Event = Depends(yoon_event)) -> None:
|
|
13
|
+
if event.type == "payment.succeeded":
|
|
14
|
+
...
|
|
15
|
+
|
|
16
|
+
app.include_router(webhooks)
|
|
17
|
+
|
|
18
|
+
The route class verifies the signature over the raw body before FastAPI parses anything
|
|
19
|
+
(401), answers an already-handled event with 200 without calling the endpoint, and remembers
|
|
20
|
+
the id only after the endpoint answered 2xx: an endpoint that raises or answers an error gets
|
|
21
|
+
the retry. ``yoon_event`` is the dependency that hands the verified event to the endpoint.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
from __future__ import annotations
|
|
25
|
+
|
|
26
|
+
from typing import Any, Callable, Coroutine, Optional
|
|
27
|
+
|
|
28
|
+
from fastapi import Request, Response
|
|
29
|
+
from fastapi.responses import JSONResponse
|
|
30
|
+
from fastapi.routing import APIRoute
|
|
31
|
+
|
|
32
|
+
from yoonpay.webhook import SIGNATURE_HEADER, Event, EventStore, MemoryEventStore, check_delivery
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def yoon_webhook_route(secret: str, store: Optional[EventStore] = None) -> type[APIRoute]:
|
|
36
|
+
"""An ``APIRoute`` class for the routers that receive Yoon's events. ``store`` defaults to
|
|
37
|
+
an in-process :class:`~yoonpay.MemoryEventStore`; with several workers, pass a
|
|
38
|
+
:class:`~yoonpay.CacheEventStore` over a shared cache."""
|
|
39
|
+
if not secret:
|
|
40
|
+
raise ValueError("secret is required: the same value as YOON_APPS_<APP>_WEBHOOK_SECRET on the Yoon side")
|
|
41
|
+
events: EventStore = store if store is not None else MemoryEventStore()
|
|
42
|
+
|
|
43
|
+
class YoonWebhookRoute(APIRoute):
|
|
44
|
+
def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]:
|
|
45
|
+
endpoint = super().get_route_handler()
|
|
46
|
+
|
|
47
|
+
async def handler(request: Request) -> Response:
|
|
48
|
+
verdict = check_delivery(await request.body(), request.headers.get(SIGNATURE_HEADER), secret, events)
|
|
49
|
+
if verdict.event is None:
|
|
50
|
+
return JSONResponse(verdict.body, status_code=verdict.status)
|
|
51
|
+
request.state.yoon_event = verdict.event
|
|
52
|
+
response = await endpoint(request)
|
|
53
|
+
if 200 <= response.status_code < 300:
|
|
54
|
+
events.add(verdict.event.id)
|
|
55
|
+
return response
|
|
56
|
+
|
|
57
|
+
return handler
|
|
58
|
+
|
|
59
|
+
return YoonWebhookRoute
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def yoon_event(request: Request) -> Event:
|
|
63
|
+
"""Dependency: the verified event of a route built with :func:`yoon_webhook_route`."""
|
|
64
|
+
event = getattr(request.state, "yoon_event", None)
|
|
65
|
+
if not isinstance(event, Event):
|
|
66
|
+
raise RuntimeError("yoon_event is only available on routes whose router uses yoon_webhook_route()")
|
|
67
|
+
return event
|
yoonpay/flask.py
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
"""Flask integration: ``pip install yoonpay[flask]``.
|
|
2
|
+
|
|
3
|
+
::
|
|
4
|
+
|
|
5
|
+
app.config["YOON_WEBHOOK_SECRET"] = os.environ["YOON_WEBHOOK_SECRET"]
|
|
6
|
+
|
|
7
|
+
@app.post("/yoon/webhook")
|
|
8
|
+
@yoon_webhook
|
|
9
|
+
def yoon_events(event):
|
|
10
|
+
if event.type == "payment.succeeded":
|
|
11
|
+
...
|
|
12
|
+
return "", 204
|
|
13
|
+
|
|
14
|
+
The decorator verifies the signature over the raw body (``request.get_data()``, 401),
|
|
15
|
+
answers an already-handled event with 200 without calling the view, and remembers the id
|
|
16
|
+
only after the view answered 2xx.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
import functools
|
|
22
|
+
from typing import Any, Callable, Optional
|
|
23
|
+
|
|
24
|
+
from flask import Response, current_app, jsonify, request
|
|
25
|
+
|
|
26
|
+
from yoonpay.webhook import SIGNATURE_HEADER, EventStore, MemoryEventStore, check_delivery
|
|
27
|
+
|
|
28
|
+
View = Callable[..., Any]
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _default_store() -> EventStore:
|
|
32
|
+
store = current_app.extensions.get("yoonpay_event_store")
|
|
33
|
+
if store is None:
|
|
34
|
+
store = current_app.extensions["yoonpay_event_store"] = MemoryEventStore()
|
|
35
|
+
return store
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
def yoon_webhook(
|
|
39
|
+
view: Optional[View] = None, *, secret: Optional[str] = None, store: Optional[EventStore] = None
|
|
40
|
+
) -> Any:
|
|
41
|
+
"""Decorates a view ``(event, *args, **kwargs)``. ``secret`` defaults to
|
|
42
|
+
``app.config["YOON_WEBHOOK_SECRET"]``; ``store`` to an in-process
|
|
43
|
+
:class:`~yoonpay.MemoryEventStore` per app — with several workers, pass a
|
|
44
|
+
:class:`~yoonpay.CacheEventStore` over a shared cache (e.g. Flask-Caching)."""
|
|
45
|
+
|
|
46
|
+
def decorate(view: View) -> View:
|
|
47
|
+
@functools.wraps(view)
|
|
48
|
+
def wrapper(*args: Any, **kwargs: Any) -> Response:
|
|
49
|
+
events = store if store is not None else _default_store()
|
|
50
|
+
verdict = check_delivery(
|
|
51
|
+
request.get_data(cache=True),
|
|
52
|
+
request.headers.get(SIGNATURE_HEADER),
|
|
53
|
+
secret if secret is not None else current_app.config.get("YOON_WEBHOOK_SECRET"),
|
|
54
|
+
events,
|
|
55
|
+
)
|
|
56
|
+
if verdict.event is None:
|
|
57
|
+
response = jsonify(verdict.body)
|
|
58
|
+
response.status_code = verdict.status
|
|
59
|
+
return response
|
|
60
|
+
response = current_app.make_response(view(verdict.event, *args, **kwargs))
|
|
61
|
+
if 200 <= response.status_code < 300:
|
|
62
|
+
events.add(verdict.event.id)
|
|
63
|
+
return response
|
|
64
|
+
|
|
65
|
+
return wrapper
|
|
66
|
+
|
|
67
|
+
return decorate(view) if view is not None else decorate
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# coding: utf-8
|
|
2
|
+
|
|
3
|
+
# flake8: noqa
|
|
4
|
+
|
|
5
|
+
"""
|
|
6
|
+
Yoon API
|
|
7
|
+
|
|
8
|
+
Yoon is a self-hosted payment gateway. Your application sends **intent** — collect 5 000 XOF from this customer by Wave — and Yoon picks a configured provider, talks to it, verifies its callbacks and keeps a ledger. ## Conventions - **Authentication:** `Authorization: Bearer yk_…` on every `/v1` route except `/v1/about`. - **Money:** integer amounts in the currency's minor unit. XOF has none: 5 000 XOF is `5000`. Never floating point. - **Idempotency:** every `POST` requires an `Idempotency-Key` header. Retrying with the same key and body returns the original response (with `Idempotent-Replayed: true`). The same key with a different body is refused. Keys are kept for 24 hours. - **Errors:** [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json` with a stable machine-readable `code`. - **Lists:** newest first, cursor-paginated with `starting_after` and `limit` (max 100). - **Phone numbers** are returned masked (`+22177***67`). - **Unknown outcomes:** if a provider does not answer, the payment stays `pending` on that provider and is never sent to another one — the customer may already be paying.
|
|
9
|
+
|
|
10
|
+
The version of the OpenAPI document: 0.1.0
|
|
11
|
+
Generated by OpenAPI Generator (https://openapi-generator.tech)
|
|
12
|
+
|
|
13
|
+
Do not edit the class manually.
|
|
14
|
+
""" # noqa: E501
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
__version__ = "1.0.0"
|
|
18
|
+
|
|
19
|
+
# Define package exports
|
|
20
|
+
__all__ = [
|
|
21
|
+
"EventsApi",
|
|
22
|
+
"ExportsApi",
|
|
23
|
+
"LedgerApi",
|
|
24
|
+
"MetaApi",
|
|
25
|
+
"PaymentsApi",
|
|
26
|
+
"PayoutsApi",
|
|
27
|
+
"RefundsApi",
|
|
28
|
+
"ApiResponse",
|
|
29
|
+
"ApiClient",
|
|
30
|
+
"Configuration",
|
|
31
|
+
"OpenApiException",
|
|
32
|
+
"ApiTypeError",
|
|
33
|
+
"ApiValueError",
|
|
34
|
+
"ApiKeyError",
|
|
35
|
+
"ApiAttributeError",
|
|
36
|
+
"ApiException",
|
|
37
|
+
"AdminReplayDeadLetter202Response",
|
|
38
|
+
"AdminResolvePayoutRequest",
|
|
39
|
+
"CreatePaymentRequest",
|
|
40
|
+
"CreatePaymentRequestCustomer",
|
|
41
|
+
"CreatePayoutRequest",
|
|
42
|
+
"CreatePayoutRequestRecipient",
|
|
43
|
+
"CreateRefundRequest",
|
|
44
|
+
"DeliveryStatus",
|
|
45
|
+
"Event",
|
|
46
|
+
"EventDelivery",
|
|
47
|
+
"EventPage",
|
|
48
|
+
"EventPayload",
|
|
49
|
+
"EventPayloadData",
|
|
50
|
+
"EventPayloadDataObject",
|
|
51
|
+
"EventType",
|
|
52
|
+
"Failure",
|
|
53
|
+
"GetAbout200Response",
|
|
54
|
+
"GetBalances200Response",
|
|
55
|
+
"GetBalances200ResponseDataInner",
|
|
56
|
+
"LedgerEntry",
|
|
57
|
+
"LedgerEntryPage",
|
|
58
|
+
"ListProviders200ResponseInner",
|
|
59
|
+
"ListProviders200ResponseInnerCapabilitiesInner",
|
|
60
|
+
"Payment",
|
|
61
|
+
"PaymentCustomer",
|
|
62
|
+
"PaymentPage",
|
|
63
|
+
"PaymentStatus",
|
|
64
|
+
"Payout",
|
|
65
|
+
"PayoutPage",
|
|
66
|
+
"PayoutRecipient",
|
|
67
|
+
"PayoutStatus",
|
|
68
|
+
"Problem",
|
|
69
|
+
"ReceiveProviderCallback200Response",
|
|
70
|
+
"Refund",
|
|
71
|
+
"RefundPage",
|
|
72
|
+
"RefundStatus",
|
|
73
|
+
"StatusEvent",
|
|
74
|
+
]
|
|
75
|
+
|
|
76
|
+
# import apis into sdk package
|
|
77
|
+
from yoonpay.generated.api.events_api import EventsApi as EventsApi
|
|
78
|
+
from yoonpay.generated.api.exports_api import ExportsApi as ExportsApi
|
|
79
|
+
from yoonpay.generated.api.ledger_api import LedgerApi as LedgerApi
|
|
80
|
+
from yoonpay.generated.api.meta_api import MetaApi as MetaApi
|
|
81
|
+
from yoonpay.generated.api.payments_api import PaymentsApi as PaymentsApi
|
|
82
|
+
from yoonpay.generated.api.payouts_api import PayoutsApi as PayoutsApi
|
|
83
|
+
from yoonpay.generated.api.refunds_api import RefundsApi as RefundsApi
|
|
84
|
+
|
|
85
|
+
# import ApiClient
|
|
86
|
+
from yoonpay.generated.api_response import ApiResponse as ApiResponse
|
|
87
|
+
from yoonpay.generated.api_client import ApiClient as ApiClient
|
|
88
|
+
from yoonpay.generated.configuration import Configuration as Configuration
|
|
89
|
+
from yoonpay.generated.exceptions import OpenApiException as OpenApiException
|
|
90
|
+
from yoonpay.generated.exceptions import ApiTypeError as ApiTypeError
|
|
91
|
+
from yoonpay.generated.exceptions import ApiValueError as ApiValueError
|
|
92
|
+
from yoonpay.generated.exceptions import ApiKeyError as ApiKeyError
|
|
93
|
+
from yoonpay.generated.exceptions import ApiAttributeError as ApiAttributeError
|
|
94
|
+
from yoonpay.generated.exceptions import ApiException as ApiException
|
|
95
|
+
|
|
96
|
+
# import models into sdk package
|
|
97
|
+
from yoonpay.generated.models.admin_replay_dead_letter202_response import AdminReplayDeadLetter202Response as AdminReplayDeadLetter202Response
|
|
98
|
+
from yoonpay.generated.models.admin_resolve_payout_request import AdminResolvePayoutRequest as AdminResolvePayoutRequest
|
|
99
|
+
from yoonpay.generated.models.create_payment_request import CreatePaymentRequest as CreatePaymentRequest
|
|
100
|
+
from yoonpay.generated.models.create_payment_request_customer import CreatePaymentRequestCustomer as CreatePaymentRequestCustomer
|
|
101
|
+
from yoonpay.generated.models.create_payout_request import CreatePayoutRequest as CreatePayoutRequest
|
|
102
|
+
from yoonpay.generated.models.create_payout_request_recipient import CreatePayoutRequestRecipient as CreatePayoutRequestRecipient
|
|
103
|
+
from yoonpay.generated.models.create_refund_request import CreateRefundRequest as CreateRefundRequest
|
|
104
|
+
from yoonpay.generated.models.delivery_status import DeliveryStatus as DeliveryStatus
|
|
105
|
+
from yoonpay.generated.models.event import Event as Event
|
|
106
|
+
from yoonpay.generated.models.event_delivery import EventDelivery as EventDelivery
|
|
107
|
+
from yoonpay.generated.models.event_page import EventPage as EventPage
|
|
108
|
+
from yoonpay.generated.models.event_payload import EventPayload as EventPayload
|
|
109
|
+
from yoonpay.generated.models.event_payload_data import EventPayloadData as EventPayloadData
|
|
110
|
+
from yoonpay.generated.models.event_payload_data_object import EventPayloadDataObject as EventPayloadDataObject
|
|
111
|
+
from yoonpay.generated.models.event_type import EventType as EventType
|
|
112
|
+
from yoonpay.generated.models.failure import Failure as Failure
|
|
113
|
+
from yoonpay.generated.models.get_about200_response import GetAbout200Response as GetAbout200Response
|
|
114
|
+
from yoonpay.generated.models.get_balances200_response import GetBalances200Response as GetBalances200Response
|
|
115
|
+
from yoonpay.generated.models.get_balances200_response_data_inner import GetBalances200ResponseDataInner as GetBalances200ResponseDataInner
|
|
116
|
+
from yoonpay.generated.models.ledger_entry import LedgerEntry as LedgerEntry
|
|
117
|
+
from yoonpay.generated.models.ledger_entry_page import LedgerEntryPage as LedgerEntryPage
|
|
118
|
+
from yoonpay.generated.models.list_providers200_response_inner import ListProviders200ResponseInner as ListProviders200ResponseInner
|
|
119
|
+
from yoonpay.generated.models.list_providers200_response_inner_capabilities_inner import ListProviders200ResponseInnerCapabilitiesInner as ListProviders200ResponseInnerCapabilitiesInner
|
|
120
|
+
from yoonpay.generated.models.payment import Payment as Payment
|
|
121
|
+
from yoonpay.generated.models.payment_customer import PaymentCustomer as PaymentCustomer
|
|
122
|
+
from yoonpay.generated.models.payment_page import PaymentPage as PaymentPage
|
|
123
|
+
from yoonpay.generated.models.payment_status import PaymentStatus as PaymentStatus
|
|
124
|
+
from yoonpay.generated.models.payout import Payout as Payout
|
|
125
|
+
from yoonpay.generated.models.payout_page import PayoutPage as PayoutPage
|
|
126
|
+
from yoonpay.generated.models.payout_recipient import PayoutRecipient as PayoutRecipient
|
|
127
|
+
from yoonpay.generated.models.payout_status import PayoutStatus as PayoutStatus
|
|
128
|
+
from yoonpay.generated.models.problem import Problem as Problem
|
|
129
|
+
from yoonpay.generated.models.receive_provider_callback200_response import ReceiveProviderCallback200Response as ReceiveProviderCallback200Response
|
|
130
|
+
from yoonpay.generated.models.refund import Refund as Refund
|
|
131
|
+
from yoonpay.generated.models.refund_page import RefundPage as RefundPage
|
|
132
|
+
from yoonpay.generated.models.refund_status import RefundStatus as RefundStatus
|
|
133
|
+
from yoonpay.generated.models.status_event import StatusEvent as StatusEvent
|
|
134
|
+
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# flake8: noqa
|
|
2
|
+
|
|
3
|
+
# import apis into api package
|
|
4
|
+
from yoonpay.generated.api.events_api import EventsApi
|
|
5
|
+
from yoonpay.generated.api.exports_api import ExportsApi
|
|
6
|
+
from yoonpay.generated.api.ledger_api import LedgerApi
|
|
7
|
+
from yoonpay.generated.api.meta_api import MetaApi
|
|
8
|
+
from yoonpay.generated.api.payments_api import PaymentsApi
|
|
9
|
+
from yoonpay.generated.api.payouts_api import PayoutsApi
|
|
10
|
+
from yoonpay.generated.api.refunds_api import RefundsApi
|
|
11
|
+
|