fastapi-myanmar-payments 0.1.0.dev0__tar.gz

fastapi_myanmar_payments-0.1.0.dev0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+.DS_Store
+/.idea

fastapi_myanmar_payments-0.1.0.dev0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to `fastapi-myanmar-payments` will be documented in this file. Releases are tagged `fastapi/v<version>`.
+
+## fastapi/v0.1.0 - Unreleased
+
+Initial release, for `python-myanmar-payments` 4.0.0a16 or later (below 5) and FastAPI 0.115 or later.
+
+### Added
+- `payments_lifespan()`: one `AsyncMyanmarPayments` per application on `app.state`, created from a factory and closed at shutdown, or an instance you own and close yourself.
+- Dependencies `get_payments`, `get_kbz_pay`, `get_wave_pay`, `get_aya_pay`, `get_yoma_mmqr` and `get_cyber_source`, with `Annotated` aliases (`PaymentsDep`, `KbzPayDep`, ...).
+- `callback_request` / `CallbackRequestDep`: the core `CallbackRequest` from the raw body bytes, headers and query string.
+- `verify_callback()`: the gateway's `handle_callback()`, answering a `SignatureVerificationError` with a generic 400.
+- `acknowledgement_response()`: the gateway's `Acknowledgement` as a response with its exact status, body and headers.
+- An agent skill, `skills/fastapi-myanmar-payments/SKILL.md`, describing how to use the adapter in an application.
+
+### Notes
+- `python-myanmar-payments` 4.0.0 is still a pre-release; its pre-releases may contain breaking changes. The adapter is tested against 4.0.0a16 and the newest published core.

