BTI-977 - Add payment method: Point Of Sale

.gitignore

@@ -14,6 +14,16 @@ htmlcov/
 .DS_Store
 __pycache__/
 *.pyc
+__pycache__/
+*.pyo
+
+# local environment
 .env
+.venv/
+venv/
 
+# logs
 *.log
+
+# type checking
+.mypy_cache/

README.md

@@ -15,6 +15,7 @@
 - [Instant Refunds](#instant-refunds)
 - [eMandate](#emandate)
 - [Split Payments](#split-payments)
+- [Point of Sale (POS)](#point-of-sale-pos)
 - [Contribute](#contribute)
 - [Versioning](#versioning)
 - [Additional information](#additional-information)
@@ -281,6 +282,42 @@ marketplaces.create_solution("marketplaces").manual_transfer({
 A runnable demo of all six request types is in
 [`examples/marketplaces.py`](examples/marketplaces.py).
 
+### Point of Sale (POS)
+
+POS transactions are PIN-based in-store payments processed through a physical payment terminal.
+You initiate the transaction via API with the terminal's unique `TerminalID`; Buckaroo routes the
+request to that terminal, which prompts the customer to complete payment there. There's no
+redirect flow, every request is sent with a fixed `Channel: "Web"`, set internally by the SDK.
+
+The immediate response carries a pending/awaiting status. The final result, plus the printable
+`Ticket` receipt text for the customer, arrives later via push notification.
+
+```python
+response = payments.create_payment("pospayment", {
+    "currency": "EUR",
+    "amount": 0.01,
+    "invoice": "TestFactuur01",
+}).terminal_id("50000001").pay()
+
+print("key:", response.key)
+print("pending:", response.is_pending())
+```
+
+Parsing the push notification once the terminal completes the transaction push bodies wrap the
+transaction under a `Transaction` key, so unwrap it before handing it to `PaymentResponse`:
+
+```python
+from buckaroo.models.payment_response import PaymentResponse
+
+transaction = push_json["Transaction"]  # raw body your webhook endpoint received
+response = PaymentResponse({"data": transaction})
+
+ticket = response.get_service_parameter("Ticket")  # printable receipt text
+```
+
+See [`examples/pos_payment.py`](examples/pos_payment.py) for a runnable demo of both the `Pay`
+action and push-notification parsing.
+
 ### Contribute
 
 We really appreciate it when developers contribute to improve the Buckaroo plugins.

buckaroo/_buckaroo_client.py

@@ -1,3 +1,5 @@
+
+import logging
 from typing import Optional
 from .exceptions._authentication_error import AuthenticationError
 from .config.buckaroo_config import BuckarooConfig, create_config_from_mode
@@ -118,7 +120,13 @@ def confirm_credential(self) -> bool:
         try:
             response = self.http_client.get("/json/Transaction/Specification/ideal")
             return response.success
-        except Exception:
+        except Exception as e:
+            logging.warning(
+                "confirm_credential: unexpected error during credential check "
+                "(network issue or unexpected API response): %s",
+                e,
+                exc_info=True,
+            )
             return False
 
     def get_config_info(self) -> dict:

buckaroo/app.py

@@ -43,7 +43,7 @@ class BuckarooConfig:
     retry_attempts: int = 3
 
     @classmethod
-    def from_env(cls) -> "BuckarooConfig":
+    def from_env(cls) -> 'BuckarooConfig':
         """Create configuration from environment variables."""
         # Get log level from env
         log_level_str = os.getenv("BUCKAROO_LOG_LEVEL", "INFO").upper()
@@ -240,3 +240,4 @@ def __exit__(self, exc_type, exc_val, exc_tb):
                 self.logger.log_exception(exc_val, context={"context_manager": "exit"})
             else:
                 self.logger.log_debug("Exiting Buckaroo app context successfully")
+