Add payment description and billing address support to Stripe

Enhances Stripe integration with better payment metadata and user experience:

**Payment Description:**
- Added payment.description to line items (visible in Stripe Dashboard)
- Added payment.description to PaymentIntent for recurring payments
- Improves payment tracking and customer support

**Billing Address Metadata:**
- Store all billing fields in session metadata for audit trail
- Includes: name, address, city, postcode, country, state, phone
- Available for accounting and support purposes

**Billing Address Pre-fill:**
- Pre-fills checkout form with address from Payment model
- Works seamlessly with Stripe's billing_address_collection='auto'
- When address is needed for tax compliance, form is already filled
- Minimal user friction, fast checkout experience
- Only applies to new sessions (not reusing existing Customers)

**Implementation Details:**
- Uses customer_details.address for checkout form pre-fill
- Maps Payment fields to Stripe address structure
- Only includes non-empty fields
- Relies on Stripe's default 'auto' address collection behavior
- Metadata stored regardless of whether collection is triggered

**Tests:**
- Line items with/without description
- Metadata storage (full, partial, none)
- Address pre-fill (full, partial, with existing customer)
- Recurring payments with description

All tests pass. Stripe provider coverage improved to 56%.

Author: PetrDlouhy

payments/stripe/providers.py

@@ -82,8 +82,10 @@ class StripeProviderV3(BasicProvider):
     :param use_token: Use instance.token instead of instance.pk in client_reference_id
     :param endpoint_secret: Endpoint Signing Secret.
     :param secure_endpoint: Validate the recieved data, useful for development.
-    :param recurring_payments: Enable wallet-based recurring payments (server-initiated).
-    :param store_payment_method: Store PaymentMethod for future use (auto-enabled if recurring_payments=True).
+    :param recurring_payments: Enable wallet-based recurring payments
+        (server-initiated).
+    :param store_payment_method: Store PaymentMethod for future use
+        (auto-enabled if recurring_payments=True).
     """
 
     form_class = BasePaymentForm
@@ -154,16 +156,54 @@ def create_session(self, payment):
             if payment.billing_email and "customer" not in session_data:
                 session_data.update({"customer_email": payment.billing_email})
 
-            # Patch session with billing name
+            # Pre-fill billing address in checkout form (only for new customers)
+            # This makes Stripe's billing_address_collection="auto" seamless:
+            # - If address is needed for tax, form is already filled
+            # - If address is not needed, pre-fill is harmless
+            if "customer" not in session_data:
+                address_data = {}
+                if payment.billing_address_1:
+                    address_data["line1"] = payment.billing_address_1
+                if payment.billing_address_2:
+                    address_data["line2"] = payment.billing_address_2
+                if payment.billing_city:
+                    address_data["city"] = payment.billing_city
+                if payment.billing_postcode:
+                    address_data["postal_code"] = payment.billing_postcode
+                if payment.billing_country_area:
+                    address_data["state"] = payment.billing_country_area
+                if payment.billing_country_code:
+                    address_data["country"] = payment.billing_country_code
+
+                if address_data:
+                    session_data["customer_details"] = {"address": address_data}
+
+            # Patch session with billing name and address in metadata
+            # Note: We rely on Stripe's default billing_address_collection="auto"
+            # which only collects address when needed for tax/compliance.
+            # The metadata below is stored for audit trail regardless.
+            metadata = {}
             if payment.billing_first_name or payment.billing_last_name:
-                session_data.update(
-                    {
-                        "metadata": {
-                            "customer_name": f"{payment.billing_first_name} "
-                            f"{payment.billing_last_name}"
-                        }
-                    }
+                metadata["customer_name"] = (
+                    f"{payment.billing_first_name} {payment.billing_last_name}".strip()
                 )
+            if payment.billing_address_1:
+                metadata["billing_address_1"] = payment.billing_address_1
+            if payment.billing_address_2:
+                metadata["billing_address_2"] = payment.billing_address_2
+            if payment.billing_city:
+                metadata["billing_city"] = payment.billing_city
+            if payment.billing_postcode:
+                metadata["billing_postcode"] = payment.billing_postcode
+            if payment.billing_country_code:
+                metadata["billing_country_code"] = payment.billing_country_code
+            if payment.billing_country_area:
+                metadata["billing_country_area"] = payment.billing_country_area
+            if payment.billing_phone:
+                metadata["billing_phone"] = str(payment.billing_phone)
+
+            if metadata:
+                session_data["metadata"] = metadata
             try:
                 return stripe.checkout.Session.create(**session_data)
             except stripe.error.StripeError as e:
@@ -187,7 +227,7 @@ def refund(self, payment, amount=None) -> int:
                     amount=self.convert_amount(payment.currency, to_refund),
                     reason="requested_by_customer",
                 )
-            except stripe.StripeError as e:
+            except stripe.error.StripeError as e:
                 raise PaymentError(e) from e
             else:
                 payment.attrs.refund = json.dumps(refund)
@@ -212,6 +252,10 @@ def get_line_items(self, payment) -> list:
         order_no = payment.token if self.use_token else payment.pk
         product_data = StripeProductData(name=f"Order #{order_no}")
 
+        # Add description if available
+        if payment.description:
+            product_data.description = payment.description
+
         price_data = StripePriceData(
             currency=payment.currency.lower(),
             unit_amount=self.convert_amount(payment.currency, payment.total),
@@ -246,7 +290,7 @@ def return_event_payload(self, request) -> Any:
             except ValueError as e:
                 # Invalid payload
                 raise e
-            except stripe.SignatureVerificationError as e:
+            except stripe.error.SignatureVerificationError as e:
                 # Invalid signature
                 raise e
         else:
@@ -265,17 +309,19 @@ def get_token_from_request(self, payment, request) -> str:
             except Exception as e:
                 raise PaymentError(
                     code=400,
-                    message="client_reference_id is not present in checkout.session event.",
+                    message=(
+                        "client_reference_id is not present in checkout.session event."
+                    ),
                 ) from e
 
         # payment_intent events don't have client_reference_id
-        # These are follow-up webhooks - we already processed the payment in checkout.session
-        # Return None to signal this should be skipped by static_callback
+        # These are follow-up webhooks - we already processed the payment
+        # in checkout.session. Return None to signal skip by static_callback
         return None
 
     def autocomplete_with_wallet(self, payment):
         """
