barkapay-payhub 1.0.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.
- barkapay_payhub-1.0.0/.gitignore +20 -0
- barkapay_payhub-1.0.0/CHANGELOG.md +16 -0
- barkapay_payhub-1.0.0/LICENSE +21 -0
- barkapay_payhub-1.0.0/PKG-INFO +180 -0
- barkapay_payhub-1.0.0/README.md +148 -0
- barkapay_payhub-1.0.0/examples/balance.py +29 -0
- barkapay_payhub-1.0.0/examples/collect.py +33 -0
- barkapay_payhub-1.0.0/examples/disburse.py +32 -0
- barkapay_payhub-1.0.0/examples/webhook.py +39 -0
- barkapay_payhub-1.0.0/pyproject.toml +90 -0
- barkapay_payhub-1.0.0/src/payhub/__init__.py +81 -0
- barkapay_payhub-1.0.0/src/payhub/_util.py +74 -0
- barkapay_payhub-1.0.0/src/payhub/_version.py +3 -0
- barkapay_payhub-1.0.0/src/payhub/client.py +203 -0
- barkapay_payhub-1.0.0/src/payhub/enums.py +57 -0
- barkapay_payhub-1.0.0/src/payhub/errors.py +143 -0
- barkapay_payhub-1.0.0/src/payhub/http.py +87 -0
- barkapay_payhub-1.0.0/src/payhub/models.py +179 -0
- barkapay_payhub-1.0.0/src/payhub/py.typed +0 -0
- barkapay_payhub-1.0.0/src/payhub/resources.py +143 -0
- barkapay_payhub-1.0.0/src/payhub/webhook.py +99 -0
- barkapay_payhub-1.0.0/tests/__init__.py +0 -0
- barkapay_payhub-1.0.0/tests/support.py +34 -0
- barkapay_payhub-1.0.0/tests/test_client.py +227 -0
- barkapay_payhub-1.0.0/tests/test_error_mapping.py +103 -0
- barkapay_payhub-1.0.0/tests/test_models.py +62 -0
- barkapay_payhub-1.0.0/tests/test_webhook.py +70 -0
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project are documented here. This project follows
|
|
4
|
+
[Semantic Versioning](https://semver.org/).
|
|
5
|
+
|
|
6
|
+
## [Unreleased]
|
|
7
|
+
|
|
8
|
+
### Added
|
|
9
|
+
- Initial Python SDK: `PayHub` client with `payments`, `transfers`, `balance`,
|
|
10
|
+
`operators` resources plus `ping()` / `me()`.
|
|
11
|
+
- Typed data objects (`Payment`, `Transfer`, `Balance`, `Pagination`) and status
|
|
12
|
+
enums (`PaymentStatus`, `TransferStatus`).
|
|
13
|
+
- Webhook signature verification (`payhub.webhook.verify` / `parse`).
|
|
14
|
+
- Typed exception hierarchy mapped from the API error envelope.
|
|
15
|
+
- Zero-dependency `urllib` transport with automatic retries on 429/503/network,
|
|
16
|
+
and an injectable `Transport` for tests.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 BarkaPay (PayHub)
|
|
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.
|
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: barkapay-payhub
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Official Python client for the PayHub payments API — mobile money & crypto, one API across countries. Import as `payhub`.
|
|
5
|
+
Project-URL: Homepage, https://payhub.africa/developers
|
|
6
|
+
Project-URL: Documentation, https://github.com/BarkaPay/payhub-python#readme
|
|
7
|
+
Project-URL: Source, https://github.com/BarkaPay/payhub-python
|
|
8
|
+
Project-URL: Changelog, https://github.com/BarkaPay/payhub-python/blob/main/CHANGELOG.md
|
|
9
|
+
Project-URL: Issues, https://github.com/BarkaPay/payhub-python/issues
|
|
10
|
+
Author-email: "BarkaPay (PayHub)" <developers@payhub.africa>
|
|
11
|
+
License-Expression: MIT
|
|
12
|
+
License-File: LICENSE
|
|
13
|
+
Keywords: africa,barkapay,fintech,mobile-money,payhub,payments
|
|
14
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
24
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
25
|
+
Classifier: Typing :: Typed
|
|
26
|
+
Requires-Python: >=3.9
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: mypy>=1.8; extra == 'dev'
|
|
29
|
+
Requires-Dist: pytest>=7.4; extra == 'dev'
|
|
30
|
+
Requires-Dist: ruff>=0.4; extra == 'dev'
|
|
31
|
+
Description-Content-Type: text/markdown
|
|
32
|
+
|
|
33
|
+
# PayHub Python SDK
|
|
34
|
+
|
|
35
|
+
Official Python client for the [PayHub](https://payhub.africa/developers) payments API —
|
|
36
|
+
mobile money & crypto, one API across countries.
|
|
37
|
+
|
|
38
|
+
- **Zero runtime dependencies** — pure standard library (`urllib`, `hmac`, `json`).
|
|
39
|
+
- Typed payments, transfers and balance objects (frozen dataclasses, `py.typed`).
|
|
40
|
+
- Built-in webhook signature verification.
|
|
41
|
+
- Automatic retries on transient errors (429 / 503 / network).
|
|
42
|
+
|
|
43
|
+
## Requirements
|
|
44
|
+
|
|
45
|
+
Python **3.9+**.
|
|
46
|
+
|
|
47
|
+
## Install
|
|
48
|
+
|
|
49
|
+
```bash
|
|
50
|
+
pip install barkapay-payhub
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
The distribution is `barkapay-payhub`; you import it as `payhub`.
|
|
54
|
+
|
|
55
|
+
## Quick start
|
|
56
|
+
|
|
57
|
+
```python
|
|
58
|
+
import payhub
|
|
59
|
+
|
|
60
|
+
client = payhub.PayHub(
|
|
61
|
+
api_key="pk_live_xxx:sk_live_yyy", # the "key_id:secret" you copy from the dashboard
|
|
62
|
+
country="bf", # default country, overridable per call
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
payment = client.payments.create({
|
|
66
|
+
"operator": "ORANGE",
|
|
67
|
+
"phone_number": "50123456789",
|
|
68
|
+
"amount": 10000,
|
|
69
|
+
"otp": "123456", # only for synchronous-OTP operators (e.g. Orange)
|
|
70
|
+
"order": {"id": "ORDER-2026-001"},
|
|
71
|
+
})
|
|
72
|
+
|
|
73
|
+
print(payment.public_id, payment.status)
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
> **Authentication:** pass the raw `key_id:secret` (or `key_id` + `secret` separately).
|
|
77
|
+
> The SDK adds the `Bearer` prefix — never include the word `Bearer` yourself
|
|
78
|
+
> (an accidental one is forgiven).
|
|
79
|
+
|
|
80
|
+
## Payments
|
|
81
|
+
|
|
82
|
+
```python
|
|
83
|
+
client.payments.create({...}) # -> payhub.Payment
|
|
84
|
+
client.payments.get("pay_… or order_id") # by public_id or your order_id
|
|
85
|
+
client.payments.list({"status": "SUCCESSFUL", "per_page": 50}) # -> PaymentList (.items, .meta)
|
|
86
|
+
client.payments.confirm_otp(public_id, "123456") # for AWAITING_OTP payments
|
|
87
|
+
client.payments.resend_otp(public_id)
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
The flow depends on the operator — always branch on the returned `status`:
|
|
91
|
+
synchronous (`SUCCESSFUL`/`FAILED`), `AWAITING_OTP` (confirm step), or
|
|
92
|
+
`PROCESSING_OPERATOR` (final outcome arrives by webhook).
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
from payhub import PaymentStatus
|
|
96
|
+
|
|
97
|
+
if payment.status is PaymentStatus.AWAITING_OTP:
|
|
98
|
+
payment = client.payments.confirm_otp(payment.public_id, otp)
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
## Transfers
|
|
102
|
+
|
|
103
|
+
```python
|
|
104
|
+
client.transfers.create({
|
|
105
|
+
"operator": "ORANGE",
|
|
106
|
+
"phone_number": "50123456789",
|
|
107
|
+
"amount": 50000,
|
|
108
|
+
"order": {"id": "XFER-2026-001"},
|
|
109
|
+
})
|
|
110
|
+
client.transfers.get(transfer_id)
|
|
111
|
+
client.transfers.list({"from_date": "2026-06-01"}) # -> TransferList
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Balance & operators
|
|
115
|
+
|
|
116
|
+
```python
|
|
117
|
+
balance = client.balance.get() # payhub.Balance: available / total / holds / currency
|
|
118
|
+
client.operators.info() # authoritative operator list for the country
|
|
119
|
+
client.operators.availability()
|
|
120
|
+
client.me()
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## Webhooks
|
|
124
|
+
|
|
125
|
+
Verify the `PayHub-Signature` header against the **raw** request body:
|
|
126
|
+
|
|
127
|
+
```python
|
|
128
|
+
from payhub import webhook
|
|
129
|
+
from payhub import SignatureVerificationError
|
|
130
|
+
|
|
131
|
+
try:
|
|
132
|
+
event = webhook.parse(
|
|
133
|
+
raw_body, # bytes or str — the RAW body
|
|
134
|
+
request.headers["PayHub-Signature"],
|
|
135
|
+
endpoint_secret, # whsec_…
|
|
136
|
+
)
|
|
137
|
+
except SignatureVerificationError:
|
|
138
|
+
return Response(status=400)
|
|
139
|
+
|
|
140
|
+
# No `event` field — derive it from event["type"] + event["status"].
|
|
141
|
+
# Deduplicate on event["public_id"] (retries deliver the same body).
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
`webhook.verify(...)` returns a `bool` if you prefer not to catch.
|
|
145
|
+
|
|
146
|
+
## Errors
|
|
147
|
+
|
|
148
|
+
Every API error raises a typed exception extending `payhub.ApiError`
|
|
149
|
+
(`.code`, `.http_status`, `.request_id`, `.errors`):
|
|
150
|
+
|
|
151
|
+
| Exception | When |
|
|
152
|
+
|---|---|
|
|
153
|
+
| `AuthenticationError` | 401 — bad credentials |
|
|
154
|
+
| `AuthorizationError` | 403/410/451 — not allowed |
|
|
155
|
+
| `ValidationError` | 422 — bad request (`.errors`) |
|
|
156
|
+
| `NotFoundError` | 404 |
|
|
157
|
+
| `ConflictError` | 409 — duplicate |
|
|
158
|
+
| `RateLimitError` | 429 |
|
|
159
|
+
| `ServiceUnavailableError` | 503 — retryable |
|
|
160
|
+
| `ServerError` | 5xx |
|
|
161
|
+
| `NetworkError` | request never reached a response |
|
|
162
|
+
|
|
163
|
+
Catch everything from the SDK with `payhub.PayHubError`.
|
|
164
|
+
|
|
165
|
+
## Configuration
|
|
166
|
+
|
|
167
|
+
```python
|
|
168
|
+
payhub.PayHub(
|
|
169
|
+
api_key="key_id:secret",
|
|
170
|
+
country="bf",
|
|
171
|
+
base_url="https://hub.barkapay.com",
|
|
172
|
+
max_retries=2, # 429/503/network
|
|
173
|
+
timeout=30.0, # seconds
|
|
174
|
+
transport=custom, # any callable matching payhub.Transport (great for tests)
|
|
175
|
+
)
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
## License
|
|
179
|
+
|
|
180
|
+
MIT.
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
# PayHub Python SDK
|
|
2
|
+
|
|
3
|
+
Official Python client for the [PayHub](https://payhub.africa/developers) payments API —
|
|
4
|
+
mobile money & crypto, one API across countries.
|
|
5
|
+
|
|
6
|
+
- **Zero runtime dependencies** — pure standard library (`urllib`, `hmac`, `json`).
|
|
7
|
+
- Typed payments, transfers and balance objects (frozen dataclasses, `py.typed`).
|
|
8
|
+
- Built-in webhook signature verification.
|
|
9
|
+
- Automatic retries on transient errors (429 / 503 / network).
|
|
10
|
+
|
|
11
|
+
## Requirements
|
|
12
|
+
|
|
13
|
+
Python **3.9+**.
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
pip install barkapay-payhub
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
The distribution is `barkapay-payhub`; you import it as `payhub`.
|
|
22
|
+
|
|
23
|
+
## Quick start
|
|
24
|
+
|
|
25
|
+
```python
|
|
26
|
+
import payhub
|
|
27
|
+
|
|
28
|
+
client = payhub.PayHub(
|
|
29
|
+
api_key="pk_live_xxx:sk_live_yyy", # the "key_id:secret" you copy from the dashboard
|
|
30
|
+
country="bf", # default country, overridable per call
|
|
31
|
+
)
|
|
32
|
+
|
|
33
|
+
payment = client.payments.create({
|
|
34
|
+
"operator": "ORANGE",
|
|
35
|
+
"phone_number": "50123456789",
|
|
36
|
+
"amount": 10000,
|
|
37
|
+
"otp": "123456", # only for synchronous-OTP operators (e.g. Orange)
|
|
38
|
+
"order": {"id": "ORDER-2026-001"},
|
|
39
|
+
})
|
|
40
|
+
|
|
41
|
+
print(payment.public_id, payment.status)
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
> **Authentication:** pass the raw `key_id:secret` (or `key_id` + `secret` separately).
|
|
45
|
+
> The SDK adds the `Bearer` prefix — never include the word `Bearer` yourself
|
|
46
|
+
> (an accidental one is forgiven).
|
|
47
|
+
|
|
48
|
+
## Payments
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
client.payments.create({...}) # -> payhub.Payment
|
|
52
|
+
client.payments.get("pay_… or order_id") # by public_id or your order_id
|
|
53
|
+
client.payments.list({"status": "SUCCESSFUL", "per_page": 50}) # -> PaymentList (.items, .meta)
|
|
54
|
+
client.payments.confirm_otp(public_id, "123456") # for AWAITING_OTP payments
|
|
55
|
+
client.payments.resend_otp(public_id)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The flow depends on the operator — always branch on the returned `status`:
|
|
59
|
+
synchronous (`SUCCESSFUL`/`FAILED`), `AWAITING_OTP` (confirm step), or
|
|
60
|
+
`PROCESSING_OPERATOR` (final outcome arrives by webhook).
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
from payhub import PaymentStatus
|
|
64
|
+
|
|
65
|
+
if payment.status is PaymentStatus.AWAITING_OTP:
|
|
66
|
+
payment = client.payments.confirm_otp(payment.public_id, otp)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
## Transfers
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
client.transfers.create({
|
|
73
|
+
"operator": "ORANGE",
|
|
74
|
+
"phone_number": "50123456789",
|
|
75
|
+
"amount": 50000,
|
|
76
|
+
"order": {"id": "XFER-2026-001"},
|
|
77
|
+
})
|
|
78
|
+
client.transfers.get(transfer_id)
|
|
79
|
+
client.transfers.list({"from_date": "2026-06-01"}) # -> TransferList
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Balance & operators
|
|
83
|
+
|
|
84
|
+
```python
|
|
85
|
+
balance = client.balance.get() # payhub.Balance: available / total / holds / currency
|
|
86
|
+
client.operators.info() # authoritative operator list for the country
|
|
87
|
+
client.operators.availability()
|
|
88
|
+
client.me()
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## Webhooks
|
|
92
|
+
|
|
93
|
+
Verify the `PayHub-Signature` header against the **raw** request body:
|
|
94
|
+
|
|
95
|
+
```python
|
|
96
|
+
from payhub import webhook
|
|
97
|
+
from payhub import SignatureVerificationError
|
|
98
|
+
|
|
99
|
+
try:
|
|
100
|
+
event = webhook.parse(
|
|
101
|
+
raw_body, # bytes or str — the RAW body
|
|
102
|
+
request.headers["PayHub-Signature"],
|
|
103
|
+
endpoint_secret, # whsec_…
|
|
104
|
+
)
|
|
105
|
+
except SignatureVerificationError:
|
|
106
|
+
return Response(status=400)
|
|
107
|
+
|
|
108
|
+
# No `event` field — derive it from event["type"] + event["status"].
|
|
109
|
+
# Deduplicate on event["public_id"] (retries deliver the same body).
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
`webhook.verify(...)` returns a `bool` if you prefer not to catch.
|
|
113
|
+
|
|
114
|
+
## Errors
|
|
115
|
+
|
|
116
|
+
Every API error raises a typed exception extending `payhub.ApiError`
|
|
117
|
+
(`.code`, `.http_status`, `.request_id`, `.errors`):
|
|
118
|
+
|
|
119
|
+
| Exception | When |
|
|
120
|
+
|---|---|
|
|
121
|
+
| `AuthenticationError` | 401 — bad credentials |
|
|
122
|
+
| `AuthorizationError` | 403/410/451 — not allowed |
|
|
123
|
+
| `ValidationError` | 422 — bad request (`.errors`) |
|
|
124
|
+
| `NotFoundError` | 404 |
|
|
125
|
+
| `ConflictError` | 409 — duplicate |
|
|
126
|
+
| `RateLimitError` | 429 |
|
|
127
|
+
| `ServiceUnavailableError` | 503 — retryable |
|
|
128
|
+
| `ServerError` | 5xx |
|
|
129
|
+
| `NetworkError` | request never reached a response |
|
|
130
|
+
|
|
131
|
+
Catch everything from the SDK with `payhub.PayHubError`.
|
|
132
|
+
|
|
133
|
+
## Configuration
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
payhub.PayHub(
|
|
137
|
+
api_key="key_id:secret",
|
|
138
|
+
country="bf",
|
|
139
|
+
base_url="https://hub.barkapay.com",
|
|
140
|
+
max_retries=2, # 429/503/network
|
|
141
|
+
timeout=30.0, # seconds
|
|
142
|
+
transport=custom, # any callable matching payhub.Transport (great for tests)
|
|
143
|
+
)
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
## License
|
|
147
|
+
|
|
148
|
+
MIT.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"""Read the merchant wallet balance. Run: PAYHUB_API_KEY=... python examples/balance.py"""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
import sys
|
|
7
|
+
|
|
8
|
+
import payhub
|
|
9
|
+
from payhub import PayHubError
|
|
10
|
+
|
|
11
|
+
client = payhub.PayHub(
|
|
12
|
+
api_key=os.environ.get("PAYHUB_API_KEY", "pk_live_xxx:sk_live_yyy"),
|
|
13
|
+
country="bf",
|
|
14
|
+
)
|
|
15
|
+
|
|
16
|
+
try:
|
|
17
|
+
balance = client.balance.get()
|
|
18
|
+
|
|
19
|
+
if balance.balances is not None:
|
|
20
|
+
# Crypto (cc): one entry per asset/network.
|
|
21
|
+
for entry in balance.balances:
|
|
22
|
+
asset = entry.get("asset", "?")
|
|
23
|
+
network = entry.get("network", "?")
|
|
24
|
+
available = entry.get("available", "0")
|
|
25
|
+
print(f"{asset}/{network}: {available}")
|
|
26
|
+
else:
|
|
27
|
+
print(f"Available: {balance.available or '0'} {balance.currency or ''}")
|
|
28
|
+
except PayHubError as exc:
|
|
29
|
+
print(f"PayHub error: {exc}", file=sys.stderr)
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""Collect a payment (mobile money). Run: PAYHUB_API_KEY=... python examples/collect.py"""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
import sys
|
|
7
|
+
import time
|
|
8
|
+
|
|
9
|
+
import payhub
|
|
10
|
+
from payhub import PayHubError
|
|
11
|
+
|
|
12
|
+
client = payhub.PayHub(
|
|
13
|
+
api_key=os.environ.get("PAYHUB_API_KEY", "pk_live_xxx:sk_live_yyy"),
|
|
14
|
+
country="bf",
|
|
15
|
+
)
|
|
16
|
+
|
|
17
|
+
try:
|
|
18
|
+
# The OTP field is only needed for synchronous-OTP operators (e.g. Orange);
|
|
19
|
+
# most async operators (MTN, Wave) return PROCESSING_OPERATOR and complete
|
|
20
|
+
# via webhook. Always branch on the returned status.
|
|
21
|
+
payment = client.payments.create(
|
|
22
|
+
{
|
|
23
|
+
"operator": "ORANGE",
|
|
24
|
+
"phone_number": "50123456789",
|
|
25
|
+
"amount": 10000,
|
|
26
|
+
"otp": "123456",
|
|
27
|
+
"order": {"id": f"ORDER-{int(time.time())}"},
|
|
28
|
+
}
|
|
29
|
+
)
|
|
30
|
+
status = payment.status.value if payment.status else "unknown"
|
|
31
|
+
print(f"Payment {payment.public_id} — status {status}")
|
|
32
|
+
except PayHubError as exc:
|
|
33
|
+
print(f"PayHub error: {exc}", file=sys.stderr)
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
"""Disburse a transfer (payout). Run: PAYHUB_API_KEY=... python examples/disburse.py"""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import os
|
|
6
|
+
import sys
|
|
7
|
+
import time
|
|
8
|
+
|
|
9
|
+
import payhub
|
|
10
|
+
from payhub import ConflictError, PayHubError
|
|
11
|
+
|
|
12
|
+
client = payhub.PayHub(
|
|
13
|
+
api_key=os.environ.get("PAYHUB_API_KEY", "pk_live_xxx:sk_live_yyy"),
|
|
14
|
+
country="bf",
|
|
15
|
+
)
|
|
16
|
+
|
|
17
|
+
try:
|
|
18
|
+
transfer = client.transfers.create(
|
|
19
|
+
{
|
|
20
|
+
"operator": "ORANGE",
|
|
21
|
+
"phone_number": "50123456789",
|
|
22
|
+
"amount": 50000,
|
|
23
|
+
"order": {"id": f"XFER-{int(time.time())}"},
|
|
24
|
+
}
|
|
25
|
+
)
|
|
26
|
+
status = transfer.status.value if transfer.status else "unknown"
|
|
27
|
+
print(f"Transfer {transfer.public_id} — status {status}")
|
|
28
|
+
except ConflictError as exc:
|
|
29
|
+
# The 60s duplicate guard fired — a near-identical transfer is already in flight.
|
|
30
|
+
print(f"Duplicate transfer: {exc}", file=sys.stderr)
|
|
31
|
+
except PayHubError as exc:
|
|
32
|
+
print(f"PayHub error: {exc}", file=sys.stderr)
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
"""Minimal webhook receiver (Flask). Mount it at your registered endpoint URL.
|
|
2
|
+
|
|
3
|
+
Run: PAYHUB_WEBHOOK_SECRET=whsec_... flask --app examples/webhook run
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import os
|
|
9
|
+
|
|
10
|
+
from flask import Flask, Response, request # type: ignore[import-not-found]
|
|
11
|
+
|
|
12
|
+
from payhub import SignatureVerificationError, webhook
|
|
13
|
+
|
|
14
|
+
app = Flask(__name__)
|
|
15
|
+
SECRET = os.environ.get("PAYHUB_WEBHOOK_SECRET", "whsec_xxx")
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
@app.post("/webhooks/payhub")
|
|
19
|
+
def payhub_webhook() -> Response:
|
|
20
|
+
# Verify against the RAW body before trusting anything.
|
|
21
|
+
try:
|
|
22
|
+
event = webhook.parse(
|
|
23
|
+
request.get_data(), # raw bytes — do NOT use a re-encoded copy
|
|
24
|
+
request.headers.get("PayHub-Signature", ""),
|
|
25
|
+
SECRET,
|
|
26
|
+
)
|
|
27
|
+
except SignatureVerificationError:
|
|
28
|
+
return Response("invalid signature", status=400)
|
|
29
|
+
|
|
30
|
+
# There is no `event` field — derive it from `type` + `status`.
|
|
31
|
+
event_type = event.get("type")
|
|
32
|
+
status = event.get("status")
|
|
33
|
+
public_id = event.get("public_id")
|
|
34
|
+
|
|
35
|
+
# TODO: deduplicate on public_id (retries deliver the same body) and update
|
|
36
|
+
# your order, e.g. (event_type == "payment" and status == "SUCCESSFUL").
|
|
37
|
+
_ = (event_type, status, public_id)
|
|
38
|
+
|
|
39
|
+
return Response("ok", status=200)
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "barkapay-payhub"
|
|
7
|
+
description = "Official Python client for the PayHub payments API — mobile money & crypto, one API across countries. Import as `payhub`."
|
|
8
|
+
readme = "README.md"
|
|
9
|
+
requires-python = ">=3.9"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
authors = [{ name = "BarkaPay (PayHub)", email = "developers@payhub.africa" }]
|
|
13
|
+
keywords = ["payhub", "barkapay", "payments", "mobile-money", "fintech", "africa"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 5 - Production/Stable",
|
|
16
|
+
"Intended Audience :: Developers",
|
|
17
|
+
"License :: OSI Approved :: MIT License",
|
|
18
|
+
"Operating System :: OS Independent",
|
|
19
|
+
"Programming Language :: Python :: 3",
|
|
20
|
+
"Programming Language :: Python :: 3.9",
|
|
21
|
+
"Programming Language :: Python :: 3.10",
|
|
22
|
+
"Programming Language :: Python :: 3.11",
|
|
23
|
+
"Programming Language :: Python :: 3.12",
|
|
24
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
25
|
+
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
26
|
+
"Typing :: Typed",
|
|
27
|
+
]
|
|
28
|
+
dynamic = ["version"]
|
|
29
|
+
dependencies = []
|
|
30
|
+
|
|
31
|
+
[project.optional-dependencies]
|
|
32
|
+
dev = [
|
|
33
|
+
"pytest>=7.4",
|
|
34
|
+
"mypy>=1.8",
|
|
35
|
+
"ruff>=0.4",
|
|
36
|
+
]
|
|
37
|
+
|
|
38
|
+
[project.urls]
|
|
39
|
+
Homepage = "https://payhub.africa/developers"
|
|
40
|
+
Documentation = "https://github.com/BarkaPay/payhub-python#readme"
|
|
41
|
+
Source = "https://github.com/BarkaPay/payhub-python"
|
|
42
|
+
Changelog = "https://github.com/BarkaPay/payhub-python/blob/main/CHANGELOG.md"
|
|
43
|
+
Issues = "https://github.com/BarkaPay/payhub-python/issues"
|
|
44
|
+
|
|
45
|
+
[tool.hatch.version]
|
|
46
|
+
path = "src/payhub/_version.py"
|
|
47
|
+
|
|
48
|
+
[tool.hatch.build.targets.wheel]
|
|
49
|
+
packages = ["src/payhub"]
|
|
50
|
+
|
|
51
|
+
[tool.hatch.build.targets.sdist]
|
|
52
|
+
include = [
|
|
53
|
+
"/src",
|
|
54
|
+
"/tests",
|
|
55
|
+
"/examples",
|
|
56
|
+
"/README.md",
|
|
57
|
+
"/LICENSE",
|
|
58
|
+
"/CHANGELOG.md",
|
|
59
|
+
]
|
|
60
|
+
|
|
61
|
+
[tool.ruff]
|
|
62
|
+
line-length = 100
|
|
63
|
+
target-version = "py39"
|
|
64
|
+
src = ["src", "tests"]
|
|
65
|
+
|
|
66
|
+
[tool.ruff.lint]
|
|
67
|
+
select = [
|
|
68
|
+
"E", # pycodestyle errors
|
|
69
|
+
"W", # pycodestyle warnings
|
|
70
|
+
"F", # pyflakes
|
|
71
|
+
"I", # isort
|
|
72
|
+
"UP", # pyupgrade
|
|
73
|
+
"B", # flake8-bugbear
|
|
74
|
+
"C4", # flake8-comprehensions
|
|
75
|
+
"SIM", # flake8-simplify
|
|
76
|
+
"RUF", # ruff-specific
|
|
77
|
+
]
|
|
78
|
+
|
|
79
|
+
[tool.ruff.lint.isort]
|
|
80
|
+
known-first-party = ["payhub"]
|
|
81
|
+
|
|
82
|
+
[tool.mypy]
|
|
83
|
+
strict = true
|
|
84
|
+
files = ["src", "tests"]
|
|
85
|
+
warn_unreachable = true
|
|
86
|
+
warn_no_return = true
|
|
87
|
+
|
|
88
|
+
[tool.pytest.ini_options]
|
|
89
|
+
testpaths = ["tests"]
|
|
90
|
+
addopts = "-ra"
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
"""Official Python client for the PayHub payments API.
|
|
2
|
+
|
|
3
|
+
Quick start::
|
|
4
|
+
|
|
5
|
+
import payhub
|
|
6
|
+
|
|
7
|
+
client = payhub.PayHub(api_key="pk_live_xxx:sk_live_yyy", country="bf")
|
|
8
|
+
payment = client.payments.create({
|
|
9
|
+
"operator": "ORANGE",
|
|
10
|
+
"phone_number": "50123456789",
|
|
11
|
+
"amount": 10000,
|
|
12
|
+
"order": {"id": "ORDER-2026-001"},
|
|
13
|
+
})
|
|
14
|
+
print(payment.public_id, payment.status)
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
from __future__ import annotations
|
|
18
|
+
|
|
19
|
+
from . import webhook
|
|
20
|
+
from ._version import __version__
|
|
21
|
+
from .client import PayHub
|
|
22
|
+
from .enums import PaymentStatus, TransferStatus
|
|
23
|
+
from .errors import (
|
|
24
|
+
ApiError,
|
|
25
|
+
AuthenticationError,
|
|
26
|
+
AuthorizationError,
|
|
27
|
+
ConfigurationError,
|
|
28
|
+
ConflictError,
|
|
29
|
+
NetworkError,
|
|
30
|
+
NotFoundError,
|
|
31
|
+
PayHubError,
|
|
32
|
+
RateLimitError,
|
|
33
|
+
ServerError,
|
|
34
|
+
ServiceUnavailableError,
|
|
35
|
+
SignatureVerificationError,
|
|
36
|
+
ValidationError,
|
|
37
|
+
)
|
|
38
|
+
from .http import Request, Response, Transport, UrllibTransport
|
|
39
|
+
from .models import (
|
|
40
|
+
Balance,
|
|
41
|
+
Pagination,
|
|
42
|
+
Payment,
|
|
43
|
+
PaymentList,
|
|
44
|
+
Transfer,
|
|
45
|
+
TransferList,
|
|
46
|
+
)
|
|
47
|
+
|
|
48
|
+
__all__ = [
|
|
49
|
+
"ApiError",
|
|
50
|
+
"AuthenticationError",
|
|
51
|
+
"AuthorizationError",
|
|
52
|
+
"Balance",
|
|
53
|
+
"ConfigurationError",
|
|
54
|
+
"ConflictError",
|
|
55
|
+
"NetworkError",
|
|
56
|
+
"NotFoundError",
|
|
57
|
+
"Pagination",
|
|
58
|
+
"PayHub",
|
|
59
|
+
# errors
|
|
60
|
+
"PayHubError",
|
|
61
|
+
# models
|
|
62
|
+
"Payment",
|
|
63
|
+
"PaymentList",
|
|
64
|
+
# enums
|
|
65
|
+
"PaymentStatus",
|
|
66
|
+
"RateLimitError",
|
|
67
|
+
# http
|
|
68
|
+
"Request",
|
|
69
|
+
"Response",
|
|
70
|
+
"ServerError",
|
|
71
|
+
"ServiceUnavailableError",
|
|
72
|
+
"SignatureVerificationError",
|
|
73
|
+
"Transfer",
|
|
74
|
+
"TransferList",
|
|
75
|
+
"TransferStatus",
|
|
76
|
+
"Transport",
|
|
77
|
+
"UrllibTransport",
|
|
78
|
+
"ValidationError",
|
|
79
|
+
"__version__",
|
|
80
|
+
"webhook",
|
|
81
|
+
]
|