clickpesa-python-sdk 0.1.4__tar.gz → 0.2.1__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.
Files changed (35) hide show
  1. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/PKG-INFO +47 -6
  2. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/README.md +46 -5
  3. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/pyproject.toml +1 -1
  4. clickpesa_python_sdk-0.2.1/src/clickpesa/_version.py +1 -0
  5. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/async_client.py +5 -2
  6. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/client.py +6 -3
  7. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/security.py +34 -10
  8. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/services/billpay.py +49 -18
  9. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/services/payouts.py +180 -15
  10. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/webhooks.py +4 -3
  11. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa_python_sdk.egg-info/PKG-INFO +47 -6
  12. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa_python_sdk.egg-info/SOURCES.txt +1 -0
  13. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/tests/test_billpay.py +33 -0
  14. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/tests/test_payouts.py +122 -3
  15. clickpesa_python_sdk-0.2.1/tests/test_payouts_async.py +171 -0
  16. clickpesa_python_sdk-0.2.1/tests/test_webhook.py +176 -0
  17. clickpesa_python_sdk-0.1.4/src/clickpesa/_version.py +0 -1
  18. clickpesa_python_sdk-0.1.4/tests/test_webhook.py +0 -93
  19. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/LICENSE +0 -0
  20. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/setup.cfg +0 -0
  21. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/__init__.py +0 -0
  22. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/exceptions.py +0 -0
  23. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/py.typed +0 -0
  24. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/services/__init__.py +0 -0
  25. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/services/account.py +0 -0
  26. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/services/exchange.py +0 -0
  27. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/services/links.py +0 -0
  28. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa/services/payments.py +0 -0
  29. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa_python_sdk.egg-info/dependency_links.txt +0 -0
  30. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa_python_sdk.egg-info/requires.txt +0 -0
  31. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/src/clickpesa_python_sdk.egg-info/top_level.txt +0 -0
  32. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/tests/test_async_client.py +0 -0
  33. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/tests/test_client.py +0 -0
  34. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/tests/test_links.py +0 -0
  35. {clickpesa_python_sdk-0.1.4 → clickpesa_python_sdk-0.2.1}/tests/test_payments.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: clickpesa-python-sdk
3
- Version: 0.1.4
3
+ Version: 0.2.1
4
4
  Summary: Production-grade Python SDK for the ClickPesa API — sync & async, collections, payouts, BillPay and more
5
5
  Author-email: Jackson Linus <jacksonlinus95@gmail.com>
6
6
  License-Expression: MIT
@@ -221,8 +221,10 @@ preview = client.payouts.preview_bank(
221
221
  account_number="1234567890",
222
222
  bic="EQBLTZTZ",
223
223
  order_id="BANK20240001",
224
- transfer_type="ACH", # "ACH" or "RTGS"
225
224
  currency="TZS",
225
+ # transfer_type is optional — ClickPesa now picks the settlement rail
226
+ # automatically (ACH up to 20,000,000 TZS, RTGS above, RTGS for USD).
227
+ # Read preview["transferType"] / preview["estimatedArrival"] for what applies.
226
228
  )
227
229
 
228
230
  # 2. Create
@@ -232,11 +234,46 @@ payout = client.payouts.create_bank(
232
234
  account_name="Jane Doe",
233
235
  bic="EQBLTZTZ",
234
236
  order_id="BANK20240001",
235
- transfer_type="RTGS",
236
237
  currency="TZS",
237
238
  )
238
239
  ```
239
240
 
241
+ ### Lipa Namba / TanQR Payout
242
+
243
+ Send money to any Lipa Namba (merchant code) or TanQR in Tanzania. Provide **exactly one**
244
+ destination: `lipa_namba` + `provider_code`, or `qr_code` (the full scanned TanQR string).
245
+ Preview must resolve a beneficiary name before you create the payout.
246
+
247
+ ```python
248
+ # Get list of supported providers (mobile money networks and banks) and their codes
249
+ providers = client.payouts.get_lipa_namba_providers()
250
+ # [{"name": "MPESA", "providerCode": "503"}, {"name": "AIRTEL MONEY", "providerCode": "504"}, ...]
251
+
252
+ # 1. Preview — by Lipa Namba + provider
253
+ preview = client.payouts.preview_lipa_namba(
254
+ amount=10000,
255
+ order_id="LN20240001",
256
+ lipa_namba="58650236",
257
+ provider_code="503", # MPESA
258
+ )
259
+ print(preview["receiver"]["accountName"]) # resolved beneficiary name
260
+
261
+ # ...or preview by a scanned TanQR string instead
262
+ preview = client.payouts.preview_lipa_namba(
263
+ amount=10000,
264
+ order_id="LN20240002",
265
+ qr_code="00020101...tz.go.bot.tips...",
266
+ )
267
+
268
+ # 2. Create
269
+ payout = client.payouts.create_lipa_namba(
270
+ amount=10000,
271
+ order_id="LN20240001",
272
+ lipa_namba="58650236",
273
+ provider_code="503",
274
+ )
275
+ ```
276
+
240
277
  ### Query Payouts
241
278
 
242
279
  ```python