fastapi_myanmar_payments-0.1.0.dev0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Nay Thu Khant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_myanmar_payments-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,302 @@
+Metadata-Version: 2.5
+Name: fastapi-myanmar-payments
+Version: 0.1.0.dev0
+Summary: FastAPI integration for python-myanmar-payments: lifespan, dependencies, verified callbacks and gateway acknowledgements.
+Project-URL: Homepage, https://github.com/laranex/python-myanmar-payments/tree/dev/adapters/fastapi
+Project-URL: Documentation, https://github.com/laranex/python-myanmar-payments/tree/dev/adapters/fastapi#readme
+Project-URL: Repository, https://github.com/laranex/python-myanmar-payments
+Project-URL: Issues, https://github.com/laranex/python-myanmar-payments/issues
+Project-URL: Changelog, https://github.com/laranex/python-myanmar-payments/blob/dev/adapters/fastapi/CHANGELOG.md
+Author-email: Soe Thura <thixpin@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.md
+Keywords: fastapi,laranex,myanmar,payment-gateway,payments,python-myanmar-payments,webhooks
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.115
+Requires-Dist: python-myanmar-payments<5,>=4.0.0a16
+Description-Content-Type: text/markdown
+
+# FastAPI Myanmar Payments
+
+Optional FastAPI integration for [python-myanmar-payments](https://pypi.org/project/python-myanmar-payments/): a lifespan that owns one payments facade, dependencies for its gateways, raw callback requests, verification that answers bad signatures with a 400, and the gateway's acknowledgement as a response.
+
+> **You don't need this package to use FastAPI.** The core SDK already has async clients (`AsyncKbzPay`, `AsyncWavePay`, ...) that work in any FastAPI endpoint. This adapter only removes the framework glue. Payments, signing, callback verification, amounts and status mapping all stay in `python-myanmar-payments`; see its [documentation](https://laranex.vercel.app/python-myanmar-payments) for each gateway.
+
+## Installation
+
+Requires Python 3.10+, FastAPI 0.115+ and `python-myanmar-payments` 4.0.0a16 or later (below 5).
+
+```bash
+pip install fastapi-myanmar-payments
+```
+
+```bash
+uv add fastapi-myanmar-payments
+```
+
+The version range names a pre-release, so pip and uv install the core's pre-releases without extra flags.
+
+> **Pre-release core.** `python-myanmar-payments` 4.0.0 is still in alpha, and its pre-releases may contain breaking changes (4.0.0a16, for example, renamed Wave Money to Wave Pay). This adapter is tested against the oldest supported core (4.0.0a16) and the newest published one. Pin both packages in your application's lock file and upgrade them together.
+
+## Quick start
+
+```python
+from fastapi import FastAPI, Response
+from python_myanmar_payments import AsyncMyanmarPayments
+
+from fastapi_myanmar_payments import (
+    CallbackRequestDep,
+    KbzPayDep,
+    acknowledgement_response,
+    payments_lifespan,
+    verify_callback,
+)
+
+app = FastAPI(lifespan=payments_lifespan(AsyncMyanmarPayments.from_env))
+
+
+@app.post("/payments/kbz/callback")
+async def kbz_callback(kbz: KbzPayDep, request: CallbackRequestDep) -> Response:
+    callback = verify_callback(kbz, request)  # 400 on a bad signature
+    ...  # validate and persist it: see "Secure webhooks"
+    return acknowledgement_response(callback.acknowledgement)
+```
+
+## Configuration
+
+The adapter adds no settings. Configure the facade exactly as the core SDK documents ([Configuration](https://laranex.vercel.app/python-myanmar-payments/configuration)):
+
+- `AsyncMyanmarPayments.from_env` reads `KBZ_PAY_*`, `WAVE_PAY_*`, `AYA_PAY_*`, `YOMA_MMQR_*`, `CYBER_SOURCE_*` and `MYANMAR_PAYMENTS_HTTP_TIMEOUT` when each gateway is first used.
+- Or pass a factory that builds it from your own settings:
+
+```python
+from python_myanmar_payments import AsyncMyanmarPayments
+
+def build_payments() -> AsyncMyanmarPayments:
+    return AsyncMyanmarPayments(
+        kbz_pay={"app_id": settings.kbz_app_id, ...},
+        wave_pay={"merchant_id": settings.wave_merchant_id, ...},
+    )
+
+app = FastAPI(lifespan=payments_lifespan(build_payments))
+```
+
+Only the gateways you use need to be configured. Using one that is not raises the core `ConfigurationError` (`gateway`, `key`), which FastAPI answers with a 500.
+
+## Lifespan
+
+`payments_lifespan(...)` stores one `AsyncMyanmarPayments` on `app.state` for the life of the application, so every request reuses the same gateways, HTTP connections and Yoma MMQR token cache. Nothing is created per request.
+
+Who closes what:
+
+| You pass | At shutdown |
+| --- | --- |
+| A factory, e.g. `AsyncMyanmarPayments.from_env` | The lifespan calls `aclose()`, which closes only the HTTP clients the gateways created. |
+| An instance, e.g. `payments_lifespan(my_payments)` | Nothing is closed; it is yours. |
+| An `http_client` or `token_cache` inside the facade | Never closed by the adapter or the core SDK; close it yourself. |
+
+Combine it with your own lifespan:
+
+```python
+from contextlib import asynccontextmanager
+
+payments = payments_lifespan(AsyncMyanmarPayments.from_env)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with payments(app):
+        # your own startup
+        yield
+        # your own shutdown
+
+
+app = FastAPI(lifespan=lifespan)
+```
+
+Share your own `httpx.AsyncClient` (proxies, tracing, limits):
+
+```python
+import httpx
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with httpx.AsyncClient(timeout=30) as http_client:  # you close it
+        factory = lambda: AsyncMyanmarPayments.from_env(http_client=http_client)
+        async with payments_lifespan(factory)(app):
+            yield
+```
+
+## Dependency injection
+
+| Dependency | Annotated alias | Gives |
+| --- | --- | --- |
+| `get_payments` | `PaymentsDep` | `AsyncMyanmarPayments` |
+| `get_kbz_pay` | `KbzPayDep` | `AsyncKbzPay` |
+| `get_wave_pay` | `WavePayDep` | `AsyncWavePay` |
+| `get_aya_pay` | `AyaPayDep` | `AsyncAyaPay` |
+| `get_yoma_mmqr` | `YomaMmqrDep` | `AsyncYomaMmqr` |
+| `get_cyber_source` | `CyberSourceDep` | `CyberSource` |
+| `callback_request` | `CallbackRequestDep` | the core `CallbackRequest` (raw body, headers and query string) |
+
+Every gateway dependency reads the facade through `get_payments`, so overriding `get_payments` replaces them all. Without a lifespan (and without an override), `get_payments` raises a `RuntimeError` that says so.
+
+## Async payment initiation
+
+```python
+from fastapi import HTTPException
+from fastapi.responses import RedirectResponse
+from python_myanmar_payments import Amount, ApiError, InvalidPaymentDataError, KbzPayPaymentData
+
+from fastapi_myanmar_payments import KbzPayDep
+
+
+@app.post("/orders/{order_id}/pay")
+async def pay(order_id: str, kbz: KbzPayDep) -> RedirectResponse:
+    order = await orders.get(order_id)  # your storage
+    try:
+        payment = await kbz.pwa(
+            KbzPayPaymentData(
+                order_id=order.id,
+                amount=Amount.parse(order.amount),
+                callback_url="https://shop.example/payments/kbz/callback",
+            )
+        )
+    except InvalidPaymentDataError as error:
+        raise HTTPException(422, detail=dict(error.errors)) from error
+    except ApiError as error:
+        raise HTTPException(502, detail="The payment gateway is unavailable.") from error
+    return RedirectResponse(payment.url, status_code=303)
+```
+
+Don't retry a failed initiation automatically: the gateway may have created the payment before the error reached you. Check `kbz.status(order_id)` (KBZ Pay, AYA Pay; Yoma MMQR by QR reference) or let the customer try again with a new attempt where the gateway requires one (Wave Pay's `merchant_reference_id`).
+
+`AyaPay.initiate()` and `CyberSource.initiate()` make no network call and return a `FormPayment`; return `HTMLResponse(payment.to_html())`.
+
+## Secure webhooks
+
+Use this order for every gateway callback: **verify → validate against the stored order → persist → acknowledge → process once.**
+
+```python
+from fastapi import Response
+from python_myanmar_payments import Amount
+
+from fastapi_myanmar_payments import (
+    CallbackRequestDep,
+    WavePayDep,
+    acknowledgement_response,
+    verify_callback,
+)
+
+
+@app.post("/payments/wave/callback")
+async def wave_callback(wave: WavePayDep, request: CallbackRequestDep) -> Response:
+    # 1. Verify. A bad signature or a malformed signed callback becomes a 400;
+    #    nothing from an unverified payload is trusted, stored or echoed.
+    callback = verify_callback(wave, request)
+
+    # 2. Validate against your stored order, never against the callback alone.
+    #    An unknown order is still recorded (step 3), never created or marked paid.
+    order = await orders.get(callback.order_id)
+    # Not every gateway sends an amount (Yoma MMQR doesn't): compare it when present.
+    amount_matches = order is not None and (
+        callback.amount is None or Amount.parse(order.amount).equals(callback.amount)
+    )
+
+    # 3. Persist durably and idempotently, e.g. a unique key on
+    #    (gateway, order_id, gateway_status, gateway_reference). A duplicate
+    #    delivery hits the key and is simply acknowledged again. If this raises,
+    #    the request fails with a 5xx and nothing is acknowledged.
+    await webhook_events.insert_once(
+        gateway="wave_pay",
+        order_id=callback.order_id,
+        order_known=order is not None,
+        status=callback.status,
+        gateway_status=callback.gateway_status,
+        gateway_reference=callback.gateway_reference,
+        amount_matches=amount_matches,
+        raw=dict(callback.raw),
+    )
+
+    # 4. Acknowledge only after step 3 has committed, with the gateway's exact response.
+    return acknowledgement_response(callback.acknowledgement)
+
+
+# 5. Process once, outside the request: a worker claims each stored event
+#    (e.g. UPDATE ... SET processed_at = now() WHERE id = ? AND processed_at IS NULL),
+#    fulfills the order only when it is known, PaymentStatus.SUCCESSFUL and
+#    amount_matches, and flags unknown orders and mismatches for review.
+```
+
+Failure and retry behavior:
+
+- **Verification fails** → 400. The gateway may retry; a forged or corrupted callback keeps failing. Log `error.__cause__` (a `SignatureVerificationError`) if you need it; its message never contains your secrets, but its `raw` payload is unverified.
+- **Unknown order** (a verified callback for an order you don't have, e.g. from another environment or a deleted order) → record it durably as an unknown-order event, then return the gateway's acknowledgement so it stops retrying. Never create the order or mark anything paid from it; review it by hand.
+- **Persisting fails** (database down) → let the exception produce a 5xx. Don't return the acknowledgement: the gateway retries later, so nothing is lost.
+- **Persisted, but processing fails later** → the event stays unprocessed in your store; retry it from your worker. The gateway already has its acknowledgement and must not be relied on to resend.
+- **Duplicates** are normal: gateways retry until they receive the acknowledgement. The idempotent insert and the once-only claim make them harmless.
+- FastAPI `BackgroundTasks` run in the same process after the response; they are lost on a crash or deploy. Use them only for work you can redo from the persisted event.
+- Never fulfill from a browser return or redirect; it is not proof of payment. For AYA Pay's signed return, `aya.verify_redirect(request)` shows the right page; fulfill from the callback or `status()`.
+- Yoma MMQR also checks the `X-Webhook-Secret` header, which `CallbackRequestDep` passes through unchanged.
+
+`callback_request` hands the core SDK the raw body bytes, the headers and the raw query string: it never decodes and re-encodes JSON or forms, so numbers like `1000.50` and form encoding reach the signature check exactly as sent. Don't read the body with `await request.json()` or `await request.form()` and rebuild it.
+
+## Testing
+
+No credentials or network are needed. Run the app in-process with `httpx.ASGITransport` and its own lifespan, and give the facade an `http_client` that answers from `httpx.MockTransport`. (FastAPI's `TestClient` works too, though recent Starlette versions ask for `httpx2` with it.)
+
+```python
+import httpx
+import pytest
+from python_myanmar_payments import AsyncMyanmarPayments
+
+from fastapi_myanmar_payments import get_payments
+
+
+def handler(request: httpx.Request) -> httpx.Response:
+    return httpx.Response(200, json={"message": "success", "transaction_id": "T1"})
+
+
+@pytest.mark.anyio
+async def test_pay() -> None:
+    fake = AsyncMyanmarPayments(
+        wave_pay={...},  # test credentials
+        http_client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),
+    )
+    app.dependency_overrides[get_payments] = lambda: fake
+    async with (
+        app.router.lifespan_context(app),
+        httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as client,
+    ):
+        response = await client.post("/orders/100/pay")
+    assert response.status_code == 303
+    app.dependency_overrides.clear()
+```
+
+- Override one gateway with `app.dependency_overrides[get_kbz_pay] = ...`.
+- Test your fulfillment code with a `PaymentCallback(order_id=..., status=PaymentStatus.SUCCESSFUL, gateway_status=...)` you build yourself.
+- Callbacks you post through `TestClient` are still signature-checked; sign them with your test secret (see the core SDK's [Testing](https://laranex.vercel.app/python-myanmar-payments/testing) guide).
+
+## What this package does not do
+
+No webhook router, no storage, no background processing, no retries and no automatic fulfillment: those decisions stay in your application. Request body size limits belong to your server or proxy.
+
+## License
+
+MIT. See [LICENSE](LICENSE.md).

fastapi_myanmar_payments-0.1.0.dev0/README.md

@@ -0,0 +1,269 @@
+# FastAPI Myanmar Payments
+
+Optional FastAPI integration for [python-myanmar-payments](https://pypi.org/project/python-myanmar-payments/): a lifespan that owns one payments facade, dependencies for its gateways, raw callback requests, verification that answers bad signatures with a 400, and the gateway's acknowledgement as a response.
+
+> **You don't need this package to use FastAPI.** The core SDK already has async clients (`AsyncKbzPay`, `AsyncWavePay`, ...) that work in any FastAPI endpoint. This adapter only removes the framework glue. Payments, signing, callback verification, amounts and status mapping all stay in `python-myanmar-payments`; see its [documentation](https://laranex.vercel.app/python-myanmar-payments) for each gateway.
+
+## Installation
+
+Requires Python 3.10+, FastAPI 0.115+ and `python-myanmar-payments` 4.0.0a16 or later (below 5).
+
+```bash
+pip install fastapi-myanmar-payments
+```
+
+```bash
+uv add fastapi-myanmar-payments
+```
+
+The version range names a pre-release, so pip and uv install the core's pre-releases without extra flags.
+
+> **Pre-release core.** `python-myanmar-payments` 4.0.0 is still in alpha, and its pre-releases may contain breaking changes (4.0.0a16, for example, renamed Wave Money to Wave Pay). This adapter is tested against the oldest supported core (4.0.0a16) and the newest published one. Pin both packages in your application's lock file and upgrade them together.
+
+## Quick start
+
+```python
+from fastapi import FastAPI, Response
+from python_myanmar_payments import AsyncMyanmarPayments
+
+from fastapi_myanmar_payments import (
+    CallbackRequestDep,
+    KbzPayDep,
+    acknowledgement_response,
+    payments_lifespan,
+    verify_callback,
+)
+
+app = FastAPI(lifespan=payments_lifespan(AsyncMyanmarPayments.from_env))
+
+
+@app.post("/payments/kbz/callback")
+async def kbz_callback(kbz: KbzPayDep, request: CallbackRequestDep) -> Response:
+    callback = verify_callback(kbz, request)  # 400 on a bad signature
+    ...  # validate and persist it: see "Secure webhooks"
+    return acknowledgement_response(callback.acknowledgement)
+```
+
+## Configuration
+
+The adapter adds no settings. Configure the facade exactly as the core SDK documents ([Configuration](https://laranex.vercel.app/python-myanmar-payments/configuration)):
+
+- `AsyncMyanmarPayments.from_env` reads `KBZ_PAY_*`, `WAVE_PAY_*`, `AYA_PAY_*`, `YOMA_MMQR_*`, `CYBER_SOURCE_*` and `MYANMAR_PAYMENTS_HTTP_TIMEOUT` when each gateway is first used.
+- Or pass a factory that builds it from your own settings:
+
+```python
+from python_myanmar_payments import AsyncMyanmarPayments
+
+def build_payments() -> AsyncMyanmarPayments:
+    return AsyncMyanmarPayments(
+        kbz_pay={"app_id": settings.kbz_app_id, ...},
+        wave_pay={"merchant_id": settings.wave_merchant_id, ...},
+    )
+
+app = FastAPI(lifespan=payments_lifespan(build_payments))
+```
+
+Only the gateways you use need to be configured. Using one that is not raises the core `ConfigurationError` (`gateway`, `key`), which FastAPI answers with a 500.
+
+## Lifespan
+
+`payments_lifespan(...)` stores one `AsyncMyanmarPayments` on `app.state` for the life of the application, so every request reuses the same gateways, HTTP connections and Yoma MMQR token cache. Nothing is created per request.
+
+Who closes what:
+
+| You pass | At shutdown |
+| --- | --- |
+| A factory, e.g. `AsyncMyanmarPayments.from_env` | The lifespan calls `aclose()`, which closes only the HTTP clients the gateways created. |
+| An instance, e.g. `payments_lifespan(my_payments)` | Nothing is closed; it is yours. |
+| An `http_client` or `token_cache` inside the facade | Never closed by the adapter or the core SDK; close it yourself. |
+
+Combine it with your own lifespan:
+
+```python
+from contextlib import asynccontextmanager
+
+payments = payments_lifespan(AsyncMyanmarPayments.from_env)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with payments(app):
+        # your own startup
+        yield
+        # your own shutdown
+
+
+app = FastAPI(lifespan=lifespan)
+```
+
+Share your own `httpx.AsyncClient` (proxies, tracing, limits):
+
+```python
+import httpx
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with httpx.AsyncClient(timeout=30) as http_client:  # you close it
+        factory = lambda: AsyncMyanmarPayments.from_env(http_client=http_client)
+        async with payments_lifespan(factory)(app):
+            yield
+```
+
+## Dependency injection
+
+| Dependency | Annotated alias | Gives |
+| --- | --- | --- |
+| `get_payments` | `PaymentsDep` | `AsyncMyanmarPayments` |
+| `get_kbz_pay` | `KbzPayDep` | `AsyncKbzPay` |
+| `get_wave_pay` | `WavePayDep` | `AsyncWavePay` |
+| `get_aya_pay` | `AyaPayDep` | `AsyncAyaPay` |
+| `get_yoma_mmqr` | `YomaMmqrDep` | `AsyncYomaMmqr` |
+| `get_cyber_source` | `CyberSourceDep` | `CyberSource` |
+| `callback_request` | `CallbackRequestDep` | the core `CallbackRequest` (raw body, headers and query string) |
+
+Every gateway dependency reads the facade through `get_payments`, so overriding `get_payments` replaces them all. Without a lifespan (and without an override), `get_payments` raises a `RuntimeError` that says so.
+
+## Async payment initiation
+
+```python
+from fastapi import HTTPException
+from fastapi.responses import RedirectResponse
+from python_myanmar_payments import Amount, ApiError, InvalidPaymentDataError, KbzPayPaymentData
+
+from fastapi_myanmar_payments import KbzPayDep
+
+
+@app.post("/orders/{order_id}/pay")
+async def pay(order_id: str, kbz: KbzPayDep) -> RedirectResponse:
+    order = await orders.get(order_id)  # your storage
+    try:
+        payment = await kbz.pwa(
+            KbzPayPaymentData(
+                order_id=order.id,
+                amount=Amount.parse(order.amount),
+                callback_url="https://shop.example/payments/kbz/callback",
+            )
+        )
+    except InvalidPaymentDataError as error:
+        raise HTTPException(422, detail=dict(error.errors)) from error
+    except ApiError as error:
+        raise HTTPException(502, detail="The payment gateway is unavailable.") from error
+    return RedirectResponse(payment.url, status_code=303)
+```
+
+Don't retry a failed initiation automatically: the gateway may have created the payment before the error reached you. Check `kbz.status(order_id)` (KBZ Pay, AYA Pay; Yoma MMQR by QR reference) or let the customer try again with a new attempt where the gateway requires one (Wave Pay's `merchant_reference_id`).
+
+`AyaPay.initiate()` and `CyberSource.initiate()` make no network call and return a `FormPayment`; return `HTMLResponse(payment.to_html())`.
+
+## Secure webhooks
+
+Use this order for every gateway callback: **verify → validate against the stored order → persist → acknowledge → process once.**
+
+```python
+from fastapi import Response
+from python_myanmar_payments import Amount
+
+from fastapi_myanmar_payments import (
+    CallbackRequestDep,
+    WavePayDep,
+    acknowledgement_response,
+    verify_callback,
+)
+
+
+@app.post("/payments/wave/callback")
+async def wave_callback(wave: WavePayDep, request: CallbackRequestDep) -> Response:
+    # 1. Verify. A bad signature or a malformed signed callback becomes a 400;
+    #    nothing from an unverified payload is trusted, stored or echoed.
+    callback = verify_callback(wave, request)
+
+    # 2. Validate against your stored order, never against the callback alone.
+    #    An unknown order is still recorded (step 3), never created or marked paid.
+    order = await orders.get(callback.order_id)
+    # Not every gateway sends an amount (Yoma MMQR doesn't): compare it when present.
+    amount_matches = order is not None and (
+        callback.amount is None or Amount.parse(order.amount).equals(callback.amount)
+    )
+
+    # 3. Persist durably and idempotently, e.g. a unique key on
+    #    (gateway, order_id, gateway_status, gateway_reference). A duplicate
+    #    delivery hits the key and is simply acknowledged again. If this raises,
+    #    the request fails with a 5xx and nothing is acknowledged.
+    await webhook_events.insert_once(
+        gateway="wave_pay",
+        order_id=callback.order_id,
+        order_known=order is not None,
+        status=callback.status,
+        gateway_status=callback.gateway_status,
+        gateway_reference=callback.gateway_reference,
+        amount_matches=amount_matches,
+        raw=dict(callback.raw),
+    )
+
+    # 4. Acknowledge only after step 3 has committed, with the gateway's exact response.
+    return acknowledgement_response(callback.acknowledgement)
+
+
+# 5. Process once, outside the request: a worker claims each stored event
+#    (e.g. UPDATE ... SET processed_at = now() WHERE id = ? AND processed_at IS NULL),
+#    fulfills the order only when it is known, PaymentStatus.SUCCESSFUL and
+#    amount_matches, and flags unknown orders and mismatches for review.
+```
+
+Failure and retry behavior:
+
+- **Verification fails** → 400. The gateway may retry; a forged or corrupted callback keeps failing. Log `error.__cause__` (a `SignatureVerificationError`) if you need it; its message never contains your secrets, but its `raw` payload is unverified.
+- **Unknown order** (a verified callback for an order you don't have, e.g. from another environment or a deleted order) → record it durably as an unknown-order event, then return the gateway's acknowledgement so it stops retrying. Never create the order or mark anything paid from it; review it by hand.
+- **Persisting fails** (database down) → let the exception produce a 5xx. Don't return the acknowledgement: the gateway retries later, so nothing is lost.
+- **Persisted, but processing fails later** → the event stays unprocessed in your store; retry it from your worker. The gateway already has its acknowledgement and must not be relied on to resend.
+- **Duplicates** are normal: gateways retry until they receive the acknowledgement. The idempotent insert and the once-only claim make them harmless.
+- FastAPI `BackgroundTasks` run in the same process after the response; they are lost on a crash or deploy. Use them only for work you can redo from the persisted event.
+- Never fulfill from a browser return or redirect; it is not proof of payment. For AYA Pay's signed return, `aya.verify_redirect(request)` shows the right page; fulfill from the callback or `status()`.
+- Yoma MMQR also checks the `X-Webhook-Secret` header, which `CallbackRequestDep` passes through unchanged.
+
+`callback_request` hands the core SDK the raw body bytes, the headers and the raw query string: it never decodes and re-encodes JSON or forms, so numbers like `1000.50` and form encoding reach the signature check exactly as sent. Don't read the body with `await request.json()` or `await request.form()` and rebuild it.
+
+## Testing
+
+No credentials or network are needed. Run the app in-process with `httpx.ASGITransport` and its own lifespan, and give the facade an `http_client` that answers from `httpx.MockTransport`. (FastAPI's `TestClient` works too, though recent Starlette versions ask for `httpx2` with it.)
+
+```python
+import httpx
+import pytest
+from python_myanmar_payments import AsyncMyanmarPayments
+
+from fastapi_myanmar_payments import get_payments
+
+
+def handler(request: httpx.Request) -> httpx.Response:
+    return httpx.Response(200, json={"message": "success", "transaction_id": "T1"})
+
+
+@pytest.mark.anyio
+async def test_pay() -> None:
+    fake = AsyncMyanmarPayments(
+        wave_pay={...},  # test credentials
+        http_client=httpx.AsyncClient(transport=httpx.MockTransport(handler)),
+    )
+    app.dependency_overrides[get_payments] = lambda: fake
+    async with (
+        app.router.lifespan_context(app),
+        httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test") as client,
+    ):
+        response = await client.post("/orders/100/pay")
+    assert response.status_code == 303
+    app.dependency_overrides.clear()
+```
+
+- Override one gateway with `app.dependency_overrides[get_kbz_pay] = ...`.
+- Test your fulfillment code with a `PaymentCallback(order_id=..., status=PaymentStatus.SUCCESSFUL, gateway_status=...)` you build yourself.
+- Callbacks you post through `TestClient` are still signature-checked; sign them with your test secret (see the core SDK's [Testing](https://laranex.vercel.app/python-myanmar-payments/testing) guide).
+
+## What this package does not do
+
+No webhook router, no storage, no background processing, no retries and no automatic fulfillment: those decisions stay in your application. Request body size limits belong to your server or proxy.
+
+## License
+
+MIT. See [LICENSE](LICENSE.md).

fastapi_myanmar_payments-0.1.0.dev0/pyproject.toml

@@ -0,0 +1,106 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fastapi-myanmar-payments"
+dynamic = ["version"]
+description = "FastAPI integration for python-myanmar-payments: lifespan, dependencies, verified callbacks and gateway acknowledgements."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE.md"]
+requires-python = ">=3.10"
+authors = [{ name = "Soe Thura", email = "thixpin@gmail.com" }]
+keywords = [
+    "laranex",
+    "python-myanmar-payments",
+    "fastapi",
+    "myanmar",
+    "payments",
+    "payment-gateway",
+    "webhooks",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Framework :: AsyncIO",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+# 4.0.0a16 is the first published core with every API the adapter uses (AsyncWavePay).
+dependencies = [
+    "fastapi>=0.115",
+    "python-myanmar-payments>=4.0.0a16,<5",
+]
+
+[project.urls]
+Homepage = "https://github.com/laranex/python-myanmar-payments/tree/dev/adapters/fastapi"
+Documentation = "https://github.com/laranex/python-myanmar-payments/tree/dev/adapters/fastapi#readme"
+Repository = "https://github.com/laranex/python-myanmar-payments"
+Issues = "https://github.com/laranex/python-myanmar-payments/issues"
+Changelog = "https://github.com/laranex/python-myanmar-payments/blob/dev/adapters/fastapi/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "mypy>=1.13",
+    "pytest>=8.3",
+    "pytest-cov>=6.0",
+    "ruff>=0.8",
+]
+
+[tool.hatch.version]
+path = "src/fastapi_myanmar_payments/_version.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/skills",
+    "/CHANGELOG.md",
+    "/LICENSE.md",
+    "/README.md",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fastapi_myanmar_payments"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = ["--strict-markers", "--strict-config", "-ra"]
+xfail_strict = true
+filterwarnings = ["error"]
+
+[tool.coverage.run]
+branch = true
+source = ["fastapi_myanmar_payments"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+fail_under = 100
+exclude_also = ["if TYPE_CHECKING:"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src", "tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "UP", "SIM", "RUF", "C4", "PT", "PIE", "RET", "N"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["N802"]

fastapi_myanmar_payments-0.1.0.dev0/skills/fastapi-myanmar-payments/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: fastapi-myanmar-payments
+description: >
+  Wire Myanmar payment gateways (KBZ Pay, Wave Pay, AYA Pay, Yoma MMQR, CyberSource) into a FastAPI app with fastapi-myanmar-payments: lifespan, gateway dependencies, verified callbacks and gateway acknowledgements.
+license: MIT
+metadata:
+  author: Soe Thura
+---
+
+# FastAPI Myanmar Payments
+
+## When to use
+
+Use this skill when a FastAPI app takes payments with `python-myanmar-payments` and the project depends on `fastapi-myanmar-payments`. The adapter only connects FastAPI to the core SDK; payment data, amounts, gateway methods, statuses and errors are the core SDK's (see its `python-myanmar-payments` skill). Without the adapter, the core's async clients work in FastAPI directly.
+
+## Install
+
+```bash
+pip install fastapi-myanmar-payments
+```
+
+Requires Python 3.10+, FastAPI 0.115+ and `python-myanmar-payments` 4.0.0a16 or later (below 5). The core is a pre-release whose versions may break each other: pin both packages and upgrade them together. Import the adapter from `fastapi_myanmar_payments` and everything else from `python_myanmar_payments`.
+
+## Configure
+
+Create the facade once per app with `payments_lifespan`; never build gateways or HTTP clients per request.
+
+```python
+from fastapi import FastAPI
+from python_myanmar_payments import AsyncMyanmarPayments
+
+from fastapi_myanmar_payments import payments_lifespan
+
+app = FastAPI(lifespan=payments_lifespan(AsyncMyanmarPayments.from_env))
+```
+
+- A factory (`AsyncMyanmarPayments.from_env`, or a function returning `AsyncMyanmarPayments(kbz_pay={...}, ...)`) is created at startup and `aclose()`d at shutdown, which closes only the HTTP clients the core created. An instance you pass is never closed. An `http_client` or `token_cache` you give the facade is never closed by the adapter: close it yourself.
+- With your own lifespan, nest it: `async with payments_lifespan(factory)(app): yield`.
+- Settings and environment variables are the core's (`KBZ_PAY_*`, `WAVE_PAY_*`, ...). An unconfigured gateway raises the core `ConfigurationError`; a missing lifespan makes `get_payments` raise `RuntimeError`.
+
+## Use
+
+### Dependencies
+
+`PaymentsDep` (`AsyncMyanmarPayments`), `KbzPayDep` (`AsyncKbzPay`), `WavePayDep` (`AsyncWavePay`), `AyaPayDep` (`AsyncAyaPay`), `YomaMmqrDep` (`AsyncYomaMmqr`) and `CyberSourceDep` (`CyberSource`) are `Annotated` aliases of `get_payments`, `get_kbz_pay`, `get_wave_pay`, `get_aya_pay`, `get_yoma_mmqr` and `get_cyber_source`. Await the async gateways' methods:
+
+```python
+from fastapi_myanmar_payments import KbzPayDep
+
+
+@app.post("/orders/{order_id}/pay")
+async def pay(order_id: str, kbz: KbzPayDep):
+    payment = await kbz.pwa(data)  # data: the core's KbzPayPaymentData
+    return RedirectResponse(payment.url, status_code=303)
+```
+
+Never retry a failed payment initiation automatically; check the status or start a new attempt.
+
+### Handle the callback
+
+Verify, validate against the stored order, persist, acknowledge, then process once:
+
+```python
+from fastapi import Response
+
+from fastapi_myanmar_payments import (
+    CallbackRequestDep,
+    KbzPayDep,
+    acknowledgement_response,
+    verify_callback,
+)
+
+
+@app.post("/payments/kbz/callback")
+async def kbz_callback(kbz: KbzPayDep, request: CallbackRequestDep) -> Response:
+    callback = verify_callback(kbz, request)  # HTTPException(400) on a bad signature
+    order = await orders.get(callback.order_id)
+    await events.insert_once(callback, order_known=order is not None)  # durable, idempotent
+    return acknowledgement_response(callback.acknowledgement)
+```
+
+- `CallbackRequestDep` (or `await callback_request(request)`) passes the raw body bytes, headers and query string to the core. Never rebuild the body from `await request.json()` or `await request.form()`.
+- `verify_callback` calls the gateway's `handle_callback()` (sync or async clients, or `CyberSource`) and turns `SignatureVerificationError` into a generic 400 with the error chained as `__cause__`. Don't catch it to return 200.
+- `acknowledgement_response` returns the gateway's exact status, body and headers (KBZ Pay's plain `success`, an empty `text/plain` 200 for most). Never write your own acknowledgement.
+- Acknowledge only after the event is stored. If storing fails, let it raise a 5xx so the gateway retries.
+- An unknown order: store it as an unknown-order event, then acknowledge. Never create the order or mark it paid.
+- Not every gateway sends an amount (Yoma MMQR doesn't): compare `callback.amount` with the stored order when present, and fulfill only `callback.is_successful()` callbacks once, outside the request. FastAPI `BackgroundTasks` are lost on a crash.
+
+## Test your app
+
+- Override `app.dependency_overrides[get_payments]` with an `AsyncMyanmarPayments` whose `http_client` is `httpx.AsyncClient(transport=httpx.MockTransport(handler))`, or override one gateway, e.g. `app.dependency_overrides[get_kbz_pay]`.
+- Run the app in-process: `async with app.router.lifespan_context(app)` and `httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test")`.
+- Posted callbacks are still signature-checked; sign them with test secrets.
+
+## Avoid
+
+- Fulfilling orders from return pages or redirects.
+- Creating `AsyncMyanmarPayments` or gateways inside an endpoint.
+- Parsing and re-serializing callback bodies before verification.
+- Acknowledging before the callback is durably stored.
+- Adding signing, verification or status mapping to the app or the adapter: they belong to the core SDK.

fastapi_myanmar_payments-0.1.0.dev0/src/fastapi_myanmar_payments/__init__.py

@@ -0,0 +1,48 @@
+"""FastAPI integration for python-myanmar-payments.
+
+A lifespan that owns one ``AsyncMyanmarPayments``, dependencies for its gateways,
+raw callback requests, verification that answers bad signatures with a 400, and
+the gateway's acknowledgement as a response. Payments, signing and verification
+stay in ``python_myanmar_payments``.
+"""
+
+from ._version import __version__
+from .callbacks import CallbackHandler, CallbackRequestDep, callback_request, verify_callback
+from .dependencies import (
+    AyaPayDep,
+    CyberSourceDep,
+    KbzPayDep,
+    PaymentsDep,
+    WavePayDep,
+    YomaMmqrDep,
+    get_aya_pay,
+    get_cyber_source,
+    get_kbz_pay,
+    get_payments,
+    get_wave_pay,
+    get_yoma_mmqr,
+)
+from .lifespan import payments_lifespan
+from .responses import acknowledgement_response
+
+__all__ = [
+    "AyaPayDep",
+    "CallbackHandler",
+    "CallbackRequestDep",
+    "CyberSourceDep",
+    "KbzPayDep",
+    "PaymentsDep",
+    "WavePayDep",
+    "YomaMmqrDep",
+    "__version__",
+    "acknowledgement_response",
+    "callback_request",
+    "get_aya_pay",
+    "get_cyber_source",
+    "get_kbz_pay",
+    "get_payments",
+    "get_wave_pay",
+    "get_yoma_mmqr",
+    "payments_lifespan",
+    "verify_callback",
+]

fastapi_myanmar_payments-0.1.0.dev0/src/fastapi_myanmar_payments/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0.dev0"

fastapi_myanmar_payments-0.1.0.dev0/src/fastapi_myanmar_payments/callbacks.py

@@ -0,0 +1,47 @@
+"""Turns a FastAPI request into the core ``CallbackRequest`` and verifies it."""
+
+from __future__ import annotations
+
+from typing import Annotated, Protocol
+
+from fastapi import Depends, HTTPException, Request
+from python_myanmar_payments import CallbackRequest, PaymentCallback, SignatureVerificationError
+
+__all__ = ["CallbackHandler", "CallbackRequestDep", "callback_request", "verify_callback"]
+
+
+async def callback_request(request: Request) -> CallbackRequest:
+    """The request exactly as the gateway sent it: raw body bytes, headers and query string.
+
+    Nothing is parsed or re-encoded here, so JSON and form callbacks reach the
+    core's signature check byte for byte. Use it as a dependency
+    (:data:`CallbackRequestDep`) or await it in an endpoint.
+    """
+    return CallbackRequest(
+        body=await request.body(),
+        headers=request.headers,
+        query=request.scope["query_string"],
+    )
+
+
+CallbackRequestDep = Annotated[CallbackRequest, Depends(callback_request)]
+
+
+class CallbackHandler(Protocol):
+    """Any gateway that verifies callbacks: sync or async clients, or ``CyberSource``."""
+
+    def handle_callback(self, request: CallbackRequest) -> PaymentCallback: ...
+
+
+def verify_callback(gateway: CallbackHandler, request: CallbackRequest) -> PaymentCallback:
+    """Verifies a callback with the gateway's ``handle_callback()``.
+
+    A ``SignatureVerificationError`` (a bad signature or a malformed signed
+    callback) becomes an ``HTTPException(400)`` with a generic detail; the original
+    error is chained as ``__cause__`` and its unverified payload is never sent back.
+    Other errors propagate.
+    """
+    try:
+        return gateway.handle_callback(request)
+    except SignatureVerificationError as error:
+        raise HTTPException(status_code=400, detail="Callback verification failed.") from error

fastapi_myanmar_payments-0.1.0.dev0/src/fastapi_myanmar_payments/dependencies.py

@@ -0,0 +1,83 @@
+"""FastAPI dependencies that hand out the application's payments facade and gateways."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import Depends, Request
+from python_myanmar_payments import (
+    AsyncAyaPay,
+    AsyncKbzPay,
+    AsyncMyanmarPayments,
+    AsyncWavePay,
+    AsyncYomaMmqr,
+    CyberSource,
+)
+
+__all__ = [
+    "AyaPayDep",
+    "CyberSourceDep",
+    "KbzPayDep",
+    "PaymentsDep",
+    "WavePayDep",
+    "YomaMmqrDep",
+    "get_aya_pay",
+    "get_cyber_source",
+    "get_kbz_pay",
+    "get_payments",
+    "get_wave_pay",
+    "get_yoma_mmqr",
+]
+
+# The dependencies are `async def` so FastAPI runs them on the event loop rather
+# than in its thread pool, where two requests could build the same gateway twice.
+
+
+async def get_payments(request: Request) -> AsyncMyanmarPayments:
+    """The ``AsyncMyanmarPayments`` that :func:`payments_lifespan` stored on the app.
+
+    Override it with ``app.dependency_overrides[get_payments]`` in tests; the
+    gateway dependencies use it too.
+    """
+    payments = getattr(request.app.state, "myanmar_payments", None)
+    if not isinstance(payments, AsyncMyanmarPayments):
+        raise RuntimeError(
+            "No AsyncMyanmarPayments is configured for this app: pass "
+            "payments_lifespan(...) as the FastAPI lifespan or override get_payments."
+        )
+    return payments
+
+
+PaymentsDep = Annotated[AsyncMyanmarPayments, Depends(get_payments)]
+
+
+async def get_kbz_pay(payments: PaymentsDep) -> AsyncKbzPay:
+    """The KBZ Pay gateway. Raises the core ``ConfigurationError`` when not configured."""
+    return payments.kbz_pay()
+
+
+async def get_wave_pay(payments: PaymentsDep) -> AsyncWavePay:
+    """The Wave Pay gateway. Raises the core ``ConfigurationError`` when not configured."""
+    return payments.wave_pay()
+
+
+async def get_aya_pay(payments: PaymentsDep) -> AsyncAyaPay:
+    """The AYA Payment Gateway. Raises the core ``ConfigurationError`` when not configured."""
+    return payments.aya_pay()
+
+
+async def get_yoma_mmqr(payments: PaymentsDep) -> AsyncYomaMmqr:
+    """The Yoma MMQR gateway. Raises the core ``ConfigurationError`` when not configured."""
+    return payments.yoma_mmqr()
+
+
+async def get_cyber_source(payments: PaymentsDep) -> CyberSource:
+    """The CyberSource gateway. Raises the core ``ConfigurationError`` when not configured."""
+    return payments.cyber_source()
+
+
+KbzPayDep = Annotated[AsyncKbzPay, Depends(get_kbz_pay)]
+WavePayDep = Annotated[AsyncWavePay, Depends(get_wave_pay)]
+AyaPayDep = Annotated[AsyncAyaPay, Depends(get_aya_pay)]
+YomaMmqrDep = Annotated[AsyncYomaMmqr, Depends(get_yoma_mmqr)]
+CyberSourceDep = Annotated[CyberSource, Depends(get_cyber_source)]

fastapi_myanmar_payments-0.1.0.dev0/src/fastapi_myanmar_payments/lifespan.py

@@ -0,0 +1,44 @@
+"""Creates the payments facade once per application and closes what it created."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+
+from fastapi import FastAPI
+from python_myanmar_payments import AsyncMyanmarPayments
+
+__all__ = ["payments_lifespan"]
+
+
+def payments_lifespan(
+    payments: AsyncMyanmarPayments | Callable[[], AsyncMyanmarPayments],
+) -> Callable[[FastAPI], AbstractAsyncContextManager[None]]:
+    """A FastAPI lifespan that stores one ``AsyncMyanmarPayments`` on ``app.state``.
+
+    Pass a factory such as ``AsyncMyanmarPayments.from_env`` to let the lifespan
+    create the facade at startup and ``aclose()`` it at shutdown; that closes only
+    the HTTP clients the facade created, never an ``http_client`` or token cache
+    you gave it. Pass an instance to keep it under your control: it is never
+    closed.
+
+    .. code-block:: python
+
+        app = FastAPI(lifespan=payments_lifespan(AsyncMyanmarPayments.from_env))
+    """
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+        if isinstance(payments, AsyncMyanmarPayments):
+            instance, owned = payments, False
+        else:
+            instance, owned = payments(), True
+        app.state.myanmar_payments = instance
+        try:
+            yield
+        finally:
+            del app.state.myanmar_payments
+            if owned:
+                await instance.aclose()
+
+    return lifespan

fastapi_myanmar_payments-0.1.0.dev0/src/fastapi_myanmar_payments/responses.py

@@ -0,0 +1,21 @@
+"""Turns the core ``Acknowledgement`` into a Starlette response."""
+
+from __future__ import annotations
+
+from fastapi import Response
+from python_myanmar_payments import Acknowledgement
+
+__all__ = ["acknowledgement_response"]
+
+
+def acknowledgement_response(acknowledgement: Acknowledgement) -> Response:
+    """The response the gateway expects: its status, body and headers, unchanged.
+
+    No media type is added, so the ``Content-Type`` is exactly the gateway's
+    (e.g. ``text/plain`` without a charset).
+    """
+    return Response(
+        content=acknowledgement.body,
+        status_code=acknowledgement.status,
+        headers=dict(acknowledgement.headers),
+    )