feat(BTI-17): add PayPerEmail example and feature test

examples/payperemail.py

@@ -0,0 +1,72 @@
+#!/usr/bin/env python3
+"""Demo of the Pay Per Email payment method.
+
+Pay Per Email emails the shopper a payment link instead of returning an inline
+redirect. The demo drives the ``PaymentInvitation`` action, passing the customer
+identity (email, name, gender) as service parameters. Gated on
+``BUCKAROO_STORE_KEY`` / ``BUCKAROO_SECRET_KEY`` env vars.
+"""
+
+import os
+import sys
+
+# Add parent directory to Python path so the demo can import the SDK in-place.
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+
+from buckaroo.app import Buckaroo
+
+
+def _have_credentials() -> bool:
+    if not os.getenv("BUCKAROO_STORE_KEY") or not os.getenv("BUCKAROO_SECRET_KEY"):
+        print("⚠️  Set BUCKAROO_STORE_KEY and BUCKAROO_SECRET_KEY to run this demo")
+        return False
+    return True
+
+
+def demo_payment_invitation() -> None:
+    """Send a Pay Per Email invitation via the PaymentInvitation action."""
+    print("\n1. Pay Per Email invitation")
+    print("-" * 40)
+    if not _have_credentials():
+        return
+
+    try:
+        app = Buckaroo.from_env()
+
+        # ExpirationDate is optional; omit it to use the account default. Gender
+        # follows Buckaroo's codes: 1=Male, 2=Female, 0=Unknown, 9=N/A.
+        response = app.payments.create_payment(
+            "payperemail",
+            {
+                "currency": "EUR",
+                "amount": 42.00,
+                "description": "pay per email demo",
+                "invoice": "PPE-DEMO-001",
+                "return_url": "https://www.buckaroo.nl",
+                "return_url_cancel": "https://www.buckaroo.nl/cancel",
+                "return_url_error": "https://www.buckaroo.nl/error",
+                "return_url_reject": "https://www.buckaroo.nl/reject",
+                "service_parameters": {
+                    "CustomerEmail": "john@example.com",
+                    "CustomerFirstName": "John",
+                    "CustomerLastName": "Doe",
+                    "CustomerGender": "1",
+                    "ExpirationDate": "2026-12-31",
+                },
+            },
+        ).execute_action("PaymentInvitation")
+        print(f"   status.code={response.status.code.code}  key={response.key}")
+    except Exception as e:
+        print(f"   ❌ {e}")
+
+
+def main() -> None:
+    print("BUCKAROO SDK — PAY PER EMAIL DEMO")
+    print("=" * 60)
+    demo_payment_invitation()
+    print("\n" + "=" * 60)
+    print("done.")
+
+
+if __name__ == "__main__":
+    main()

tests/feature/payments/test_payperemail.py

@@ -0,0 +1,47 @@
+"""Feature test: PayPerEmail PaymentInvitation round-trip through the full stack.
+
+Pay Per Email emails the shopper a payment link instead of returning an inline
+redirect. The ``PaymentInvitation`` action carries the customer identity as
+service parameters; this pins that the action and those params reach the wire.
+"""
+
+from tests.support.helpers import Helpers
+from tests.support.mock_request import BuckarooMockRequest
+from tests.support.recording_mock import recorded_action, recorded_service_parameters
+
+
+class TestPayPerEmailFeature:
+    def test_payment_invitation_sends_action_and_customer_params(self, buckaroo, mock_strategy):
+        response_body = Helpers.success_response(
+            {
+                "Services": [
+                    {"Name": "payperemail", "Action": "PaymentInvitation", "Parameters": []}
+                ],
+                "ServiceCode": "payperemail",
+            }
+        )
+        mock_strategy.queue(BuckarooMockRequest.json("POST", "*/json/transaction", response_body))
+
+        response = buckaroo.payments.create_payment(
+            "payperemail",
+            Helpers.standard_payload(
+                invoice="INV-PPE-001",
+                description="Pay per email invite",
+                service_parameters={
+                    "CustomerEmail": "jane@example.com",
+                    "CustomerFirstName": "Jane",
+                    "CustomerLastName": "Doe",
+                    "CustomerGender": "1",
+                },
+            ),
+        ).execute_action("PaymentInvitation")
+
+        assert response.status.code.code == 190
+        assert response.key == response_body["Key"]
+        assert recorded_action(mock_strategy) == "PaymentInvitation"
+
+        sent = {p["Name"].lower(): p["Value"] for p in recorded_service_parameters(mock_strategy)}
+        assert sent["customeremail"] == "jane@example.com"
+        assert sent["customerfirstname"] == "Jane"
+        assert sent["customerlastname"] == "Doe"
+        assert sent["customergender"] == "1"