python-payway 0.0.7__tar.gz → 0.0.8__tar.gz

{python_payway-0.0.7/python_payway.egg-info → python_payway-0.0.8}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: python-payway
-Version: 0.0.7
+Version: 0.0.8
 Summary: Python client for working with Westpac's PayWay REST API
 Author-email: Ben Napper <reppan197@gmail.com>
 License: MIT
@@ -11,7 +11,7 @@ Keywords: payway,westpac,api,client
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: requests>=2.20.0
@@ -19,6 +19,7 @@ Provides-Extra: dev
 Requires-Dist: pre-commit>=3.5.0; extra == "dev"
 Requires-Dist: ruff==0.6.6; extra == "dev"
 Requires-Dist: mypy>=0.971; extra == "dev"
+Dynamic: license-file
 
 # PayWay REST API - Python
 
@@ -32,6 +33,8 @@ Requires-Dist: mypy>=0.971; extra == "dev"
 
 ## Install
 
+Requires Python 3.11 or later.
+
 ```bash
 pip install python-payway
 ```
@@ -131,6 +134,36 @@ payment = PayWayPayment(customer_number=customer_number,
 transaction, errors = client.process_payment(payment)
 ```
 
+## Retries
+
+Retries are off by default. Opt in with `max_retries` (and optionally `retry_delay`, the base
+wait in seconds between attempts):
+
+```python
+client = Client(merchant_id='<your_payway_merchant_id>',
+                bank_account_id='<your_payway_bank_account_id>',
+                publishable_api_key='<your_payway_publishable_api_key>',
+                secret_api_key='<your_payway_secret_api_key>',
+                max_retries=2,
+                retry_delay=1.0)
+```
+
+This follows PayWay's retry guidance (<https://www.payway.com.au/docs/rest.html#network-errors>):
+
+- Requests are resent on connection errors, timeouts and HTTP 429/503 responses, waiting
+  `retry_delay` seconds between attempts (linear backoff, or the response's `Retry-After`
+  header when present). PayWay suggests a 20 second wait; keep `retry_delay` small for
+  synchronous checkout flows.
+- POSTs are only retried when an `idempotency_key` was supplied — the same
+  `Idempotency-Key` is resent so PayWay replays the original response instead of
+  processing a duplicate payment. POSTs without a key (and PUTs) are never retried.
+  GETs are always safe to retry.
+- Other errors (including HTTP 500/502/504) are never retried, per PayWay's advice.
+
+```python
+transaction, errors = client.process_payment(payment, idempotency_key=str(uuid.uuid4()))
+```
+
 ## Handling errors
 
 Documented errors (such as 422 Unprocessable entity) are parsed into an PaymentError class that you can use in an customer error message.
@@ -234,12 +267,11 @@ Please follow PayWay's advice about reducing your risk of fraudulent transaction
 ## Running the project
 
 ```bash
-uv python install 3.8.19
-uv venv --python 3.8.19
-source .venv/bin/activate
-uv sync --extra dev
+uv sync
 ```
 
+uv provisions a suitable Python (3.11+) and installs the dev dependencies automatically.
+
 ## Testing
 
 ```bash

{python_payway-0.0.7 → python_payway-0.0.8}/README.md

@@ -10,6 +10,8 @@
 
 ## Install
 
+Requires Python 3.11 or later.
+
 ```bash
 pip install python-payway
 ```
@@ -109,6 +111,36 @@ payment = PayWayPayment(customer_number=customer_number,
 transaction, errors = client.process_payment(payment)
 ```
 
+## Retries
+
+Retries are off by default. Opt in with `max_retries` (and optionally `retry_delay`, the base
+wait in seconds between attempts):
+
+```python
+client = Client(merchant_id='<your_payway_merchant_id>',
+                bank_account_id='<your_payway_bank_account_id>',
+                publishable_api_key='<your_payway_publishable_api_key>',
+                secret_api_key='<your_payway_secret_api_key>',
+                max_retries=2,
+                retry_delay=1.0)
+```
+
+This follows PayWay's retry guidance (<https://www.payway.com.au/docs/rest.html#network-errors>):
+
+- Requests are resent on connection errors, timeouts and HTTP 429/503 responses, waiting
+  `retry_delay` seconds between attempts (linear backoff, or the response's `Retry-After`
+  header when present). PayWay suggests a 20 second wait; keep `retry_delay` small for
+  synchronous checkout flows.
+- POSTs are only retried when an `idempotency_key` was supplied — the same
+  `Idempotency-Key` is resent so PayWay replays the original response instead of
+  processing a duplicate payment. POSTs without a key (and PUTs) are never retried.
+  GETs are always safe to retry.
+- Other errors (including HTTP 500/502/504) are never retried, per PayWay's advice.
+
+```python
+transaction, errors = client.process_payment(payment, idempotency_key=str(uuid.uuid4()))
+```
+
 ## Handling errors
 
 Documented errors (such as 422 Unprocessable entity) are parsed into an PaymentError class that you can use in an customer error message.
@@ -212,12 +244,11 @@ Please follow PayWay's advice about reducing your risk of fraudulent transaction
 ## Running the project
 
 ```bash
-uv python install 3.8.19
-uv venv --python 3.8.19
-source .venv/bin/activate
-uv sync --extra dev
+uv sync
 ```
 
+uv provisions a suitable Python (3.11+) and installs the dev dependencies automatically.
+
 ## Testing
 
 ```bash

{python_payway-0.0.7 → python_payway-0.0.8}/payway/client.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
 import json
+import time
+from collections.abc import Callable
+from http import HTTPStatus
 from logging import getLogger
 from typing import Any
 
@@ -11,9 +14,11 @@ from payway.constants import (
     CREDIT_CARD_PAYMENT_CHOICE,
     CUSTOMER_URL,
     PAYWAY_ERROR_RESPONSE_CODES,
+    RETRYABLE_STATUS_CODES,
     TOKEN_NO_REDIRECT,
     TRANSACTION_URL,
     VALID_PAYMENT_METHOD_CHOICES,
+    PaymentMethod,
 )
 from payway.customers import CustomerRequest
 from payway.exceptions import PaywayError
@@ -43,18 +48,22 @@ class Client(CustomerRequest, TransactionRequest):
     secret_api_key = ""
     publishable_api_key = ""
 
-    def __init__(
+    def __init__(  # noqa: PLR0913
         self,
         merchant_id: str,
         bank_account_id: str,
         secret_api_key: str,
         publishable_api_key: str,
+        max_retries: int = 0,
+        retry_delay: float = 1.0,
     ) -> None:
         """
         :param merchant_id: PayWay Merchant ID
         :param bank_account_id: PayWay Bank Account ID
         :param secret_api_key: PayWay Secret APi Key
         :param publishable_api_key: PayWay Publishable API Key
+        :param max_retries: retries per request on network errors and HTTP 429/503 (0 disables)
+        :param retry_delay: base seconds to wait between attempts (Retry-After header wins if present)
         """
         self._validate_credentials(
             merchant_id,
@@ -66,9 +75,11 @@ class Client(CustomerRequest, TransactionRequest):
         self.bank_account_id = bank_account_id
         self.secret_api_key = secret_api_key
         self.publishable_api_key = publishable_api_key
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
         session = requests.Session()
         session.auth = (self.secret_api_key, "")
-        session.headers = {"content-type": "application/x-www-form-urlencoded"}
+        session.headers["content-type"] = "application/x-www-form-urlencoded"
         self.session = session
         session_no_headers = requests.Session()
         session_no_headers.auth = session.auth
@@ -95,7 +106,10 @@ class Client(CustomerRequest, TransactionRequest):
             )
 
     def get_request(self, endpoint: str) -> requests.Response:
-        return requests.get(url=endpoint, auth=(self.secret_api_key, ""), timeout=30)
+        return self._send_with_retries(
+            lambda: requests.get(url=endpoint, auth=(self.secret_api_key, ""), timeout=30),
+            can_retry=True,
+        )
 
     def post_request(
         self, endpoint: str, data: dict[str, Any], auth: tuple[str, str] | None = None, idempotency_key: str | None = None
@@ -109,9 +123,41 @@ class Client(CustomerRequest, TransactionRequest):
         headers = {"content-type": "application/x-www-form-urlencoded"}
         if idempotency_key:
             headers["Idempotency-Key"] = idempotency_key
-        return requests.post(url=endpoint, auth=auth, data=data, headers=headers, timeout=30)
+        return self._send_with_retries(
+            lambda: requests.post(url=endpoint, auth=auth, data=data, headers=headers, timeout=30),
+            can_retry=bool(idempotency_key),
+        )
+
+    def _send_with_retries(self, send: Callable[[], requests.Response], can_retry: bool) -> requests.Response:  # noqa: FBT001
+        """
+        Resend on network errors and HTTP 429/503 per PayWay's retry guidance
+        https://www.payway.com.au/docs/rest.html#network-errors
+        Requests without an Idempotency-Key must pass can_retry=False: retrying
+        them could double-charge. Other statuses (including 500/502/504) are
+        returned as-is.
+        """
+        retries = self.max_retries if can_retry else 0
+        for attempt in range(retries):
+            try:
+                response = send()
+            except (requests.ConnectionError, requests.Timeout) as exc:
+                logger.warning("PayWay request failed (%s), retrying", exc)
+                time.sleep(self._retry_wait(attempt, None))
+                continue
+            if response.status_code not in RETRYABLE_STATUS_CODES:
+                return response
+            logger.warning("PayWay responded %s, retrying", response.status_code)
+            time.sleep(self._retry_wait(attempt, response))
+        return send()
+
+    def _retry_wait(self, attempt: int, response: requests.Response | None) -> float:
+        retry_after = response.headers.get("Retry-After") if response is not None else None
+        if retry_after and retry_after.isdigit():
+            return float(retry_after)
+        return self.retry_delay * (attempt + 1)
 
     def put_request(self, endpoint: str, data: dict[str, Any]) -> requests.Response:
+        # No Idempotency-Key is sent on PUTs, so they are never retried
         return requests.put(
             url=endpoint,
             auth=(self.secret_api_key, ""),
@@ -121,30 +167,27 @@ class Client(CustomerRequest, TransactionRequest):
         )
 
     def create_token(
-        self, payway_obj: BankAccount | PayWayCard, payment_method: str, idempotency_key: str | None = None
+        self, payway_obj: BankAccount | PayWayCard, payment_method: PaymentMethod | str, idempotency_key: str | None = None
     ) -> tuple[TokenResponse | None, list[PaymentError] | None]:
         """
         Creates a single use token for a Customer's payment setup (credit card or bank account)
         :param payway_obj:   object: one of model.PayWayCard or model.BankAccount object
-        :param payment_method:   str: one of `card` or `direct_debit`
+        :param payment_method:   PaymentMethod or str: one of `card` or `direct_debit`
         :param idempotency_key:   str: unique value to avoid duplicate POSTs
         """
-        data = payway_obj.to_dict()
-        if payment_method == "card":
-            payway_payment_method = CREDIT_CARD_PAYMENT_CHOICE
-        elif payment_method == "direct_debit":
-            payway_payment_method = BANK_ACCOUNT_PAYMENT_CHOICE
-        else:
+        try:
+            payment_method = PaymentMethod(payment_method)
+        except ValueError as exc:
             valid_payment_method_choices = ", ".join(VALID_PAYMENT_METHOD_CHOICES)
             raise PaywayError(
                 message=f"Invalid payment method. Must be one of {valid_payment_method_choices}",
                 code="INVALID_PAYMENT_METHOD",
-            )
-        data.update(
-            {
-                "paymentMethod": payway_payment_method,
-            },
-        )
+            ) from exc
+        data = payway_obj.to_dict()
+        if payment_method is PaymentMethod.CARD:
+            data["paymentMethod"] = CREDIT_CARD_PAYMENT_CHOICE
+        else:
+            data["paymentMethod"] = BANK_ACCOUNT_PAYMENT_CHOICE
         logger.info("Sending Create Token request to PayWay.")
         response = self.post_request(
             TOKEN_NO_REDIRECT,
@@ -155,7 +198,7 @@ class Client(CustomerRequest, TransactionRequest):
         errors = self._validate_response(response)
         if errors:
             return None, errors
-        return TokenResponse().from_dict(response.json()), errors
+        return TokenResponse.from_dict(response.json()), errors
 
     def create_card_token(
         self, card: PayWayCard, idempotency_key: str | None = None
@@ -164,7 +207,7 @@ class Client(CustomerRequest, TransactionRequest):
         :param card:    PayWayCard object represents a customer's credit card details
         :param idempotency_key:   str: unique value to avoid duplicate POSTs
         """
-        return self.create_token(card, "card", idempotency_key=idempotency_key)
+        return self.create_token(card, PaymentMethod.CARD, idempotency_key=idempotency_key)
 
     def create_bank_account_token(
         self, bank_account: BankAccount, idempotency_key: str | None = None
@@ -176,7 +219,7 @@ class Client(CustomerRequest, TransactionRequest):
         """
         return self.create_token(
             bank_account,
-            "direct_debit",
+            PaymentMethod.DIRECT_DEBIT,
             idempotency_key=idempotency_key,
         )
 
@@ -210,7 +253,7 @@ class Client(CustomerRequest, TransactionRequest):
         errors = self._validate_response(response)
         if errors:
             return None, errors
-        customer = PayWayCustomer().from_dict(response.json())
+        customer = PayWayCustomer.from_dict(response.json())
         return customer, errors
 
     def process_payment(
@@ -241,19 +284,19 @@ class Client(CustomerRequest, TransactionRequest):
             http_error_msg = f"{response.status_code} Client Error: {response.reason} for url: {response.url}"
             raise PaywayError(code=str(response.status_code), message=http_error_msg)
 
-        if response.status_code in [404, 422]:  # Documented PayWay errors in JSON
-            return PaymentError().from_dict(response.json())
+        if response.status_code in [HTTPStatus.NOT_FOUND, HTTPStatus.UNPROCESSABLE_ENTITY]:  # Documented PayWay errors in JSON
+            return PaymentError.from_dict(response.json())
 
-        if response.status_code == 500:
+        if response.status_code == HTTPStatus.INTERNAL_SERVER_ERROR:
             try:
                 errors = response.json()
-            except json.JSONDecodeError:
+            except json.JSONDecodeError as exc:
                 raise PaywayError(
                     code=str(response.status_code),
                     message="Internal server error",
-                )
+                ) from exc
             # Documented PayWay server errors in JSON
-            payway_error = ServerError().from_dict(errors)
+            payway_error = ServerError.from_dict(errors)
             message = payway_error.to_message()
             raise PaywayError(code=str(response.status_code), message=message)
 

{python_payway-0.0.7 → python_payway-0.0.8}/payway/constants.py

@@ -1,5 +1,14 @@
 from __future__ import annotations
 
+from enum import StrEnum
+from http import HTTPStatus
+
+
+class PaymentMethod(StrEnum):
+    CARD = "card"
+    DIRECT_DEBIT = "direct_debit"
+
+
 PAYWAY_API_URL = "https://api.payway.com.au/rest/v1"
 TOKEN_URL = PAYWAY_API_URL + "/single-use-tokens-redirect"
 TRANSACTION_URL = PAYWAY_API_URL + "/transactions"
@@ -65,7 +74,10 @@ EFT_RESPONSE_CODES = {
     "QS": "Transaction Successful",
     "QT": "Invalid currency",
     "QU": "Unknown Customer IP Address",
-    "QV": "Invalid Original Order Number specified for Refund, Refund amount exceeds capture amount, or Previous capture was not approved",
+    "QV": (
+        "Invalid Original Order Number specified for Refund, Refund amount exceeds capture amount, "
+        "or Previous capture was not approved"
+    ),
     "QW": "Invalid Reference Number",
     "QX": "Network Error has occurred",
     "QY": "Card Type Not Accepted",
@@ -138,18 +150,20 @@ DIRECT_DEBIT_CHOICES = (
     ("remittanceProcessingService", "Remittance Processing Service"),
 )
 PAYMENT_METHOD_CHOICES = OTHER_PAYMENT_CHOICES + DIRECT_DEBIT_CHOICES
-VALID_PAYMENT_METHOD_CHOICES = ["card", "direct_debit"]
+VALID_PAYMENT_METHOD_CHOICES = [method.value for method in PaymentMethod]
+# PayWay advises resending with the same Idempotency-Key on 429/503 only
+RETRYABLE_STATUS_CODES = frozenset({HTTPStatus.TOO_MANY_REQUESTS, HTTPStatus.SERVICE_UNAVAILABLE})
 PAYWAY_ERROR_RESPONSE_CODES = [
-    400,
-    401,
-    403,
-    405,
-    406,
-    407,
-    409,
-    410,
-    415,
-    429,
-    501,
-    503,
+    HTTPStatus.BAD_REQUEST,
+    HTTPStatus.UNAUTHORIZED,
+    HTTPStatus.FORBIDDEN,
+    HTTPStatus.METHOD_NOT_ALLOWED,
+    HTTPStatus.NOT_ACCEPTABLE,
+    HTTPStatus.PROXY_AUTHENTICATION_REQUIRED,
+    HTTPStatus.CONFLICT,
+    HTTPStatus.GONE,
+    HTTPStatus.UNSUPPORTED_MEDIA_TYPE,
+    HTTPStatus.TOO_MANY_REQUESTS,
+    HTTPStatus.NOT_IMPLEMENTED,
+    HTTPStatus.SERVICE_UNAVAILABLE,
 ]