@@ -245,7 +282,7 @@ payouts = client.payouts.get_status("PAY20240001")
245
282
 
246
283
  # All payouts with filters
247
284
  page = client.payouts.list_all(
248
- channel="MOBILE MONEY",
285
+ channel="MOBILE MONEY", # or "BANK TRANSFER" | "TIPS LIPA NAMBA"
249
286
  status="SUCCESS",
250
287
  limit=50,
251
288
  )
@@ -280,6 +317,7 @@ cn = client.billpay.create_customer_control_number(
280
317
  phone="255712345678", # phone or email required
281
318
  email="john@example.com",
282
319
  amount=50000,
320
+ max_collection_amount=150000, # optional cap; forces ALLOW_PARTIAL_AND_OVER_PAYMENT, must be >= amount
283
321
  payment_mode="ALLOW_PARTIAL_AND_OVER_PAYMENT",
284
322
  )
285
323
  ```
@@ -313,6 +351,7 @@ details = client.billpay.get_details("55042914871931")
313
351
  client.billpay.update_reference(
314
352
  "55042914871931",
315
353
  amount=120000,
354
+ max_collection_amount=200000, # only with ALLOW_PARTIAL_AND_OVER_PAYMENT
316
355
  description="Updated Water Bill",
317
356
  payment_mode="EXACT",
318
357
  )
@@ -427,14 +466,16 @@ asyncio.run(run_payments())
427
466
  from clickpesa import WebhookValidator
428
467
 
429
468
  # In your webhook endpoint (Flask / FastAPI / Django etc.)
469
+ # ClickPesa sends the checksum inside the body (data.checksum), not in a header.
430
470
  def webhook_handler(request):
431
471
  is_valid = WebhookValidator.verify(
432
472
  payload=request.json,
433
- signature=request.headers["X-ClickPesa-Signature"],
434
473
  checksum_key="YOUR_CHECKSUM_KEY",
435
474
  )
436
475
  if not is_valid:
437
- return {"error": "Invalid signature"}, 401
476
+ # Don't trust the payload. Either answer 401, or (safer for payments)
477
+ # confirm the status with the API before acting on it.
478
+ return {"error": "Invalid checksum"}, 401
438
479
 
439
480
  # Process event ...
440
481
  ```
@@ -186,8 +186,10 @@ preview = client.payouts.preview_bank(
186
186
  account_number="1234567890",
187
187
  bic="EQBLTZTZ",
188
188
  order_id="BANK20240001",
189
- transfer_type="ACH", # "ACH" or "RTGS"
190
189
  currency="TZS",
190
+ # transfer_type is optional — ClickPesa now picks the settlement rail
191
+ # automatically (ACH up to 20,000,000 TZS, RTGS above, RTGS for USD).
192
+ # Read preview["transferType"] / preview["estimatedArrival"] for what applies.
191
193
  )
192
194
 
193
195
  # 2. Create
@@ -197,11 +199,46 @@ payout = client.payouts.create_bank(
197
199
  account_name="Jane Doe",
198
200
  bic="EQBLTZTZ",
199
201
  order_id="BANK20240001",
200
- transfer_type="RTGS",
201
202
  currency="TZS",
202
203
  )
