bitmomo 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,16 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 — unreleased
4
+
5
+ First version of the Python SDK.
6
+
7
+ - `Client` and `AsyncClient` covering the merchant API: payments, payment
8
+ status, payment list, payouts, rates, balances, webhook settings and secret
9
+ rotation, and payment links.
10
+ - Webhook verification (`bitmomo.webhooks.verify_event`) with versioned
11
+ secrets, a freshness window and header cross-checks, plus an in-memory
12
+ delivery dedupe cache.
13
+ - Exact `Decimal` money, strict response checking, read retries on 429 and
14
+ 5xx, no automatic write retries, redirects refused.
15
+ - Verified against the shared BitMomo SDK fixtures used by the Node, Go and
16
+ Rust SDKs.
bitmomo-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Bitmomo contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
bitmomo-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,153 @@
1
+ Metadata-Version: 2.5
2
+ Name: bitmomo
3
+ Version: 0.1.0
4
+ Summary: BitMomo merchant SDK: accept crypto payments and verify webhooks in Python
5
+ Project-URL: Homepage, https://docs.bitmomo.app
6
+ Project-URL: Documentation, https://docs.bitmomo.app
7
+ Author: BitMomo
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: bitmomo,cedi,crypto,ghana,payments,stablecoin,webhooks
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3 :: Only
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Programming Language :: Python :: 3.14
21
+ Classifier: Topic :: Office/Business :: Financial
22
+ Classifier: Typing :: Typed
23
+ Requires-Python: >=3.10
24
+ Requires-Dist: httpx<1,>=0.27
25
+ Description-Content-Type: text/markdown
26
+
27
+ # BitMomo Python SDK
28
+
29
+ Accept crypto payments in your Python application and verify BitMomo webhooks.
30
+ Sync and async clients, exact `Decimal` money, and one dependency (`httpx`).
31
+
32
+ > **Test money only.** BitMomo currently runs on test networks. Live API keys
33
+ > are disabled, so nothing you do with this SDK moves real money.
34
+
35
+ Guides and the API reference: https://docs.bitmomo.app
36
+
37
+ ## Install
38
+
39
+ ```bash
40
+ pip install bitmomo
41
+ ```
42
+
43
+ Python 3.10 or newer.
44
+
45
+ ## Create a payment
46
+
47
+ ```python
48
+ import bitmomo
49
+
50
+ client = bitmomo.Client(
51
+ api_key=os.environ["BITMOMO_API_KEY"],
52
+ base_url="https://api.dev.bitmomo.app",
53
+ )
54
+
55
+ payment = client.create_payment(
56
+ amount="150.00", # GHS, as a string, int or Decimal; never a float
57
+ crypto_type="USDT_TRC20",
58
+ order_id="order-1001",
59
+ idempotency_key="order-1001", # reuse the same key if you retry
60
+ )
61
+ print(payment.deposit_address, payment.crypto_amount, payment.qr_code_data)
62
+ ```
63
+
64
+ Show the customer `qr_code_data` (or `deposit_address` and `crypto_amount`).
65
+ Then wait for the webhook, or poll:
66
+
67
+ ```python
68
+ status = client.get_payment_status(payment.id) # "pending", "confirmed", "completed", ...
69
+ detail = client.get_payment(payment.id) # economics, payout state, order terms
70
+ ```
71
+
72
+ ### Async
73
+
74
+ ```python
75
+ async with bitmomo.AsyncClient(api_key=key, base_url="https://api.dev.bitmomo.app") as client:
76
+ payment = await client.create_payment(amount="150.00", crypto_type="USDT_TRC20")
77
+ ```
78
+
79
+ ## Verify webhooks
80
+
81
+ Verify the **raw** request body, before parsing it. Keep both secrets during
82
+ the 24 hours after you rotate.
83
+
84
+ ```python
85
+ from bitmomo import webhooks
86
+
87
+ dedupe = webhooks.DeliveryDedupeCache()
88
+
89
+ def handle(request):
90
+ result = webhooks.verify_event(
91
+ request.body, # bytes, exactly as received
92
+ request.headers["X-Webhook-Signature"],
93
+ secrets=[webhooks.WebhookSecret(version=1, secret=WEBHOOK_SECRET)],
94
+ timestamp=request.headers.get("X-Webhook-Timestamp"),
95
+ key_version=request.headers.get("X-Webhook-Key-Version"),
96
+ )
97
+ if not result:
98
+ return 400 # result.reason says why
99
+ if dedupe.seen(result.envelope.delivery_id):
100
+ return 200 # already handled
101
+ event = json.loads(request.body)
102
+ ...
103
+ return 200
104
+ ```
105
+
106
+ Deliveries arrive at least once. The in-memory cache is enough for one
107
+ process; store processed `delivery_id`s durably if a duplicate would cause a
108
+ second effect (shipping twice, crediting twice).
109
+
110
+ ## Everything the client can do
111
+
112
+ | Method | API |
113
+ |---|---|
114
+ | `create_payment(...)` | `POST /api/v1/gateway/payments` |
115
+ | `get_payment(payment_id)` | `GET /api/v1/gateway/payments/{id}` |
116
+ | `get_payment_status(payment_id)` | `GET /api/v1/payments/{id}/status` |
117
+ | `list_payments(page=, limit=, status=)` | `GET /api/v1/gateway/payments` |
118
+ | `request_payout(amount=, idempotency_key=, settlement_method=)` | `POST /api/v1/gateway/payouts` |
119
+ | `get_rates()` | `GET /api/v1/rates` |
120
+ | `get_balances()` | `GET /api/v1/gateway/balances` |
121
+ | `get_webhook_config()` | `GET /api/v1/gateway/webhooks/config` |
122
+ | `update_webhook_config(url=, events=, is_active=)` | `PUT /api/v1/gateway/webhooks/config` |
123
+ | `rotate_webhook_secret()` | `POST /api/v1/gateway/webhooks/config/rotate` |
124
+ | `delete_webhook_config()` | `DELETE /api/v1/gateway/webhooks/config` |
125
+ | `create_payment_link(name=, ...)` | `POST /api/v1/gateway/payment-links` |
126
+ | `list_payment_links()` | `GET /api/v1/gateway/payment-links` |
127
+ | `get_payment_link(link_id)` | `GET /api/v1/gateway/payment-links/{id}` |
128
+
129
+ Each API key carries scopes. A key without the right scope gets a
130
+ `BitmomoError` with status 403.
131
+
132
+ ## Errors and retries
133
+
134
+ Every failure raises `bitmomo.BitmomoError` with `status`, `code`, `message`,
135
+ `request_id` and `retriable`. `status` is 0 when no response arrived
136
+ (`NETWORK_ERROR`) or the response broke the contract (`SCHEMA_ERROR`).
137
+
138
+ - Reads retry automatically on 429 and 5xx, twice by default (`max_retries=`),
139
+ honouring `Retry-After` up to 60 seconds.
140
+ - Writes are never retried for you. Retry them yourself with the same
141
+ idempotency key; `request_payout` refuses to send without one.
142
+ - Redirects are refused, so your API key is never sent to another host.
143
+ - `base_url` must be an HTTPS origin (plain HTTP only for localhost).
144
+
145
+ ## Money
146
+
147
+ Money fields are `decimal.Decimal`. Use `format(value, "f")` to print them
148
+ without scientific notation. Amounts you send may be `Decimal`, `int` or a
149
+ decimal string; floats are refused because they cannot hold cents exactly.
150
+
151
+ ## License
152
+
153
+ MIT
@@ -0,0 +1,127 @@
1
+ # BitMomo Python SDK
2
+
3
+ Accept crypto payments in your Python application and verify BitMomo webhooks.
4
+ Sync and async clients, exact `Decimal` money, and one dependency (`httpx`).
5
+
6
+ > **Test money only.** BitMomo currently runs on test networks. Live API keys
7
+ > are disabled, so nothing you do with this SDK moves real money.
8
+
9
+ Guides and the API reference: https://docs.bitmomo.app
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ pip install bitmomo
15
+ ```
16
+
17
+ Python 3.10 or newer.
18
+
19
+ ## Create a payment
20
+
21
+ ```python
22
+ import bitmomo
23
+
24
+ client = bitmomo.Client(
25
+ api_key=os.environ["BITMOMO_API_KEY"],
26
+ base_url="https://api.dev.bitmomo.app",
27
+ )
28
+
29
+ payment = client.create_payment(
30
+ amount="150.00", # GHS, as a string, int or Decimal; never a float
31
+ crypto_type="USDT_TRC20",
32
+ order_id="order-1001",
33
+ idempotency_key="order-1001", # reuse the same key if you retry
34
+ )
35
+ print(payment.deposit_address, payment.crypto_amount, payment.qr_code_data)
36
+ ```
37
+
38
+ Show the customer `qr_code_data` (or `deposit_address` and `crypto_amount`).
39
+ Then wait for the webhook, or poll:
40
+
41
+ ```python
42
+ status = client.get_payment_status(payment.id) # "pending", "confirmed", "completed", ...
43
+ detail = client.get_payment(payment.id) # economics, payout state, order terms
44
+ ```
45
+
46
+ ### Async
47
+
48
+ ```python
49
+ async with bitmomo.AsyncClient(api_key=key, base_url="https://api.dev.bitmomo.app") as client:
50
+ payment = await client.create_payment(amount="150.00", crypto_type="USDT_TRC20")
51
+ ```
52
+
53
+ ## Verify webhooks
54
+
55
+ Verify the **raw** request body, before parsing it. Keep both secrets during
56
+ the 24 hours after you rotate.
57
+
58
+ ```python
59
+ from bitmomo import webhooks
60
+
61
+ dedupe = webhooks.DeliveryDedupeCache()
62
+
63
+ def handle(request):
64
+ result = webhooks.verify_event(
65
+ request.body, # bytes, exactly as received
66
+ request.headers["X-Webhook-Signature"],
67
+ secrets=[webhooks.WebhookSecret(version=1, secret=WEBHOOK_SECRET)],
68
+ timestamp=request.headers.get("X-Webhook-Timestamp"),
69
+ key_version=request.headers.get("X-Webhook-Key-Version"),
70
+ )
71
+ if not result:
72
+ return 400 # result.reason says why
73
+ if dedupe.seen(result.envelope.delivery_id):
74
+ return 200 # already handled
75
+ event = json.loads(request.body)
76
+ ...
77
+ return 200
78
+ ```
79
+
80
+ Deliveries arrive at least once. The in-memory cache is enough for one
81
+ process; store processed `delivery_id`s durably if a duplicate would cause a
82
+ second effect (shipping twice, crediting twice).
83
+
84
+ ## Everything the client can do
85
+
86
+ | Method | API |
87
+ |---|---|
88
+ | `create_payment(...)` | `POST /api/v1/gateway/payments` |
89
+ | `get_payment(payment_id)` | `GET /api/v1/gateway/payments/{id}` |
90
+ | `get_payment_status(payment_id)` | `GET /api/v1/payments/{id}/status` |
91
+ | `list_payments(page=, limit=, status=)` | `GET /api/v1/gateway/payments` |
92
+ | `request_payout(amount=, idempotency_key=, settlement_method=)` | `POST /api/v1/gateway/payouts` |
93
+ | `get_rates()` | `GET /api/v1/rates` |
94
+ | `get_balances()` | `GET /api/v1/gateway/balances` |
95
+ | `get_webhook_config()` | `GET /api/v1/gateway/webhooks/config` |
96
+ | `update_webhook_config(url=, events=, is_active=)` | `PUT /api/v1/gateway/webhooks/config` |
97
+ | `rotate_webhook_secret()` | `POST /api/v1/gateway/webhooks/config/rotate` |
98
+ | `delete_webhook_config()` | `DELETE /api/v1/gateway/webhooks/config` |
99
+ | `create_payment_link(name=, ...)` | `POST /api/v1/gateway/payment-links` |
100
+ | `list_payment_links()` | `GET /api/v1/gateway/payment-links` |
101
+ | `get_payment_link(link_id)` | `GET /api/v1/gateway/payment-links/{id}` |
102
+
103
+ Each API key carries scopes. A key without the right scope gets a
104
+ `BitmomoError` with status 403.
105
+
106
+ ## Errors and retries
107
+
108
+ Every failure raises `bitmomo.BitmomoError` with `status`, `code`, `message`,
109
+ `request_id` and `retriable`. `status` is 0 when no response arrived
110
+ (`NETWORK_ERROR`) or the response broke the contract (`SCHEMA_ERROR`).
111
+
112
+ - Reads retry automatically on 429 and 5xx, twice by default (`max_retries=`),
113
+ honouring `Retry-After` up to 60 seconds.
114
+ - Writes are never retried for you. Retry them yourself with the same
115
+ idempotency key; `request_payout` refuses to send without one.
116
+ - Redirects are refused, so your API key is never sent to another host.
117
+ - `base_url` must be an HTTPS origin (plain HTTP only for localhost).
118
+
119
+ ## Money
120
+
121
+ Money fields are `decimal.Decimal`. Use `format(value, "f")` to print them
122
+ without scientific notation. Amounts you send may be `Decimal`, `int` or a
123
+ decimal string; floats are refused because they cannot hold cents exactly.
124
+
125
+ ## License
126
+
127
+ MIT
@@ -0,0 +1,39 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.27"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "bitmomo"
7
+ version = "0.1.0"
8
+ description = "BitMomo merchant SDK: accept crypto payments and verify webhooks in Python"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "BitMomo" }]
14
+ keywords = ["bitmomo", "payments", "crypto", "stablecoin", "webhooks", "ghana", "cedi"]
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Intended Audience :: Developers",
18
+ "Operating System :: OS Independent",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3 :: Only",
21
+ "Programming Language :: Python :: 3.10",
22
+ "Programming Language :: Python :: 3.11",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ "Programming Language :: Python :: 3.14",
26
+ "Topic :: Office/Business :: Financial",
27
+ "Typing :: Typed",
28
+ ]
29
+ dependencies = ["httpx>=0.27,<1"]
30
+
31
+ [project.urls]
32
+ Homepage = "https://docs.bitmomo.app"
33
+ Documentation = "https://docs.bitmomo.app"
34
+
35
+ [tool.hatch.build.targets.wheel]
36
+ packages = ["src/bitmomo"]
37
+
38
+ [tool.hatch.build.targets.sdist]
39
+ include = ["src/bitmomo", "tests", "README.md", "CHANGELOG.md", "LICENSE"]
@@ -0,0 +1,78 @@
1
+ """BitMomo merchant SDK: accept crypto payments and verify webhooks from Python.
2
+
3
+ import bitmomo
4
+
5
+ client = bitmomo.Client(api_key="cp_...", base_url="https://api.dev.bitmomo.app")
6
+ payment = client.create_payment(amount="150.00", crypto_type="USDT_TRC20",
7
+ idempotency_key="order-1001")
8
+
9
+ Guides: https://docs.bitmomo.app
10
+ """
11
+ from . import webhooks
12
+ from ._client import AsyncClient, Client, Money, new_idempotency_key
13
+ from ._errors import BitmomoError
14
+ from ._models import (
15
+ PAYMENT_STATUSES,
16
+ AssetBalance,
17
+ Balances,
18
+ CreatedPayment,
19
+ ExchangeRate,
20
+ Payment,
21
+ PaymentEconomics,
22
+ PaymentLink,
23
+ PaymentList,
24
+ PaymentOrderTerms,
25
+ PaymentPricingTerms,
26
+ PaymentSummary,
27
+ PayoutResponse,
28
+ PayoutView,
29
+ RotatedWebhookSecret,
30
+ UnallocatedBucket,
31
+ UnallocatedBuckets,
32
+ WebhookConfig,
33
+ WebhookEndpoint,
34
+ )
35
+ from ._version import __version__
36
+ from .webhooks import (
37
+ DeliveryDedupeCache,
38
+ VerificationResult,
39
+ WebhookEnvelope,
40
+ WebhookSecret,
41
+ verify_event as verify_webhook_event,
42
+ verify_signature as verify_webhook_signature,
43
+ )
44
+
45
+ __all__ = [
46
+ "PAYMENT_STATUSES",
47
+ "AssetBalance",
48
+ "AsyncClient",
49
+ "Balances",
50
+ "BitmomoError",
51
+ "Client",
52
+ "CreatedPayment",
53
+ "DeliveryDedupeCache",
54
+ "ExchangeRate",
55
+ "Money",
56
+ "Payment",
57
+ "PaymentEconomics",
58
+ "PaymentLink",
59
+ "PaymentList",
60
+ "PaymentOrderTerms",
61
+ "PaymentPricingTerms",
62
+ "PaymentSummary",
63
+ "PayoutResponse",
64
+ "PayoutView",
65
+ "RotatedWebhookSecret",
66
+ "UnallocatedBucket",
67
+ "UnallocatedBuckets",
68
+ "VerificationResult",
69
+ "WebhookConfig",
70
+ "WebhookEndpoint",
71
+ "WebhookEnvelope",
72
+ "WebhookSecret",
73
+ "__version__",
74
+ "new_idempotency_key",
75
+ "verify_webhook_event",
76
+ "verify_webhook_signature",
77
+ "webhooks",
78
+ ]