-        Complete payment using stored PaymentMethod (server-initiated recurring payment).
+        Complete payment using stored PaymentMethod (server-initiated).
 
         This method charges a stored payment method without user interaction.
         Uses get_renew_data() to retrieve both payment_method_id and customer_id.
@@ -313,6 +359,10 @@ def autocomplete_with_wallet(self, payment):
                 },
             }
 
+            # Add description if available (visible in Stripe Dashboard)
+            if payment.description:
+                intent_params["description"] = payment.description
+
             intent = stripe.PaymentIntent.create(**intent_params)
 
             payment.transaction_id = intent.id
@@ -400,11 +450,11 @@ def erase_wallet(self, wallet):
 
     def _store_payment_method_from_session(self, payment, session_info):
         """
-        Extract and store PaymentMethod and Customer from successful Checkout Session.
+        Extract and store PaymentMethod and Customer from Checkout Session.
 
-        Called after payment is confirmed to store payment method for future recurring charges.
-        Extracts customer_id from PaymentIntent (created by Stripe Checkout) and passes
-        it to implementer via set_renew_token().
+        Called after payment is confirmed to store payment method for future
+        recurring charges. Extracts customer_id from PaymentIntent (created by
+        Stripe Checkout) and passes it to implementer via set_renew_token().
         """
         stripe.api_key = self.api_key
 
@@ -467,8 +517,9 @@ def process_data(self, payment, request):
 
             elif session_info["payment_status"] == "paid":
                 # Store PaymentMethod BEFORE changing status
-                # This is important because status change triggers signal that sets token_verified=True
-                # Use atomic transaction to prevent race conditions with concurrent webhooks
+                # This is important because status change triggers signal that
+                # sets token_verified=True. Use atomic transaction to prevent
+                # race conditions with concurrent webhooks
                 with transaction.atomic():
                     if self.store_payment_method and hasattr(
                         payment, "set_renew_token"

payments/stripe/test_recurring.py

@@ -5,7 +5,6 @@
 from __future__ import annotations
 
 from decimal import Decimal
-from unittest.mock import Mock
 from unittest.mock import patch
 
 import pytest
@@ -25,12 +24,12 @@
 class MockStripeIntent(dict):
     """
     JSON-serializable mock for Stripe PaymentIntent objects.
-    
+
     Stripe objects are dict-like and JSON-serializable. This mock replicates
     that behavior so tests can store intents in payment.attrs without
     triggering "Object of type Mock is not JSON serializable" errors.
     """
-    
+
     def __getattr__(self, key):
         try:
             value = self[key]
@@ -68,10 +67,12 @@ def test_autocomplete_with_wallet_success(self, mock_pi_create):
         )
 
         # Mock successful PaymentIntent
-        mock_pi_create.return_value = MockStripeIntent({
-            "id": "pi_test_123",
-            "status": "succeeded",
-        })
+        mock_pi_create.return_value = MockStripeIntent(
+            {
+                "id": "pi_test_123",
+                "status": "succeeded",
+            }
+        )
 
         # Execute recurring charge
         self.provider.autocomplete_with_wallet(payment)
@@ -123,14 +124,16 @@ def test_autocomplete_with_wallet_requires_3ds(self, mock_pi_create):
         )
 
         # Mock PaymentIntent requiring 3DS
-        mock_pi_create.return_value = MockStripeIntent({
-            "id": "pi_test_123",
-            "status": "requires_action",
-            "next_action": {
-                "type": "redirect_to_url",
-                "redirect_to_url": {"url": "https://stripe.com/3ds/authenticate"},
-            },
-        })
+        mock_pi_create.return_value = MockStripeIntent(
+            {
+                "id": "pi_test_123",
+                "status": "requires_action",
+                "next_action": {
+                    "type": "redirect_to_url",
+                    "redirect_to_url": {"url": "https://stripe.com/3ds/authenticate"},
+                },
+            }
+        )
 
         # Should raise RedirectNeeded
         with pytest.raises(RedirectNeeded) as exc_info:
@@ -149,11 +152,13 @@ def test_autocomplete_with_wallet_card_declined(self, mock_pi_create):
         )
 
         # Mock declined payment
-        mock_pi_create.return_value = MockStripeIntent({
-            "id": "pi_test_123",
-            "status": "requires_payment_method",
-            "last_payment_error": {"message": "Your card was declined"},
-        })
+        mock_pi_create.return_value = MockStripeIntent(
+            {
+                "id": "pi_test_123",
+                "status": "requires_payment_method",
+                "last_payment_error": {"message": "Your card was declined"},
+            }
+        )
 
         # Execute - should not raise
         self.provider.autocomplete_with_wallet(payment)
@@ -206,3 +211,55 @@ def test_autocomplete_with_wallet_no_token(self):
                 self.provider.autocomplete_with_wallet(payment)
 
             assert "No payment method token" in str(exc_info.value)
+
+    @patch("stripe.PaymentIntent.create")
+    def test_autocomplete_with_wallet_includes_description(self, mock_pi_create):
+        """Payment description should be included in PaymentIntent."""
+        payment = Payment.objects.create(
+            variant="stripe-recurring",
+            total=Decimal("75.00"),
+            currency="USD",
+            wallet=self.wallet,
+            description="Monthly subscription renewal - Premium Plan",
+        )
+
+        mock_pi_create.return_value = MockStripeIntent(
+            {
+                "id": "pi_test_desc",
+                "status": "succeeded",
+            }
+        )
+
+        self.provider.autocomplete_with_wallet(payment)
+
+        # Verify description was included in PaymentIntent creation
+        mock_pi_create.assert_called_once()
+        call_kwargs = mock_pi_create.call_args[1]
+        assert (
+            call_kwargs["description"] == "Monthly subscription renewal - Premium Plan"
+        )
+
+    @patch("stripe.PaymentIntent.create")
+    def test_autocomplete_with_wallet_without_description(self, mock_pi_create):
+        """PaymentIntent should work without description (backward compatibility)."""
+        payment = Payment.objects.create(
+            variant="stripe-recurring",
+            total=Decimal("25.00"),
+            currency="USD",
+            wallet=self.wallet,
+            description="",  # Empty description
+        )
+
+        mock_pi_create.return_value = MockStripeIntent(
+            {
+                "id": "pi_test_no_desc",
+                "status": "succeeded",
+            }
+        )
+
+        self.provider.autocomplete_with_wallet(payment)
+
+        # Verify description was not included when empty
+        mock_pi_create.assert_called_once()
+        call_kwargs = mock_pi_create.call_args[1]
+        assert "description" not in call_kwargs