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.
Files changed (66) hide show
  1. yoonpay/__init__.py +38 -0
  2. yoonpay/_version.py +2 -0
  3. yoonpay/client.py +210 -0
  4. yoonpay/django.py +73 -0
  5. yoonpay/errors.py +68 -0
  6. yoonpay/fastapi.py +67 -0
  7. yoonpay/flask.py +67 -0
  8. yoonpay/generated/__init__.py +134 -0
  9. yoonpay/generated/api/__init__.py +11 -0
  10. yoonpay/generated/api/events_api.py +937 -0
  11. yoonpay/generated/api/exports_api.py +1219 -0
  12. yoonpay/generated/api/ledger_api.py +640 -0
  13. yoonpay/generated/api/meta_api.py +530 -0
  14. yoonpay/generated/api/payments_api.py +1296 -0
  15. yoonpay/generated/api/payouts_api.py +1210 -0
  16. yoonpay/generated/api/refunds_api.py +1459 -0
  17. yoonpay/generated/api_client.py +804 -0
  18. yoonpay/generated/api_response.py +21 -0
  19. yoonpay/generated/configuration.py +589 -0
  20. yoonpay/generated/exceptions.py +216 -0
  21. yoonpay/generated/models/__init__.py +53 -0
  22. yoonpay/generated/models/admin_replay_dead_letter202_response.py +96 -0
  23. yoonpay/generated/models/admin_resolve_payout_request.py +97 -0
  24. yoonpay/generated/models/create_payment_request.py +122 -0
  25. yoonpay/generated/models/create_payment_request_customer.py +90 -0
  26. yoonpay/generated/models/create_payout_request.py +118 -0
  27. yoonpay/generated/models/create_payout_request_recipient.py +90 -0
  28. yoonpay/generated/models/create_refund_request.py +90 -0
  29. yoonpay/generated/models/delivery_status.py +48 -0
  30. yoonpay/generated/models/event.py +125 -0
  31. yoonpay/generated/models/event_delivery.py +119 -0
  32. yoonpay/generated/models/event_page.py +104 -0
  33. yoonpay/generated/models/event_payload.py +108 -0
  34. yoonpay/generated/models/event_payload_data.py +91 -0
  35. yoonpay/generated/models/event_payload_data_object.py +151 -0
  36. yoonpay/generated/models/event_type.py +52 -0
  37. yoonpay/generated/models/failure.py +89 -0
  38. yoonpay/generated/models/get_about200_response.py +93 -0
  39. yoonpay/generated/models/get_balances200_response.py +106 -0
  40. yoonpay/generated/models/get_balances200_response_data_inner.py +93 -0
  41. yoonpay/generated/models/ledger_entry.py +100 -0
  42. yoonpay/generated/models/ledger_entry_page.py +104 -0
  43. yoonpay/generated/models/list_providers200_response_inner.py +101 -0
  44. yoonpay/generated/models/list_providers200_response_inner_capabilities_inner.py +100 -0
  45. yoonpay/generated/models/payment.py +175 -0
  46. yoonpay/generated/models/payment_customer.py +92 -0
  47. yoonpay/generated/models/payment_page.py +104 -0
  48. yoonpay/generated/models/payment_status.py +49 -0
  49. yoonpay/generated/models/payout.py +149 -0
  50. yoonpay/generated/models/payout_page.py +104 -0
  51. yoonpay/generated/models/payout_recipient.py +92 -0
  52. yoonpay/generated/models/payout_status.py +49 -0
  53. yoonpay/generated/models/problem.py +97 -0
  54. yoonpay/generated/models/receive_provider_callback200_response.py +87 -0
  55. yoonpay/generated/models/refund.py +132 -0
  56. yoonpay/generated/models/refund_page.py +104 -0
  57. yoonpay/generated/models/refund_status.py +49 -0
  58. yoonpay/generated/models/status_event.py +129 -0
  59. yoonpay/generated/py.typed +0 -0
  60. yoonpay/generated/rest.py +258 -0
  61. yoonpay/py.typed +0 -0
  62. yoonpay/webhook.py +181 -0
  63. yoonpay-0.1.0.dist-info/METADATA +197 -0
  64. yoonpay-0.1.0.dist-info/RECORD +66 -0
  65. yoonpay-0.1.0.dist-info/WHEEL +4 -0
  66. 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
@@ -0,0 +1,2 @@
1
+ __version__ = "0.1.0"
2
+ USER_AGENT = f"yoon-python/{__version__}"
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
+