203
204
  ```
204
205
 
206
+ ### Lipa Namba / TanQR Payout
207
+
208
+ Send money to any Lipa Namba (merchant code) or TanQR in Tanzania. Provide **exactly one**
209
+ destination: `lipa_namba` + `provider_code`, or `qr_code` (the full scanned TanQR string).
210
+ Preview must resolve a beneficiary name before you create the payout.
211
+
212
+ ```python
213
+ # Get list of supported providers (mobile money networks and banks) and their codes
214
+ providers = client.payouts.get_lipa_namba_providers()
215
+ # [{"name": "MPESA", "providerCode": "503"}, {"name": "AIRTEL MONEY", "providerCode": "504"}, ...]
216
+
217
+ # 1. Preview — by Lipa Namba + provider
218
+ preview = client.payouts.preview_lipa_namba(
219
+ amount=10000,
220
+ order_id="LN20240001",
221
+ lipa_namba="58650236",
222
+ provider_code="503", # MPESA
223
+ )
224
+ print(preview["receiver"]["accountName"]) # resolved beneficiary name
225
+
226
+ # ...or preview by a scanned TanQR string instead
227
+ preview = client.payouts.preview_lipa_namba(
228
+ amount=10000,
229
+ order_id="LN20240002",
230
+ qr_code="00020101...tz.go.bot.tips...",
231
+ )
232
+
233
+ # 2. Create
234
+ payout = client.payouts.create_lipa_namba(
235
+ amount=10000,
236
+ order_id="LN20240001",
237
+ lipa_namba="58650236",
238
+ provider_code="503",
239
+ )
240
+ ```
241
+
205
242
  ### Query Payouts
206
243
 
207
244
  ```python
@@ -210,7 +247,7 @@ payouts = client.payouts.get_status("PAY20240001")
210
247
 
211
248
  # All payouts with filters
212
249
  page = client.payouts.list_all(
213
- channel="MOBILE MONEY",
250
+ channel="MOBILE MONEY", # or "BANK TRANSFER" | "TIPS LIPA NAMBA"
214
251
  status="SUCCESS",
215
252
  limit=50,
216
253
  )
@@ -245,6 +282,7 @@ cn = client.billpay.create_customer_control_number(
245
282
  phone="255712345678", # phone or email required
246
283
  email="john@example.com",
247
284
  amount=50000,
285
+ max_collection_amount=150000, # optional cap; forces ALLOW_PARTIAL_AND_OVER_PAYMENT, must be >= amount
248
286
  payment_mode="ALLOW_PARTIAL_AND_OVER_PAYMENT",
249
287
  )
250
288
  ```
@@ -278,6 +316,7 @@ details = client.billpay.get_details("55042914871931")
278
316
  client.billpay.update_reference(
279
317
  "55042914871931",
280
318
  amount=120000,
319
+ max_collection_amount=200000, # only with ALLOW_PARTIAL_AND_OVER_PAYMENT
281
320
  description="Updated Water Bill",
282
321
  payment_mode="EXACT",
283
322
  )
@@ -392,14 +431,16 @@ asyncio.run(run_payments())
392
431
  from clickpesa import WebhookValidator
393
432
 
394
433
  # In your webhook endpoint (Flask / FastAPI / Django etc.)
434
+ # ClickPesa sends the checksum inside the body (data.checksum), not in a header.
395
435
  def webhook_handler(request):
396
436
  is_valid = WebhookValidator.verify(
397
437
  payload=request.json,
398
- signature=request.headers["X-ClickPesa-Signature"],
399
438
  checksum_key="YOUR_CHECKSUM_KEY",
400
439
  )
401
440
  if not is_valid:
402
- return {"error": "Invalid signature"}, 401
441
+ # Don't trust the payload. Either answer 401, or (safer for payments)
442
+ # confirm the status with the API before acting on it.
443
+ return {"error": "Invalid checksum"}, 401
403
444
 
404
445
  # Process event ...
405
446
  ```
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "clickpesa-python-sdk"
7
- version = "0.1.4"
7
+ version = "0.2.1"
8
8
  authors = [
9
9
  { name = "Jackson Linus", email = "jacksonlinus95@gmail.com" },
10
10
  ]
@@ -0,0 +1 @@
1
+ __version__ = "0.2.1"
@@ -15,10 +15,13 @@ from __future__ import annotations
15
15
  import asyncio
16
16
  import logging
17
17
  import time
18
- from typing import Any
18
+ from typing import TYPE_CHECKING, Any
19
19
 
20
20
  import httpx
21
21
 
