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

{python_payway-0.0.9/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.9
+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>
@@ -281,6 +302,21 @@ PayWay API documentation <https://www.payway.com.au/docs/rest.html>
 It is recommended to use PayWay's Trusted Frame <https://www.payway.com.au/docs/rest.html#trusted-frame>
 when creating a single use token of a card or bank account so your PCI-compliance scope is reduced.  
 
+## Keeping the raw response
+
+Models parsed from a PayWay response keep that response verbatim on `raw`:
+
+```python
+transaction, errors = client.process_payment(payment)
+transaction.raw  # exactly what PayWay returned
+```
+
+Parsing is lossy — keys PayWay sends that the dataclass does not declare are dropped,
+absent keys become `None`, and a few are renamed (`maskedCardNumber` is parsed into
+`card_number`). Store `raw` rather than `to_dict()` if you are persisting responses for
+auditing, reconciliation or dispute resolution. Models you construct yourself, such as a
+`PayWayPayment` you are about to send, leave `raw` as `None`.
+
 ## Fraud
 
 Please follow PayWay's advice about reducing your risk of fraudulent transactions. <https://www.payway.com.au/docs/card-testing.html#card-testing>

{python_payway-0.0.9 → 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>
@@ -258,6 +279,21 @@ PayWay API documentation <https://www.payway.com.au/docs/rest.html>
 It is recommended to use PayWay's Trusted Frame <https://www.payway.com.au/docs/rest.html#trusted-frame>
 when creating a single use token of a card or bank account so your PCI-compliance scope is reduced.  
 
+## Keeping the raw response
+
+Models parsed from a PayWay response keep that response verbatim on `raw`:
+
+```python
+transaction, errors = client.process_payment(payment)
+transaction.raw  # exactly what PayWay returned
+```
+
+Parsing is lossy — keys PayWay sends that the dataclass does not declare are dropped,
+absent keys become `None`, and a few are renamed (`maskedCardNumber` is parsed into
+`card_number`). Store `raw` rather than `to_dict()` if you are persisting responses for
+auditing, reconciliation or dispute resolution. Models you construct yourself, such as a
+`PayWayPayment` you are about to send, leave `raw` as `None`.
+
 ## Fraud
 
 Please follow PayWay's advice about reducing your risk of fraudulent transactions. <https://www.payway.com.au/docs/card-testing.html#card-testing>

{python_payway-0.0.9 → 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.9 → 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.9 → python_payway-0.0.11}/payway/model.py

@@ -15,9 +15,16 @@ class PayWayModel:
         alias:      PayWay key when it is not the camelCase of the field name
         exclude:    omit the field from to_dict output
         from_dict:  callable applied to a non-None raw value when parsing
+
+    Instances built by from_dict keep the response body they were parsed from
+    on ``raw``, unchanged. Parsing is lossy - undeclared PayWay keys are dropped,
+    absent ones become None, and aliases rename them - so callers persisting a
+    response for auditing or dispute resolution should store ``raw``, not
+    ``to_dict()``. Models you build yourself leave it None.
     """
 
     __dataclass_fields__: ClassVar[dict[str, Any]]
+    raw: dict[str, Any] | None = None
 
     def to_dict(self) -> dict[str, Any]:
         result = {}
@@ -39,7 +46,9 @@ class PayWayModel:
             if converter is not None and value is not None:
                 value = converter(value)
             kwargs[f.name] = value
-        return cls(**kwargs)
+        instance = cls(**kwargs)
+        instance.raw = data
+        return instance
 
 
 @dataclass
@@ -65,8 +74,10 @@ class PayWayCard(PayWayModel):
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> PayWayCard:
-        data = {**data, "cardNumber": data.get("maskedCardNumber") or data.get("cardNumber")}
-        return super().from_dict(data)
+        card = super().from_dict({**data, "cardNumber": data.get("maskedCardNumber") or data.get("cardNumber")})
+        # Keep PayWay's own body, not the copy rewritten for the alias above.
+        card.raw = data
+        return card
 
 
 @dataclass
@@ -284,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.9 → python_payway-0.0.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-payway"
-version = "0.0.9"
+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.9 → 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.9
+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>
@@ -281,6 +302,21 @@ PayWay API documentation <https://www.payway.com.au/docs/rest.html>
 It is recommended to use PayWay's Trusted Frame <https://www.payway.com.au/docs/rest.html#trusted-frame>
 when creating a single use token of a card or bank account so your PCI-compliance scope is reduced.  
 
+## Keeping the raw response
+
+Models parsed from a PayWay response keep that response verbatim on `raw`:
+
+```python
+transaction, errors = client.process_payment(payment)
+transaction.raw  # exactly what PayWay returned
+```
+
+Parsing is lossy — keys PayWay sends that the dataclass does not declare are dropped,
+absent keys become `None`, and a few are renamed (`maskedCardNumber` is parsed into
+`card_number`). Store `raw` rather than `to_dict()` if you are persisting responses for
+auditing, reconciliation or dispute resolution. Models you construct yourself, such as a
+`PayWayPayment` you are about to send, leave `raw` as `None`.
+
 ## Fraud
 
 Please follow PayWay's advice about reducing your risk of fraudulent transactions. <https://www.payway.com.au/docs/card-testing.html#card-testing>

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

@@ -179,6 +179,29 @@ class TestClient(unittest.TestCase):
         self.assertEqual(transaction.status, "approved")
         self.assertEqual(transaction.response_code, "11")
 
+    @patch("requests.post")
+    def test_process_payment_keeps_the_raw_response(self, mock_post) -> None:
+        """
+        Parsing drops keys PayWay sent, so ``raw`` keeps the body verbatim for
+        callers that persist responses for auditing or dispute resolution.
+        """
+        response = load_json_file("tests/data/transaction.json")
+        mock_post.return_value.status_code = 200
+        mock_post.return_value.json.return_value = response
+        payment = copy.deepcopy(self.payment)
+        payment.customer_number = "1"
+        payment.token = "2bcec36f-7b02-43db-b3ec-bfb65acfe272"
+        payment.order_number = "5200"
+        payment.merchant_id = self.client.merchant_id
+
+        transaction, _ = self.client.process_payment(payment)
+
+        self.assertEqual(transaction.raw, response)
+        # cardScheme and cardType are not modelled, so only raw still has them.
+        self.assertEqual(transaction.raw["creditCard"]["cardScheme"], "visa")
+        self.assertNotIn("cardScheme", transaction.to_dict()["creditCard"])
+        self.assertEqual(transaction.card.raw, response["creditCard"])
+
     @patch("requests.post")
     def test_process_payment_with_idempotency_key(self, mock_post) -> None:
         """
@@ -262,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: