feat: implement idempotency key generation for Stripe checkout sessions to prevent duplicate charges

Author: alanmaizon

love_backend/apps/payments/services.py

@@ -8,6 +8,8 @@
 
 All money-moving calls pass an idempotency key so retries never double-charge.
 """
+import hashlib
+import json
 import logging
 import os
 
@@ -93,6 +95,43 @@ def _application_fee_minor(amount_minor: int) -> int:
     return (amount_minor * settings.PLATFORM_FEE_BPS) // 10000
 
 
+def _checkout_idempotency_key(
+    donation: Donation,
+    *,
+    amount_minor: int,
+    currency: str,
+    destination: str,
+    fee_minor: int,
+    locale: str,
+    success_url: str,
+    cancel_url: str,
+) -> str:
+    """
+    Stripe idempotency keys are scoped to the exact request body.
+
+    Using only donation.pk collides in CI: e2e_prepare imports a fixed CSV so each
+    run often creates donation id=28, while Stripe remembers checkout-donation-28
+    from an earlier job with different session params (locale, URLs, fees).
+    """
+    payload = {
+        "donation_id": donation.pk,
+        "created_at": donation.created_at.isoformat() if donation.created_at else "",
+        "amount_minor": amount_minor,
+        "currency": currency,
+        "charity_id": donation.charity_id,
+        "destination": destination,
+        "fee_minor": fee_minor,
+        "locale": locale,
+        "success_url": success_url,
+        "cancel_url": cancel_url,
+        "customer_email": donation.donor_email or "",
+    }
+    digest = hashlib.sha256(
+        json.dumps(payload, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()[:24]
+    return f"checkout-donation-{donation.pk}-{digest}"
+
+
 def _resolve_payout_for_checkout(charity: Charity) -> PayoutAccount:
     """Return a payout row that exists in Stripe and can receive destination charges."""
     payout = getattr(charity, "payout_account", None)
@@ -166,11 +205,25 @@ def create_checkout_session(donation: Donation) -> str:
     if fee_minor > 0:
         payment_intent_data["application_fee_amount"] = fee_minor
 
+    locale = os.environ.get("STRIPE_CHECKOUT_LOCALE", "en")
+    success_url = f"{settings.FRONTEND_URL}/confirmation?session_id={{CHECKOUT_SESSION_ID}}"
+    cancel_url = f"{settings.FRONTEND_URL}/donate?canceled=1"
+    idempotency_key = _checkout_idempotency_key(
+        donation,
+        amount_minor=amount_minor,
+        currency=currency,
+        destination=payout.stripe_account_id,
+        fee_minor=fee_minor,
+        locale=locale,
+        success_url=success_url,
+        cancel_url=cancel_url,
+    )
+
     session = s.checkout.Session.create(
         mode="payment",
-        locale=os.environ.get("STRIPE_CHECKOUT_LOCALE", "en"),
-        success_url=f"{settings.FRONTEND_URL}/confirmation?session_id={{CHECKOUT_SESSION_ID}}",
-        cancel_url=f"{settings.FRONTEND_URL}/donate?canceled=1",
+        locale=locale,
+        success_url=success_url,
+        cancel_url=cancel_url,
         customer_email=donation.donor_email or None,
         line_items=[{
             "quantity": 1,
@@ -185,6 +238,6 @@ def create_checkout_session(donation: Donation) -> str:
         }],
         payment_intent_data=payment_intent_data,
         metadata={"donation_id": str(donation.id), "campaign": donation.campaign.slug if donation.campaign else ""},
-        idempotency_key=f"checkout-donation-{donation.id}",
+        idempotency_key=idempotency_key,
     )
     return session.url

love_backend/apps/payments/tests.py

@@ -507,6 +507,52 @@ def test_checkout_rejects_empty_email(self, create_session):
         create_session.assert_not_called()
 
 
+class CheckoutIdempotencyKeyTests(TestCase):
+    def setUp(self):
+        charity = Charity.objects.create(
+            name="C", slug="c-idem", verification_status=Charity.VERIFIED,
+        )
+        self.donation = Donation.objects.create(
+            charity=charity,
+            donor_name="D",
+            donor_email="[email protected]",
+            amount=Decimal("20.00"),
+            message="hi",
+        )
+
+    def _key(self, **overrides):
+        defaults = dict(
+            donation=self.donation,
+            amount_minor=2000,
+            currency="eur",
+            destination="acct_test",
+            fee_minor=0,
+            locale="en",
+            success_url="http://localhost:5173/confirmation?session_id={CHECKOUT_SESSION_ID}",
+            cancel_url="http://localhost:5173/donate?canceled=1",
+        )
+        defaults.update(overrides)
+        return services._checkout_idempotency_key(**defaults)
+
+    def test_same_params_same_key(self):
+        self.assertEqual(self._key(), self._key())
+
+    def test_locale_change_changes_key(self):
+        self.assertNotEqual(self._key(locale="en"), self._key(locale="es"))
+
+    def test_different_donation_rows_differ_even_if_pk_reused(self):
+        other = Donation.objects.create(
+            charity=self.donation.charity,
+            donor_name="D2",
+            donor_email="[email protected]",
+            amount=Decimal("20.00"),
+        )
+        self.assertNotEqual(
+            self._key(donation=self.donation),
+            self._key(donation=other),
+        )
+
+
 class ReconciliationTests(TestCase):
     def test_confirmed_without_ledger_flags_issue(self):
         donation = _make_donation()