22
+ if TYPE_CHECKING:
23
+ from typing_extensions import Self
24
+
22
25
  from .exceptions import (
23
26
  AuthenticationError,
24
27
  ClickPesaError,
@@ -277,7 +280,7 @@ class AsyncClickPesaClient:
277
280
  await self._http.aclose()
278
281
 
279
282
  # Async context-manager protocol
280
- async def __aenter__(self) -> "AsyncClickPesaClient":
283
+ async def __aenter__(self) -> "Self":
281
284
  return self
282
285
 
283
286
  async def __aexit__(self, *_: Any) -> None:
@@ -10,10 +10,13 @@ from __future__ import annotations
10
10
  import logging
11
11
  import time
12
12
  import threading
13
- from typing import Any
13
+ from typing import TYPE_CHECKING, Any
14
14
 
15
15
  import httpx
16
16
 
17
+ if TYPE_CHECKING:
18
+ from typing_extensions import Self
19
+
17
20
  from .exceptions import (
18
21
  AuthenticationError,
19
22
  ClickPesaError,
@@ -164,7 +167,7 @@ class ClickPesaClient:
164
167
  self._token = token
165
168
  self._token_expires_at = now + _TOKEN_TTL
166
169
  logger.debug("Access token cached for %d seconds.", _TOKEN_TTL)
167
- return self._token
170
+ return token
168
171
 
169
172
  raise ClickPesaError(
170
173
  f"Authentication failed after {self.max_retries} attempts"
@@ -300,7 +303,7 @@ class ClickPesaClient:
300
303
  self._http.close()
301
304
 
302
305
  # Context-manager protocol
303
- def __enter__(self) -> "ClickPesaClient":
306
+ def __enter__(self) -> "Self":
304
307
  return self
305
308
 
306
309
  def __exit__(self, *_: Any) -> None:
@@ -56,26 +56,50 @@ class SecurityManager:
56
56
  ).hexdigest()
57
57
 
58
58
  @staticmethod
59
- def verify_webhook(checksum_key: str, payload: dict, signature: str) -> bool:
59
+ def webhook_checksum(checksum_key: str, payload: dict) -> str:
60
60
  """
61
- Verify an incoming ClickPesa webhook signature.
61
+ The checksum ClickPesa puts in a webhook body.
62
62
 
63
- Uses ``hmac.compare_digest`` for constant-time comparison to prevent
64
- timing-based side-channel attacks.
63
+ ClickPesa webhooks look like ``{"event": "...", "data": {..., "checksum":
64
+ "...", "checksumMethod": "canonical"}}``. The checksum is
65
+ HMAC-SHA256(checksum_key, canonical compact JSON of ``data`` WITHOUT the
66
+ ``checksum`` and ``checksumMethod`` fields). The ``event`` envelope is
67
+ not signed.
68
+
69
+ Returns ``""`` when there is no key or no ``data`` object.
70
+ """
71
+ data = payload.get("data") if isinstance(payload, dict) else None
72
+ if not checksum_key or not isinstance(data, dict):
73
+ return ""
74
+ signed = {k: v for k, v in data.items() if k not in ("checksum", "checksumMethod")}
75
+ return SecurityManager.create_checksum(checksum_key, signed)
76
+
77
+ @staticmethod
78
+ def verify_webhook(checksum_key: str, payload: dict, signature: str | None = None) -> bool:
79
+ """
80
+ Verify an incoming ClickPesa webhook.
81
+
82
+ ClickPesa sends no signature header: the checksum is ``data.checksum``
83
+ in the body. ``signature`` is optional and, when given, is compared
84
+ instead of ``data.checksum`` (kept for callers that pass it).
85
+
86
+ Uses ``hmac.compare_digest`` for constant-time comparison.
65
87
 
66
88
  Args:
67
89
  checksum_key: Your application's checksum secret key.
68
90
  payload: The parsed webhook body dict.
69
- signature: The ``X-ClickPesa-Signature`` header value.
91
+ signature: Optional; defaults to ``payload["data"]["checksum"]``.
70
92
 
71
93
  Returns:
72
- ``True`` if the signature is valid, ``False`` otherwise.
94
+ ``True`` if the checksum is valid, ``False`` otherwise.
73
95
  """
74
- if not signature:
96
+ if signature is None:
97
+ data = payload.get("data") if isinstance(payload, dict) else None
98
+ signature = data.get("checksum") if isinstance(data, dict) else None
99
+ if not signature or not isinstance(signature, str):
75
100
  return False
76
-
77
- computed = SecurityManager.create_checksum(checksum_key, payload)
78
- return hmac.compare_digest(computed, signature)
101
+ computed = SecurityManager.webhook_checksum(checksum_key, payload)
102
+ return bool(computed) and hmac.compare_digest(computed, signature)
79
103
 
80
104
 
81
105
  __all__ = ["SecurityManager"]
@@ -34,6 +34,7 @@ class BillPayService:
34
34
  self,
35
35
  bill_reference: str | None = None,
36
36
  amount: float | None = None,
37
+ max_collection_amount: float | None = None,
37
38
  description: str | None = None,
38
39
  payment_mode: BillPaymentMode | None = None,
39
40
  ) -> dict[str, Any]:
@@ -41,14 +42,19 @@ class BillPayService:
41
42
  Generate a one-time order control number.
42
43
 
43
44
  All fields are optional. If ``bill_reference`` is omitted the API
44
- auto-generates one. ``payment_mode`` is only applied when ``amount``
45
- is also set.
45
+ auto-generates one. ``payment_mode`` is applied when ``amount`` is
46
+ set, or when ``max_collection_amount`` is set (forced to
47
+ ``"ALLOW_PARTIAL_AND_OVER_PAYMENT"``).
46
48
 
47
49
  Args:
48
- bill_reference: Custom alphanumeric reference (must be unique).
49
- amount: Bill amount.
50
- description: Human-readable bill description.
51
- payment_mode: ``"ALLOW_PARTIAL_AND_OVER_PAYMENT"`` (default) or ``"EXACT"``.
50
+ bill_reference: Custom alphanumeric reference (must be unique).
51
+ amount: Target/expected bill amount.
52
+ max_collection_amount: Maximum total this control number can collect;
53
+ closes once reached. Only with
54
+ ``"ALLOW_PARTIAL_AND_OVER_PAYMENT"``. If ``amount``
55
+ is also set, must be at least ``amount``.
56
+ description: Human-readable bill description.
57
+ payment_mode: ``"ALLOW_PARTIAL_AND_OVER_PAYMENT"`` (default) or ``"EXACT"``.
52
58
 
53
59
  Returns:
54
60
  Dict with ``billPayNumber``, ``billDescription``, ``billAmount``, etc.
@@ -58,6 +64,8 @@ class BillPayService:
58
64
  payload["billReference"] = bill_reference
59
65
  if amount is not None:
60
66
  payload["billAmount"] = amount
67
+ if max_collection_amount is not None:
68
+ payload["billMaxCollectionAmount"] = max_collection_amount
61
69
  if description is not None:
62
70
  payload["billDescription"] = description
63
71
  if payment_mode is not None:
@@ -71,6 +79,7 @@ class BillPayService:
71
79
  email: str | None = None,
72
80
  bill_reference: str | None = None,
73
81
  amount: float | None = None,
82
+ max_collection_amount: float | None = None,
74
83
  description: str | None = None,
75
84
  payment_mode: BillPaymentMode | None = None,
76
85
  ) -> dict[str, Any]:
