python-payway 0.0.10__tar.gz → 0.0.11__tar.gz

{python_payway-0.0.10/python_payway.egg-info → python_payway-0.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-payway
-Version: 0.0.10
+Version: 0.0.11
 Summary: Python client for working with Westpac's PayWay REST API
 Author-email: Ben Napper <reppan197@gmail.com>
 License: MIT
@@ -274,6 +274,27 @@ Update a customer's payment setup with a new credit card or bank account in PayW
 payment_setup, errors = client.update_payment_setup(new_token, payway_customer.customer_number)
 ```
 
+## Renewing the secret API key
+
+Secret API keys expire one year after they are created. PayWay generates the replacement
+40 days before that, so an application that asks for the latest key once a day and stores
+what it gets back rolls onto the new key without an administrator creating one in the
+PayWay website.
+
+```python
+api_key, errors = client.get_latest_api_key()
+if api_key and api_key.key != stored_secret_api_key:
+    # Persist api_key.key. Log api_key.key_name - it is masked; the key itself is a password.
+    save_secret_api_key(api_key.key)
+```
+
+Usually the key returned is the one that authenticated the call. Renewal chains off the
+live key, so if the stored key is left to expire the call fails with a `PaywayError` and
+recovery means minting a key by hand — poll daily and alert on repeated failures.
+
+To test your renewal code, create two secret API keys in the PayWay website, configure the
+first, and confirm the application switches to the second on its own.
+
 ## Additional notes
 
 PayWay API documentation <https://www.payway.com.au/docs/rest.html>

{python_payway-0.0.10 → python_payway-0.0.11}/README.md

@@ -251,6 +251,27 @@ Update a customer's payment setup with a new credit card or bank account in PayW
 payment_setup, errors = client.update_payment_setup(new_token, payway_customer.customer_number)
 ```
 
+## Renewing the secret API key
+
+Secret API keys expire one year after they are created. PayWay generates the replacement
+40 days before that, so an application that asks for the latest key once a day and stores
+what it gets back rolls onto the new key without an administrator creating one in the
+PayWay website.
+
+```python
+api_key, errors = client.get_latest_api_key()
+if api_key and api_key.key != stored_secret_api_key:
+    # Persist api_key.key. Log api_key.key_name - it is masked; the key itself is a password.
+    save_secret_api_key(api_key.key)
+```
+
+Usually the key returned is the one that authenticated the call. Renewal chains off the
+live key, so if the stored key is left to expire the call fails with a `PaywayError` and
+recovery means minting a key by hand — poll daily and alert on repeated failures.
+
+To test your renewal code, create two secret API keys in the PayWay website, configure the
+first, and confirm the application switches to the second on its own.
+
 ## Additional notes
 
 PayWay API documentation <https://www.payway.com.au/docs/rest.html>

{python_payway-0.0.10 → python_payway-0.0.11}/payway/client.py

@@ -10,6 +10,7 @@ from typing import Any
 import requests
 
 from payway.constants import (
+    API_KEY_URL,
     BANK_ACCOUNT_PAYMENT_CHOICE,
     CREDIT_CARD_PAYMENT_CHOICE,
     CUSTOMER_URL,
@@ -26,6 +27,7 @@ from payway.model import (
     BankAccount,
     PaymentError,
     PaymentSetup,
+    PayWayApiKey,
     PayWayCard,
     PayWayCustomer,
     PayWayPayment,
@@ -361,6 +363,21 @@ class Client(CustomerRequest, TransactionRequest):
             return None, errors
         return PayWayTransaction.from_dict(response.json()), errors
 
+    def get_latest_api_key(self) -> tuple[PayWayApiKey | None, list[PaymentError] | None]:
+        """
+        Return the secret API key to use from now on, authenticated with the current one.
+        Usually this is the key already in use. PayWay generates the replacement 40 days
+        before the current key expires, and returns that instead once it exists, so callers
+        polling daily and persisting the result renew without an administrator minting a key
+        in the PayWay website.
+        https://www.payway.com.au/docs/rest.html#automate-secret-api-key-renewal
+        """
+        response = self.get_request(f"{API_KEY_URL}/latest")
+        errors = self._validate_response(response)
+        if errors:
+            return None, errors
+        return PayWayApiKey.from_dict(response.json()), errors
+
     def get_customer(self, customer_id: str) -> tuple[PayWayCustomer | None, list[PaymentError] | None]:
         """
         Returns a PayWay Customer's Payment Setup, [Payment] Schedule, Contact Details, Custom Fields and Notes

{python_payway-0.0.10 → python_payway-0.0.11}/payway/constants.py

@@ -13,6 +13,7 @@ PAYWAY_API_URL = "https://api.payway.com.au/rest/v1"
 TOKEN_URL = PAYWAY_API_URL + "/single-use-tokens"
 TRANSACTION_URL = PAYWAY_API_URL + "/transactions"
 CUSTOMER_URL = PAYWAY_API_URL + "/customers"
+API_KEY_URL = PAYWAY_API_URL + "/api-keys"
 TRANSACTION_APPROVED = "0"
 
 SUMMARY_CODES = {

{python_payway-0.0.10 → python_payway-0.0.11}/payway/model.py

@@ -295,3 +295,14 @@ class TokenResponse(PayWayModel):
     payment_method: str | None = None
     card: PayWayCard | None = field(default=None, metadata={"alias": "creditCard", "from_dict": PayWayCard.from_dict})
     bank_account: dict[str, Any] | None = None
+
+
+@dataclass
+class PayWayApiKey(PayWayModel):
+    """
+    key_name: str: masked form of the key, safe to log
+    key: str: the secret API key itself - treat it like a password
+    """
+
+    key_name: str | None = None
+    key: str | None = None

{python_payway-0.0.10 → python_payway-0.0.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-payway"
-version = "0.0.10"
+version = "0.0.11"
 description = "Python client for working with Westpac's PayWay REST API"
 authors = [
     { name = "Ben Napper", email = "reppan197@gmail.com" }

{python_payway-0.0.10 → python_payway-0.0.11/python_payway.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-payway
-Version: 0.0.10
+Version: 0.0.11
 Summary: Python client for working with Westpac's PayWay REST API
 Author-email: Ben Napper <reppan197@gmail.com>
 License: MIT
@@ -274,6 +274,27 @@ Update a customer's payment setup with a new credit card or bank account in PayW
 payment_setup, errors = client.update_payment_setup(new_token, payway_customer.customer_number)
 ```
 
+## Renewing the secret API key
+
+Secret API keys expire one year after they are created. PayWay generates the replacement
+40 days before that, so an application that asks for the latest key once a day and stores
+what it gets back rolls onto the new key without an administrator creating one in the
+PayWay website.
+
+```python
+api_key, errors = client.get_latest_api_key()
+if api_key and api_key.key != stored_secret_api_key:
+    # Persist api_key.key. Log api_key.key_name - it is masked; the key itself is a password.
+    save_secret_api_key(api_key.key)
+```
+
+Usually the key returned is the one that authenticated the call. Renewal chains off the
+live key, so if the stored key is left to expire the call fails with a `PaywayError` and
+recovery means minting a key by hand — poll daily and alert on repeated failures.
+
+To test your renewal code, create two secret API keys in the PayWay website, configure the
+first, and confirm the application switches to the second on its own.
+
 ## Additional notes
 
 PayWay API documentation <https://www.payway.com.au/docs/rest.html>

{python_payway-0.0.10 → python_payway-0.0.11}/tests/test_client.py

@@ -285,6 +285,68 @@ class TestClient(unittest.TestCase):
         self.assertIsNone(ps_errors)
         self.assertIsNotNone(ps)
 
+    @patch("requests.get")
+    def test_get_latest_api_key(self, mock_get) -> None:
+        mock_get.return_value.status_code = 200
+        mock_get.return_value.json.return_value = {
+            "keyName": "T10000_SEC...1A4",
+            "key": "T10000_SEC_RANDOM_RANDOM_RANDOM_1A4",
+        }
+
+        api_key, errors = self.client.get_latest_api_key()
+
+        self.assertIsNone(errors)
+        self.assertEqual(api_key.key_name, "T10000_SEC...1A4")
+        self.assertEqual(api_key.key, "T10000_SEC_RANDOM_RANDOM_RANDOM_1A4")
+        self.assertEqual(mock_get.call_args.kwargs["url"], "https://api.payway.com.au/rest/v1/api-keys/latest")
+        self.assertEqual(mock_get.call_args.kwargs["auth"], ("TPUBLISHABLE-SECRET", ""))
+
+    @patch("requests.get")
+    def test_get_latest_api_key_returns_the_replacement_key(self, mock_get) -> None:
+        """
+        PayWay generates the next secret key 40 days before the current one expires and
+        returns it here in place of the key that authenticated the request.
+        """
+        mock_get.return_value.status_code = 200
+        mock_get.return_value.json.return_value = {
+            "keyName": "T10000_SEC...9B2",
+            "key": "T10000_SEC_NEXT_NEXT_NEXT_9B2",
+        }
+
+        api_key, errors = self.client.get_latest_api_key()
+
+        self.assertIsNone(errors)
+        self.assertNotEqual(api_key.key, self.client.secret_api_key)
+        self.assertEqual(api_key.key, "T10000_SEC_NEXT_NEXT_NEXT_9B2")
+
+    @patch("requests.get")
+    def test_get_latest_api_key_returns_payway_errors(self, mock_get) -> None:
+        mock_get.return_value.status_code = 422
+        mock_get.return_value.json.return_value = {
+            "data": [{"fieldName": "apiKey", "message": "Invalid API key.", "fieldValue": ""}]
+        }
+
+        api_key, errors = self.client.get_latest_api_key()
+
+        self.assertIsNone(api_key)
+        self.assertEqual(len(errors), 1)
+        self.assertEqual(errors[0].message, "Invalid API key.")
+
+    @patch("requests.get")
+    def test_get_latest_api_key_raises_when_the_current_key_is_rejected(self, mock_get) -> None:
+        """
+        Renewal chains off the live key, so an expired one cannot fetch its replacement -
+        recovering needs an administrator to create a key in the PayWay website.
+        """
+        mock_get.return_value.status_code = 401
+        mock_get.return_value.reason = "Unauthorized"
+        mock_get.return_value.url = "https://api.payway.com.au/rest/v1/api-keys/latest"
+
+        with self.assertRaises(PaywayError) as context:
+            self.client.get_latest_api_key()
+
+        self.assertIn("401", str(context.exception))
+
 
 class TestClientRetries(unittest.TestCase):
     def setUp(self) -> None: