paga-python 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,424 @@
1
+ Metadata-Version: 2.5
2
+ Name: paga-python
3
+ Version: 0.1.0
4
+ Summary: Async Python SDK for the Paga Engine API - payments, payouts, wallets and financial operations.
5
+ Project-URL: Homepage, https://github.com/TeamTrustBridge/paga-python
6
+ Project-URL: Documentation, https://github.com/TeamTrustBridge/paga-python#readme
7
+ Project-URL: Repository, https://github.com/TeamTrustBridge/paga-python
8
+ Project-URL: Issues, https://github.com/TeamTrustBridge/paga-python/issues
9
+ License: GPL-3.0
10
+ License-File: LICENSE
11
+ Keywords: fintech,open-banking,paga,payments,payouts,sdk
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Framework :: AsyncIO
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Topic :: Office/Business :: Financial
23
+ Classifier: Typing :: Typed
24
+ Requires-Python: >=3.9
25
+ Requires-Dist: httpx<1.0,>=0.27
26
+ Requires-Dist: pydantic<3.0,>=2.7
27
+ Provides-Extra: dev
28
+ Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
29
+ Requires-Dist: pytest>=8.0; extra == 'dev'
30
+ Description-Content-Type: text/markdown
31
+
32
+ # paga-python
33
+
34
+ **Async Python SDK for the [Paga Engine API](https://developer-docs.paga.com/).**
35
+
36
+ `paga-python` makes the Paga developer workflow easy for page and integration
37
+ developers building checkout and payment experiences. It wraps the Paga Engine
38
+ API — payments, refunds, money transfers, airtime, bill payments, Direct
39
+ Debit, subsidiary accounts and business account operations — behind a single,
40
+ fully async client.
41
+
42
+ The TypeScript (`paga-ts`) and Rust (`paga-rs`) counterparts live in the same
43
+ repository and track the same operation set.
44
+
45
+ ## Features
46
+
47
+ - **Async all the way through** — built on `httpx.AsyncClient`, usable as an async context manager.
48
+ - **Simple interface** — every operation takes plain keyword-only parameters; no raw JSON payloads needed.
49
+ - **Built-in Paga hash signing** — SHA-512 request hashing validated against Paga's documented examples, plus webhook signature verification helpers.
50
+ - **Typed responses** — pydantic models for every endpoint response.
51
+ - **Typed exceptions** — `PagaError`, `PagaAuthenticationError`, `PagaAPIError`, `PagaRateLimitError`.
52
+ - **Typed status codes** — `CollectStatusCode` and `BusinessErrorCode` enums, with `classify()` to turn a response into a `SUCCESS` / `PENDING` / `PARTIAL` / `FAILED` / `UNKNOWN` outcome.
53
+ - **Unknown-outcome detection** — Paga's `-1`, `105` and `135` mean *unknown*, not *failed*. `PagaAPIError.is_unknown_outcome` tells you when to check the transaction status instead of resending.
54
+
55
+ > Paga requires your server's IP address to be whitelisted before any call will
56
+ > succeed. A 403 usually means the IP is not on the list.
57
+
58
+ ## Installation
59
+
60
+ ```bash
61
+ pip install paga-python
62
+ ```
63
+
64
+ Requires Python 3.9+ and runs on an asyncio event loop.
65
+
66
+ ## Quick start
67
+
68
+ ```python
69
+ import asyncio
70
+ from paga import PagaClient
71
+
72
+ async def main() -> None:
73
+ async with PagaClient(
74
+ public_id="YOUR_PUBLIC_KEY",
75
+ credentials="YOUR_SECRET_KEY",
76
+ hash_key="YOUR_HASH_KEY",
77
+ environment="test", # or "live"
78
+ ) as client:
79
+ payment = await client.create_payment(
80
+ reference_number="ORD-2026-0187",
81
+ amount=50,
82
+ payer_name="Bello Ramon",
83
+ payer_phone_number="08064343187",
84
+ payee_name="Your business name",
85
+ call_back_url="https://yourstore.com/webhooks/paga",
86
+ payment_methods=["BANK_TRANSFER"],
87
+ )
88
+ status = await client.get_payment_status(reference_number="ORD-2026-0187")
89
+ # status.data.statusCode -> "0" means paid
90
+
91
+ asyncio.run(main())
92
+ ```
93
+
94
+ ## Supported operations
95
+
96
+ | Area | Operation | Method | Endpoint |
97
+ |---|---|---|---|
98
+ | Checkout | Create payment request | `create_payment` | `POST /paymentRequest` |
99
+ | Checkout | Check payment status | `get_payment_status` | `POST /status` |
100
+ | Checkout | Verify charge | `verify_charge` | `POST /checkout/transaction/verify` |
101
+ | Refunds | Refund / cancel | `refund_payment` | `POST /refund/v2` |
102
+ | Refunds | Check refund status | `get_refund_status` | `POST /status` |
103
+ | Bank USSD | List customer's banks | `get_collect_banks` | `POST /banks` |
104
+ | Direct Debit | Start hosted set-up session | `start_direct_debit_session` | `POST /checkout/charge-process/start` |
105
+ | Direct Debit | Set up a mandate by API | `create_direct_debit_mandate` | `POST /paymentRequest` |
106
+ | Direct Debit | Check mandate status | `get_mandate_status` | `POST /status` |
107
+ | Direct Debit | Charge the mandate | `charge_mandate` | `POST /chargeDebitMandate` |
108
+ | Direct Debit | Check charge status | `get_charge_mandate_status` | `POST /getChargeMandateStatus` |
109
+ | Direct Debit | Disable a mandate | `disable_mandate` | `POST /disableMandate` |
110
+ | USD collection | Check payment status | `get_usd_payment_status` | `POST /status` |
111
+ | Money transfer | List institutions | `get_banks` | `POST /getBanks` |
112
+ | Money transfer | Validate the account | `validate_deposit_to_bank` | `POST /validateDepositToBank` |
113
+ | Money transfer | Send money to a bank account | `send_money` | `POST /depositToBank` |
114
+ | Money transfer | Send money to a Paga wallet | `transfer_to_paga_wallet` | `POST /moneyTransfer` |
115
+ | Money transfer | Validate a Paga wallet transfer | `validate_money_transfer` | `POST /validateMoneyTransfer` |
116
+ | Money transfer | Bulk money transfer | `send_bulk_money_transfer` | `POST /moneyTransferBulk` |
117
+ | Money transfer | Check transaction status | `get_transaction_status` | `POST /transactionStatus` |
118
+ | Airtime & data | List operators | `get_mobile_operators` | `POST /getMobileOperators` |
119
+ | Airtime & data | List data bundles | `get_data_bundles` | `POST /getDataBundleByOperator` |
120
+ | Airtime & data | Buy airtime / data | `buy_airtime` | `POST /airtimePurchase` |
121
+ | Bill payment | List billers | `get_merchants` | `POST /getMerchants` |
122
+ | Bill payment | List a biller's services | `get_merchant_services` | `POST /getMerchantServices` |
123
+ | Bill payment | Validate the customer | `get_merchant_account_details` | `POST /getMerchantAccountDetails` |
124
+ | Bill payment | Pay bill | `pay_bill` | `POST /merchantPayment` |
125
+ | Business | Check balance | `get_business_balance` | `POST /accountBalance` |
126
+ | Business | Transaction history | `get_business_transactions` | `POST /transactionHistory` |
127
+ | Business | Recent transactions | `get_recent_transactions` | `POST /recentTransactionHistory` |
128
+ | Business | Operation status | `get_operation_status` | `POST /getOperationStatus` |
129
+ | Business | Onboard a merchant | `onboard_merchant` | `POST /onboardMerchant` |
130
+ | Business | Dispense cash | `dispense_cash` | `POST /dispenseCash` |
131
+ | Subsidiary accounts | Create account | `create_subsidiary_account` | `POST /subsidiary-accounts` |
132
+ | Subsidiary accounts | Charge account | `charge_subsidiary_account` | `POST /subsidiary-accounts/{accountReference}/charge` |
133
+ | Subsidiary accounts | Top up account | `top_up_subsidiary_account` | `POST /subsidiary-accounts/{accountReference}/topup` |
134
+ | Subsidiary accounts | Transfer between accounts | `transfer_between_subsidiary_accounts` | `POST /subsidiary-accounts/transfer` |
135
+ | Subsidiary accounts | Retrieve account | `retrieve_subsidiary_account` | `GET /subsidiary-accounts/{accountReference}` |
136
+ | Subsidiary accounts | Update account | `update_subsidiary_account` | `PUT /subsidiary-accounts/{accountReference}` |
137
+ | Subsidiary accounts | Get balance | `get_subsidiary_balance` | `GET /subsidiary-accounts/{accountReference}/balance` |
138
+ | Subsidiary accounts | History | `get_subsidiary_history` | `GET /subsidiary-accounts/{accountReference}/history` |
139
+ | Persistent accounts | Register | `register_persistent_payment_account` | `POST /registerPersistentPaymentAccount` |
140
+ | Persistent accounts | Update | `update_persistent_payment_account` | `POST /updatePersistentPaymentAccount` |
141
+ | Persistent accounts | Get | `get_persistent_payment_account` | `POST /getPersistentPaymentAccount` |
142
+ | Persistent accounts | Delete | `delete_persistent_payment_account` | `POST /deletePersistentPaymentAccount` |
143
+ | Payment history | Request history | `get_payment_request_history` | `POST /history` |
144
+ | Customers | Register | `register_customer` | `POST /registerCustomer` |
145
+ | Customers | Register with KYC | `register_customer_with_kyc` | `POST /registerCustomerWithKYC` |
146
+ | Customers | Upload account photo | `register_customer_account_photo` | `POST /registerCustomerAccountPhoto` |
147
+ | Customers | Upload identification | `register_customer_identification` | `POST /registerCustomerIdentification` |
148
+
149
+ ## Usage
150
+
151
+ All operations take simple, keyword-only parameters — no raw JSON payloads needed.
152
+
153
+ ### Create a payment request
154
+
155
+ ```python
156
+ payment = await client.create_payment(
157
+ reference_number="ORD-2026-0187",
158
+ amount=50,
159
+ payer_name="Bello Ramon",
160
+ payer_phone_number="08064343187",
161
+ payee_name="Your business name",
162
+ call_back_url="https://yourstore.com/webhooks/paga",
163
+ payment_methods=["BANK_TRANSFER"],
164
+ )
165
+ ```
166
+
167
+ ### Check payment status
168
+
169
+ ```python
170
+ status = await client.get_payment_status(reference_number="ORD-2026-0187")
171
+ # status.data.statusCode -> "0" means paid
172
+ ```
173
+
174
+ ### Verify a charge
175
+
176
+ ```python
177
+ verified = await client.verify_charge(
178
+ payment_reference=payment.referenceNumber,
179
+ public_key="...",
180
+ amount=50,
181
+ currency="NGN",
182
+ )
183
+ # verified.status_code == 0 -> paid; 2 -> pending
184
+ ```
185
+
186
+ ### Refund / cancel a payment request
187
+
188
+ ```python
189
+ refund = await client.refund_payment(
190
+ reference_number="RFD-2026-0031",
191
+ payment_request_reference="ORD-2026-0187",
192
+ refund_amount=1000,
193
+ currency="NGN",
194
+ reason="Item out of stock",
195
+ )
196
+ # refund.statusCode -> "102" means duplicate reference (no double refund)
197
+ ```
198
+
199
+ ### Send money to a bank account or Paga wallet
200
+
201
+ ```python
202
+ transfer = await client.send_money(
203
+ reference_number="PAY-2026-0311",
204
+ amount="5000.00",
205
+ destination_bank_uuid="40090E2F-7446-4217-9345-7BBAB7043C4C",
206
+ destination_bank_account_number="0000000000",
207
+ remarks="Salary for June",
208
+ )
209
+ ```
210
+
211
+ ### Buy airtime or data
212
+
213
+ ```python
214
+ purchase = await client.buy_airtime(
215
+ reference_number="AIR-2026-0042",
216
+ amount="500",
217
+ destination_phone_number="08063332187",
218
+ mobile_operator_public_id="42419156-DD57-4737-8373-20678CD9AA29",
219
+ is_data_bundle=False,
220
+ )
221
+ ```
222
+
223
+ ### Pay a bill
224
+
225
+ ```python
226
+ bill = await client.pay_bill(
227
+ reference_number="BILL-2026-0042",
228
+ amount=6000,
229
+ merchant_account="A3878DC1-F07D-48E7-AA59-8276C3C26647",
230
+ merchant_reference_number="8110411076",
231
+ merchant_service=["STARTERE36"],
232
+ )
233
+ # bill.responseCode -> 0 means success
234
+ ```
235
+
236
+ ### Check business account balance
237
+
238
+ ```python
239
+ balance = await client.get_business_balance(reference_number="BAL-2026-0042")
240
+ # balance.availableBalance -> what you can actually send before a payout run
241
+ ```
242
+
243
+ ### Get business transaction history
244
+
245
+ ```python
246
+ history = await client.get_business_transactions(
247
+ reference_number="HIS-2026-0042",
248
+ start_date_utc="2026-11-01T00:00:00",
249
+ end_date_utc="2026-11-04T00:00:00",
250
+ )
251
+ # history.items -> transactions between the two dates
252
+ ```
253
+
254
+ ### Create a subsidiary account
255
+
256
+ ```python
257
+ account = await client.create_subsidiary_account(
258
+ reference_number="REF-100005550002",
259
+ account_reference="CUST-000184-WALLET",
260
+ account_name="Bello Ramon",
261
+ iifi_number="22222132329",
262
+ callback_url="https://yourstore.com/webhooks/paga",
263
+ )
264
+ # account.statusCode -> "0" means created; "102" means duplicate reference
265
+ ```
266
+
267
+ ### Charge a subsidiary account
268
+
269
+ ```python
270
+ charge = await client.charge_subsidiary_account(
271
+ account_reference="CUST-000184-WALLET",
272
+ reference_number="REF-CHARGE-001",
273
+ amount=1000,
274
+ currency="NGN",
275
+ narration="Service fee",
276
+ )
277
+ # charge.transactionId -> the debit transaction
278
+ # charge.newBalance -> balance after the debit
279
+ ```
280
+
281
+ ### Top up a subsidiary account
282
+
283
+ ```python
284
+ top_up = await client.top_up_subsidiary_account(
285
+ account_reference="CUST-000184-WALLET",
286
+ reference_number="REF-TOPUP-001",
287
+ amount=500,
288
+ currency="NGN",
289
+ narration="Bonus credit",
290
+ )
291
+ # top_up.newBalance -> balance after the credit
292
+ ```
293
+
294
+ ### Transfer between subsidiary accounts
295
+
296
+ ```python
297
+ transfer = await client.transfer_between_subsidiary_accounts(
298
+ source_account_reference="CUST-000184-WALLET",
299
+ destination_account_reference="CUST-000221-WALLET",
300
+ reference_number="REF-TRANSFER-001",
301
+ amount=1500,
302
+ currency="NGN",
303
+ narration="Payment for goods",
304
+ )
305
+ ```
306
+
307
+ ### Retrieve / update / balance / history for a subsidiary account
308
+
309
+ ```python
310
+ account = await client.retrieve_subsidiary_account(
311
+ account_reference="CUST-000184-WALLET",
312
+ reference_number="REF-GET-001",
313
+ )
314
+ account = await client.update_subsidiary_account(
315
+ account_reference="CUST-000184-WALLET",
316
+ reference_number="REF-UPDATE-001",
317
+ status="DISABLED", # send only what you want to change
318
+ )
319
+
320
+ balance = await client.get_subsidiary_balance(
321
+ account_reference="CUST-000184-WALLET",
322
+ reference_number="REF-BAL-001",
323
+ )
324
+
325
+ history = await client.get_subsidiary_history(
326
+ account_reference="CUST-000184-WALLET",
327
+ reference_number="REF-HIS-001",
328
+ start_date_time_utc="2026-06-01T00:00:00",
329
+ end_date_time_utc="2026-06-30T23:59:59",
330
+ page_number=0,
331
+ page_size=20,
332
+ )
333
+ ```
334
+
335
+ ## Webhook verification
336
+
337
+ ```python
338
+ from paga import (
339
+ parse_usd_payment_webhook,
340
+ verify_charge_callback,
341
+ verify_checkout_notification,
342
+ verify_funding_notification,
343
+ verify_mandate_callback,
344
+ verify_money_transfer_notification,
345
+ verify_payment_callback,
346
+ verify_persistent_payment_account_callback,
347
+ verify_subsidiary_operation,
348
+ )
349
+
350
+ # Checkout notification: hash = amount + timeStamp + paymentReference + hashKey
351
+ ok = verify_checkout_notification(payload, received_hash, hash_key)
352
+
353
+ # Dynamic virtual account callback: hash = notificationId + statusCode + externalReferenceNumber + state + outstandingBalance + hashKey
354
+ ok = verify_payment_callback(payload, received_hash, hash_key)
355
+
356
+ # Subsidiary funding notification: hash = transactionReference + transactionDate + amount + accountNumber + timestamp + hashKey
357
+ ok = verify_funding_notification(payload, received_hash, hash_key)
358
+
359
+ # Subsidiary charge / top-up / transfer callback: hash = externalReferenceNumber + transactionDate + amount + accountNumber + hashKey
360
+ ok = verify_subsidiary_operation(payload, received_hash, hash_key)
361
+
362
+ # Money transfer notification: the digest arrives in the x-paga-hash HEADER,
363
+ # not the body. hash = referenceNumber + transactionDate + transactionId + amount + sessionId
364
+ ok = verify_money_transfer_notification(payload, request.headers["x-paga-hash"], hash_key)
365
+
366
+ # Direct Debit mandate callback: hash = statusCode + timeStamp + accountNumber + bankName + referenceNumber + mandateStatus
367
+ ok = verify_mandate_callback(payload, payload["hash"], hash_key)
368
+
369
+ # Direct Debit charge callback: hash = statusCode + referenceNumber + accountReference + amount
370
+ ok = verify_charge_callback(payload, payload["hash"], hash_key)
371
+
372
+ # Persistent payment account callback: hash = statusCode + accountNumber + amount + clearingFeeAmount + transferFeeAmount
373
+ ok = verify_persistent_payment_account_callback(payload, payload["hash"], hash_key)
374
+ ```
375
+
376
+ The USD (ACH, Wire and Swift) webhook carries **no signature at all**, so
377
+ there is nothing to verify — parse it and de-duplicate on `referenceNumber`
378
+ plus `paymentId`:
379
+
380
+ ```python
381
+ webhook = parse_usd_payment_webhook(payload)
382
+ if webhook.isCaptured:
383
+ ... # fulfil
384
+ elif webhook.isFundingFailed:
385
+ ... # do not fulfil
386
+ ```
387
+
388
+ ## Error handling
389
+
390
+ ```python
391
+ from paga import PagaAPIError, PagaAuthenticationError, PagaRateLimitError
392
+
393
+ try:
394
+ payment = await client.create_payment(...)
395
+ except PagaAuthenticationError:
396
+ ... # invalid public key / secret key / hash key, or a non-whitelisted IP
397
+ except PagaRateLimitError:
398
+ ... # 429 from Paga
399
+ except PagaAPIError as err:
400
+ ... # err.code, err.responseCode, err.statusCode, err.outcome
401
+ ```
402
+
403
+ A 200 response does not mean the money moved. Read the code in the body:
404
+
405
+ ```python
406
+ from paga import classify, is_unknown_outcome, OperationOutcome
407
+
408
+ status = await client.get_transaction_status(reference_number="PAY-2026-0311")
409
+ if classify(status.model_dump()) is OperationOutcome.SUCCESS:
410
+ ... # settled
411
+ ```
412
+
413
+ When the outcome is **unknown** — Paga's `-1`, `105` and `135`, a timeout or a
414
+ 504 — do not send again. Check the transaction status with the *original*
415
+ reference number:
416
+
417
+ ```python
418
+ if is_unknown_outcome(body):
419
+ final = await client.get_transaction_status(reference_number=original_reference)
420
+ ```
421
+
422
+ ## License
423
+
424
+ GPL-3.0 — see [LICENSE](LICENSE).
@@ -0,0 +1,19 @@
1
+ paga/__init__.py,sha256=wal29UFTqW_v0PxX2mGPjAnQ5rm7-GxcFx9xSwO6I_U,5616
2
+ paga/actions.py,sha256=6C_d4T9ly4XuMaZafDgeNeaYoFw9FUISLhbNSYoHncY,9170
3
+ paga/auth.py,sha256=0UGsKr1TAptk_IsG_qyW9R1DYx1NCwttJtE5Inr3OJE,14551
4
+ paga/business.py,sha256=J4QF7pgK_cjgpOJCbJM6YEQHeHvLJRFcD-p8jf1OBl0,32462
5
+ paga/checkout.py,sha256=_5OIbG-3ZFikL8uqW9I47AawvkijtsC7GZ0abcdm9EE,9333
6
+ paga/client.py,sha256=fUcvDOCB5yxX4oH7RKcv6w7b_JmAcamTrl0AK80IElI,13397
7
+ paga/codes.py,sha256=qy3ZIsEuiRPRCzH3XIIPPrp8aCgJTpgTk0O6VdKPcrs,5267
8
+ paga/customer.py,sha256=SWJDrUhhZViZ8qT2cZLxMmaYF_9WaiTZjU27APj0RX8,11526
9
+ paga/direct_debit.py,sha256=BS_Q--I3NaAgs31at5kMErUXmftX7vp22hRGqN0ntSc,13506
10
+ paga/directory.py,sha256=EYuYiuMdZZMYNxs7Y9T2eemxd2i-QfOFVONlUSlVF5M,18766
11
+ paga/exceptions.py,sha256=-q1N9T6RHUqiqeAFBWeeEJRVdSGGAQfAQhPa6xwD4eE,2636
12
+ paga/models.py,sha256=2Y9GaXL-Xl7HoXj7vd2XeX0Xwtk9bgOI9TwgaOFX_Lc,32093
13
+ paga/outcome.py,sha256=8YSJZDIvZ8dgg70K2MMvXYHjSqD_mtkPYypUkTjiyFg,4083
14
+ paga/persistent.py,sha256=2G4czC75E2aqWM1K-F0OK8VLMN-qh4ERylC81TzCqFw,7450
15
+ paga/webhooks.py,sha256=hE45BMZhsRCo9bSgZM6_W3qinn3_2xUcg1O8NxF9TqA,12837
16
+ paga_python-0.1.0.dist-info/METADATA,sha256=bCxzRRP9Frh59X9uiW7GmNsOAVQeI2ui5ujJ-rPU_LY,16873
17
+ paga_python-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
18
+ paga_python-0.1.0.dist-info/licenses/LICENSE,sha256=OXLcl0T2SZ8Pmy2_dmlvKuetivmyPd5m1q-Gyd-zaYY,35149
19
+ paga_python-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any