@@ -80,13 +89,17 @@ class BillPayService:
80
89
  Either ``phone`` or ``email`` (or both) must be supplied.
81
90
 
82
91
  Args:
83
- customer_name: Customer's full name.
84
- phone: Phone with country code, no ``+`` (e.g. ``"255712345678"``).
85
- email: Customer email address.
86
- bill_reference: Custom alphanumeric reference (must be unique).
87
- amount: Bill amount.
88
- description: Human-readable bill description.
89
- payment_mode: ``"ALLOW_PARTIAL_AND_OVER_PAYMENT"`` (default) or ``"EXACT"``.
92
+ customer_name: Customer's full name.
93
+ phone: Phone with country code, no ``+`` (e.g. ``"255712345678"``).
94
+ email: Customer email address.
95
+ bill_reference: Custom alphanumeric reference (must be unique).
96
+ amount: Target/expected bill amount.
97
+ max_collection_amount: Maximum total this control number can collect;
98
+ closes once reached. Only with
99
+ ``"ALLOW_PARTIAL_AND_OVER_PAYMENT"``. If ``amount``
100
+ is also set, must be at least ``amount``.
101
+ description: Human-readable bill description.
102
+ payment_mode: ``"ALLOW_PARTIAL_AND_OVER_PAYMENT"`` (default) or ``"EXACT"``.
90
103
 
91
104
  Returns:
92
105
  Dict with ``billPayNumber``, ``billCustomerName``, ``billAmount``, etc.
@@ -103,6 +116,8 @@ class BillPayService:
103
116
  payload["billReference"] = bill_reference
104
117
  if amount is not None:
105
118
  payload["billAmount"] = amount
119
+ if max_collection_amount is not None:
120
+ payload["billMaxCollectionAmount"] = max_collection_amount
106
121
  if description is not None:
107
122
  payload["billDescription"] = description
108
123
  if payment_mode is not None:
@@ -184,6 +199,7 @@ class BillPayService:
184
199
  self,
185
200
  bill_pay_number: str,
186
201
  amount: float | None = None,
202
+ max_collection_amount: float | None = None,
187
203
  description: str | None = None,
188
204
  status: BillStatus | None = None,
189
205
  payment_mode: BillPaymentMode | None = None,
@@ -194,11 +210,15 @@ class BillPayService:
194
210
  At least one argument besides ``bill_pay_number`` must be provided.
195
211
 
196
212
  Args:
197
- bill_pay_number: The BillPay number to update.
198
- amount: New bill amount (positive, max 2 decimal places).
199
- description: New description (max 500 characters).
200
- status: ``"ACTIVE"`` or ``"INACTIVE"``.
201
- payment_mode: ``"ALLOW_PARTIAL_AND_OVER_PAYMENT"`` or ``"EXACT"``.
213
+ bill_pay_number: The BillPay number to update.
214
+ amount: New bill amount (positive, max 2 decimal places).
215
+ max_collection_amount: New max total that can be collected; remaining is
216
+ recalculated from what was already paid. Only with
217
+ ``"ALLOW_PARTIAL_AND_OVER_PAYMENT"``.
218
+ description: New description (max 500 characters).
219
+ status: ``"ACTIVE"`` or ``"INACTIVE"``.
220
+ payment_mode: ``"ALLOW_PARTIAL_AND_OVER_PAYMENT"`` or ``"EXACT"``
221
+ (switching to ``"EXACT"`` removes the collection limit).
202
222
 
203
223
  Returns:
204
224
  Updated BillPay object.
@@ -206,6 +226,8 @@ class BillPayService:
206
226
  data: dict[str, Any] = {}
207
227
  if amount is not None:
208
228
  data["billAmount"] = amount
229
+ if max_collection_amount is not None:
230
+ data["billMaxCollectionAmount"] = max_collection_amount
209
231
  if description is not None:
210
232
  data["billDescription"] = description
211
233
  if status is not None:
@@ -241,6 +263,7 @@ class AsyncBillPayService:
241
263
  self,
242
264
  bill_reference: str | None = None,
243
265
  amount: float | None = None,
266
+ max_collection_amount: float | None = None,
244
267
  description: str | None = None,
245
268
  payment_mode: BillPaymentMode | None = None,
246
269
  ) -> dict[str, Any]:
@@ -249,6 +272,8 @@ class AsyncBillPayService:
249
272
  payload["billReference"] = bill_reference
250
273
  if amount is not None:
251
274
  payload["billAmount"] = amount
275
+ if max_collection_amount is not None:
276
+ payload["billMaxCollectionAmount"] = max_collection_amount
252
277
  if description is not None:
253
278
  payload["billDescription"] = description
254
279
  if payment_mode is not None:
@@ -262,6 +287,7 @@ class AsyncBillPayService:
262
287
  email: str | None = None,
263
288
  bill_reference: str | None = None,
264
289
  amount: float | None = None,
290
+ max_collection_amount: float | None = None,
265
291
  description: str | None = None,
266
292
  payment_mode: BillPaymentMode | None = None,
267
293
  ) -> dict[str, Any]:
@@ -276,6 +302,8 @@ class AsyncBillPayService:
276
302
  payload["billReference"] = bill_reference
277
303
  if amount is not None:
278
304
  payload["billAmount"] = amount
305
+ if max_collection_amount is not None:
306
+ payload["billMaxCollectionAmount"] = max_collection_amount
279
307
  if description is not None:
280
308
  payload["billDescription"] = description
281
309
  if payment_mode is not None:
@@ -319,6 +347,7 @@ class AsyncBillPayService:
319
347
  self,
320
348
  bill_pay_number: str,
321
349
  amount: float | None = None,
350
+ max_collection_amount: float | None = None,
322
351
  description: str | None = None,
323
352
  status: BillStatus | None = None,
324
353
  payment_mode: BillPaymentMode | None = None,
@@ -326,6 +355,8 @@ class AsyncBillPayService:
326
355
  data: dict[str, Any] = {}
327
356
  if amount is not None:
328
357
  data["billAmount"] = amount
358
+ if max_collection_amount is not None:
359
+ data["billMaxCollectionAmount"] = max_collection_amount
329
360
  if description is not None:
330
361
  data["billDescription"] = description
331
362
  if status is not None: