AI Deliberation Transcript

Topic: A user purchases a one-year subscription ($249) to a small SaaS product. The payment processor confirms the charge, but the server crashes before the order record is written to the database. The user sees a blank page. They check their bank account and see the charge. They have no confirmation email and no account access. The support team is two people.

Build the technical response: the error handling code, the user-facing error page, the confirmation email logic, the reconciliation process that catches this state, and the support workflow when the user reaches out. Write it in Python as working code with comments. Structure the response however you think best serves the problem.

Date: 2026-03-30 17:52

Rounds: 1

Mode: Conversation

Active Models: codex

Context Mode: clean

Methodology

Models

• codex: gpt-5.4

System Prompt (per model)

You are codex, alongside a human facilitator.
Speak honestly and in your own voice. No format requirements or word limits.

Context Preamble (sent with first turn)

No preamble — clean context mode

Transcript

[HUMAN] 2026-03-30 17:51:07 A user purchases a one-year subscription ($249) to a small SaaS product. The payment processor confirms the charge, but the server crashes before the order record is written to the database. The user sees a blank page. They check their bank account and see the charge. They have no confirmation email and no account access. The support team is two people.

Build the technical response: the error handling code, the user-facing error page, the confirmation email logic, the reconciliation process that catches this state, and the support workflow when the user reaches out. Write it in Python as working code with comments. Structure the response however you think best serves the problem.

[GPT-5.4] 2026-03-30 17:52:33 Below is a compact but working Python example that covers the full response to this failure mode:

• checkout request handling
• idempotent order creation
• graceful user-facing error page when payment succeeded but provisioning did not
• confirmation email logic
• webhook handling
• reconciliation job that finds “charged but not provisioned”
• support workflow for a 2-person team

I’ll use FastAPI + SQLAlchemy-style code with an in-memory SQLite database so the logic is runnable and easy to inspect. The “payment processor” and “email sender” are mocked, but the flow is realistic.

Design goals

The main principle is:

Never assume the browser request is the source of truth after a successful charge.
If payment succeeds, we need independent recovery paths:

1. Immediate path: write order + provision account in the request.
2. Webhook path: payment processor event can repair missing state.
3. Reconciliation path: periodic job finds charges with no local order.
4. Support path: support can search by email/payment id and safely recover.

To make this reliable:

• every checkout has a stable checkout_id
• every payment has a unique payment_intent_id
• orders are created idempotently
• provisioning is retryable
• confirmation email is tied to order state, not just browser success
• support never manually “guesses”; they run a safe recovery operation

Working code

from __future__ import annotations

import enum
import secrets
import traceback
from datetime import datetime, timedelta
from typing import Optional, Dict, List

from fastapi import FastAPI, HTTPException, Request, Form
from fastapi.responses import HTMLResponse, JSONResponse
from pydantic import BaseModel
from sqlalchemy import (
    create_engine,
    Column,
    String,
    Integer,
    DateTime,
    Enum,
    Boolean,
    ForeignKey,
    Text,
    UniqueConstraint,
)
from sqlalchemy.orm import declarative_base, sessionmaker, relationship, Session

# ============================================================
# Database setup
# ============================================================

Base = declarative_base()
engine = create_engine("sqlite:///./saas_demo.db", echo=False, future=True)
SessionLocal = sessionmaker(bind=engine, expire_on_commit=False)

ANNUAL_PLAN_PRICE_CENTS = 24900
ANNUAL_PLAN_NAME = "Annual Subscription"
PRODUCT_NAME = "TinySaaS"


# ============================================================
# Models
# ============================================================

class CheckoutStatus(str, enum.Enum):
    initiated = "initiated"
    payment_succeeded = "payment_succeeded"
    completed = "completed"
    recovery_needed = "recovery_needed"
    failed = "failed"


class OrderStatus(str, enum.Enum):
    pending = "pending"
    active = "active"
    failed = "failed"
    refunded = "refunded"


class EmailStatus(str, enum.Enum):
    pending = "pending"
    sent = "sent"
    failed = "failed"


class SupportTicketStatus(str, enum.Enum):
    open = "open"
    investigating = "investigating"
    resolved = "resolved"


class CheckoutAttempt(Base):
    """
    Tracks a checkout attempt from the moment the user starts payment.
    This is critical because if the browser request crashes after charge,
    we still have a local artifact we can reconcile against.
    """
    __tablename__ = "checkout_attempts"

    id = Column(String, primary_key=True)  # stable checkout_id
    email = Column(String, nullable=False, index=True)
    plan = Column(String, nullable=False)
    amount_cents = Column(Integer, nullable=False)
    status = Column(Enum(CheckoutStatus), nullable=False, default=CheckoutStatus.initiated)
    payment_intent_id = Column(String, nullable=True, unique=True, index=True)
    last_error = Column(Text, nullable=True)
    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
    updated_at = Column(DateTime, default=datetime.utcnow, nullable=False)

    order = relationship("Order", back_populates="checkout", uselist=False)


class Order(Base):
    """
    Canonical local subscription/order record.
    Idempotency is enforced by uniqueness on payment_intent_id and checkout_id.
    """
    __tablename__ = "orders"
    __table_args__ = (
        UniqueConstraint("payment_intent_id", name="uq_orders_payment_intent_id"),
        UniqueConstraint("checkout_id", name="uq_orders_checkout_id"),
    )

    id = Column(String, primary_key=True)
    checkout_id = Column(String, ForeignKey("checkout_attempts.id"), nullable=False)
    email = Column(String, nullable=False, index=True)
    plan = Column(String, nullable=False)
    amount_cents = Column(Integer, nullable=False)
    status = Column(Enum(OrderStatus), nullable=False, default=OrderStatus.pending)
    payment_intent_id = Column(String, nullable=False, index=True)
    account_id = Column(String, nullable=True, index=True)
    confirmation_email_status = Column(Enum(EmailStatus), nullable=False, default=EmailStatus.pending)
    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
    activated_at = Column(DateTime, nullable=True)

    checkout = relationship("CheckoutAttempt", back_populates="order")


class Account(Base):
    """
    User account/subscription access. In many systems this could be a user row
    plus entitlement rows; kept simple here.
    """
    __tablename__ = "accounts"

    id = Column(String, primary_key=True)
    email = Column(String, nullable=False, unique=True, index=True)
    password_setup_token = Column(String, nullable=True)
    subscription_active = Column(Boolean, default=False, nullable=False)
    subscription_plan = Column(String, nullable=True)
    subscription_renewal_date = Column(DateTime, nullable=True)
    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)


class EmailLog(Base):
    __tablename__ = "email_logs"

    id = Column(String, primary_key=True)
    to_email = Column(String, nullable=False, index=True)
    subject = Column(String, nullable=False)
    body = Column(Text, nullable=False)
    status = Column(Enum(EmailStatus), nullable=False)
    related_order_id = Column(String, nullable=True, index=True)
    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
    error = Column(Text, nullable=True)


class SupportTicket(Base):
    __tablename__ = "support_tickets"

    id = Column(String, primary_key=True)
    email = Column(String, nullable=False, index=True)
    subject = Column(String, nullable=False)
    message = Column(Text, nullable=False)
    status = Column(Enum(SupportTicketStatus), nullable=False, default=SupportTicketStatus.open)
    linked_payment_intent_id = Column(String, nullable=True, index=True)
    linked_order_id = Column(String, nullable=True, index=True)
    resolution_notes = Column(Text, nullable=True)
    created_at = Column(DateTime, default=datetime.utcnow, nullable=False)
    updated_at = Column(DateTime, default=datetime.utcnow, nullable=False)


Base.metadata.create_all(bind=engine)


# ============================================================
# Mock payment processor
# ============================================================

class PaymentIntent(BaseModel):
    id: str
    amount_cents: int
    email: str
    succeeded: bool
    metadata: Dict[str, str]
    created_at: datetime


class FakePaymentProcessor:
    """
    Simulates a payment processor that can:
    - create charges
    - list successful charges
    - retrieve a charge by id

    In reality this would be Stripe, Adyen, Braintree, etc.
    """
    def __init__(self):
        self._charges: Dict[str, PaymentIntent] = {}

    def charge(self, email: str, amount_cents: int, metadata: Dict[str, str]) -> PaymentIntent:
        pid = "pi_" + secrets.token_hex(8)
        payment = PaymentIntent(
            id=pid,
            amount_cents=amount_cents,
            email=email,
            succeeded=True,
            metadata=metadata,
            created_at=datetime.utcnow(),
        )
        self._charges[pid] = payment
        return payment

    def retrieve(self, payment_intent_id: str) -> Optional[PaymentIntent]:
        return self._charges.get(payment_intent_id)

    def list_successful_since(self, since: datetime) -> List[PaymentIntent]:
        return [
            p for p in self._charges.values()
            if p.succeeded and p.created_at >= since
        ]


payment_processor = FakePaymentProcessor()


# ============================================================
# Mock email sender
# ============================================================

def send_email(db: Session, to_email: str, subject: str, body: str, related_order_id: Optional[str] = None) -> None:
    """
    Mock sender. In production, this would call SES, Postmark, Resend, etc.
    We log every attempt so support can see whether an email was actually sent.
    """
    log = EmailLog(
        id="eml_" + secrets.token_hex(8),
        to_email=to_email,
        subject=subject,
        body=body,
        status=EmailStatus.sent,
        related_order_id=related_order_id,
    )
    db.add(log)
    db.commit()


# ============================================================
# Core business logic
# ============================================================

def now_utc() -> datetime:
    return datetime.utcnow()


def generate_id(prefix: str) -> str:
    return f"{prefix}_{secrets.token_hex(8)}"


def create_checkout_attempt(db: Session, email: str) -> CheckoutAttempt:
    checkout = CheckoutAttempt(
        id=generate_id("chk"),
        email=email,
        plan=ANNUAL_PLAN_NAME,
        amount_cents=ANNUAL_PLAN_PRICE_CENTS,
        status=CheckoutStatus.initiated,
        created_at=now_utc(),
        updated_at=now_utc(),
    )
    db.add(checkout)
    db.commit()
    return checkout


def get_or_create_account(db: Session, email: str) -> Account:
    account = db.query(Account).filter(Account.email == email).first()
    if account:
        return account

    account = Account(
        id=generate_id("acct"),
        email=email,
        password_setup_token=secrets.token_urlsafe(24),
        subscription_active=False,
        created_at=now_utc(),
    )
    db.add(account)
    db.commit()
    return account


def build_confirmation_email(order: Order, account: Account) -> tuple[str, str]:
    setup_url = f"https://example.com/setup-password?token={account.password_setup_token}"
    login_url = "https://example.com/login"
    subject = f"Your {PRODUCT_NAME} subscription is active"
    body = f"""
Hi,

Thanks for your purchase of the {ANNUAL_PLAN_NAME} (${order.amount_cents / 100:.2f}).

Your subscription is now active for: {order.email}

If this is your first time, set your password here:
{setup_url}

If you already have an account, log in here:
{login_url}

Payment reference: {order.payment_intent_id}
Order ID: {order.id}

If anything looks wrong, reply to this email and our small support team will help.

— {PRODUCT_NAME}
""".strip()
    return subject, body


def send_confirmation_email_if_needed(db: Session, order: Order) -> None:
    if order.confirmation_email_status == EmailStatus.sent:
        return

    account = db.query(Account).filter(Account.id == order.account_id).first()
    if not account:
        raise RuntimeError("Cannot send confirmation email without an account")

    subject, body = build_confirmation_email(order, account)
    send_email(db, order.email, subject, body, related_order_id=order.id)
    order.confirmation_email_status = EmailStatus.sent
    db.commit()


def provision_order_idempotently(db: Session, checkout: CheckoutAttempt) -> Order:
    """
    This is the heart of the recovery strategy.

    Given a checkout that has a successful payment_intent_id, ensure:
    - there is exactly one order
    - there is an account
    - subscription is active
    - confirmation email is sent

    Safe to call multiple times from:
    - checkout request handler
    - webhook
    - reconciliation job
    - support tool
    """
    if not checkout.payment_intent_id:
        raise RuntimeError("Cannot provision without payment_intent_id")

    existing = db.query(Order).filter(Order.payment_intent_id == checkout.payment_intent_id).first()
    if existing:
        # Ensure downstream state is also repaired if partially missing.
        account = db.query(Account).filter(Account.id == existing.account_id).first()
        if not account:
            account = get_or_create_account(db, existing.email)
            existing.account_id = account.id

        if not account.subscription_active:
            account.subscription_active = True
            account.subscription_plan = existing.plan
            account.subscription_renewal_date = now_utc() + timedelta(days=365)

        if existing.status != OrderStatus.active:
            existing.status = OrderStatus.active
            existing.activated_at = now_utc()

        checkout.status = CheckoutStatus.completed
        checkout.updated_at = now_utc()
        db.commit()

        send_confirmation_email_if_needed(db, existing)
        return existing

    # Create account and order from scratch.
    account = get_or_create_account(db, checkout.email)
    account.subscription_active = True
    account.subscription_plan = checkout.plan
    account.subscription_renewal_date = now_utc() + timedelta(days=365)

    order = Order(
        id=generate_id("ord"),
        checkout_id=checkout.id,
        email=checkout.email,
        plan=checkout.plan,
        amount_cents=checkout.amount_cents,
        status=OrderStatus.active,
        payment_intent_id=checkout.payment_intent_id,
        account_id=account.id,
        activated_at=now_utc(),
        confirmation_email_status=EmailStatus.pending,
    )
    db.add(order)

    checkout.status = CheckoutStatus.completed
    checkout.updated_at = now_utc()
    db.commit()

    send_confirmation_email_if_needed(db, order)
    return order


def mark_checkout_error(db: Session, checkout: CheckoutAttempt, exc: Exception) -> None:
    checkout.status = CheckoutStatus.recovery_needed
    checkout.last_error = "".join(traceback.format_exception_only(type(exc), exc)).strip()
    checkout.updated_at = now_utc()
    db.commit()


def recover_checkout_by_payment_intent(db: Session, payment_intent_id: str) -> Order:
    """
    Used by webhook, reconciliation, and support.
    """
    checkout = db.query(CheckoutAttempt).filter(
        CheckoutAttempt.payment_intent_id == payment_intent_id
    ).first()

    payment = payment_processor.retrieve(payment_intent_id)
    if not payment or not payment.succeeded:
        raise RuntimeError("No successful payment found for payment_intent_id")

    if not checkout:
        # This means payment succeeded but even the local checkout row is missing.
        # We still recover by reconstructing enough local state from processor metadata.
        checkout_id = payment.metadata.get("checkout_id", generate_id("chk"))
        checkout = CheckoutAttempt(
            id=checkout_id,
            email=payment.email,
            plan=ANNUAL_PLAN_NAME,
            amount_cents=payment.amount_cents,
            status=CheckoutStatus.payment_succeeded,
            payment_intent_id=payment.id,
            created_at=payment.created_at,
            updated_at=now_utc(),
            last_error="Recovered from payment processor without original local checkout row",
        )
        db.add(checkout)
        db.commit()

    if checkout.status in [CheckoutStatus.initiated, CheckoutStatus.recovery_needed, CheckoutStatus.payment_succeeded]:
        checkout.status = CheckoutStatus.payment_succeeded
        checkout.updated_at = now_utc()
        db.commit()

    return provision_order_idempotently(db, checkout)


# ============================================================
# FastAPI app
# ============================================================

app = FastAPI(title="TinySaaS Checkout Recovery Demo")


@app.get("/", response_class=HTMLResponse)
def home():
    return """
    <h1>TinySaaS Demo</h1>
    <p>Annual subscription: $249/year</p>
    <form method="post" action="/start-checkout">
      <input name="email" type="email" placeholder="[email protected]" required />
      <button type="submit">Buy annual plan</button>
    </form>
    <p>Use /start-checkout?crash_after_charge=true to simulate the failure mode.</p>
    """


@app.post("/start-checkout", response_class=HTMLResponse)
def start_checkout(email: str = Form(...), crash_after_charge: bool = False):
    """
    Simulates checkout where payment can succeed and the app can crash before order write.
    """
    db = SessionLocal()
    checkout = create_checkout_attempt(db, email)

    try:
        # Charge the card. This part succeeds.
        payment = payment_processor.charge(
            email=email,
            amount_cents=ANNUAL_PLAN_PRICE_CENTS,
            metadata={"checkout_id": checkout.id, "plan": ANNUAL_PLAN_NAME},
        )

        checkout.payment_intent_id = payment.id
        checkout.status = CheckoutStatus.payment_succeeded
        checkout.updated_at = now_utc()
        db.commit()

        # Simulate the dangerous crash after successful charge but before order creation.
        if crash_after_charge:
            raise RuntimeError("Simulated server crash after payment success, before order write")

        # Normal happy path.
        order = provision_order_idempotently(db, checkout)

        return f"""
        <h1>Payment successful</h1>
        <p>Thanks! Your subscription is active.</p>
        <p>Order ID: {order.id}</p>
        <p>A confirmation email was sent to {order.email}.</p>
        """

    except Exception as exc:
        mark_checkout_error(db, checkout, exc)

        # Important: do not say "payment failed" because payment may have succeeded.
        # Give the user a concrete next step and a recovery identifier.
        return HTMLResponse(
            content=render_recovery_page(
                email=email,
                checkout_id=checkout.id,
                payment_intent_id=checkout.payment_intent_id,
            ),
            status_code=500,
        )
    finally:
        db.close()


def render_recovery_page(email: str, checkout_id: str, payment_intent_id: Optional[str]) -> str:
    payment_ref_html = f"<p><strong>Payment reference:</strong> {payment_intent_id}</p>" if payment_intent_id else ""
    return f"""
    <html>
      <head><title>We’re checking your purchase</title></head>
      <body style="font-family: sans-serif; max-width: 700px; margin: 40px auto;">
        <h1>We’re checking your purchase</h1>
        <p>
          Your payment may have gone through, but we hit a problem finishing account setup.
          Please do <strong>not</strong> purchase again right now.
        </p>
        <p>
          If your card or bank shows a charge, we’ll use that payment to activate your subscription.
        </p>
        <p><strong>Email:</strong> {email}</p>
        <p><strong>Reference:</strong> {checkout_id}</p>
        {payment_ref_html}
        <p>
          We’re automatically checking for successful payments and will email you as soon as your account is ready.
        </p>
        <p>
          If you want help now, contact support and include the reference above:
          <a href="/support">support</a>
        </p>
      </body>
    </html>
    """


@app.post("/webhook/payment-succeeded")
def payment_succeeded_webhook(payment_intent_id: str):
    """
    Simulated webhook endpoint.
    In production this should verify signatures and be retried by the processor.
    """
    db = SessionLocal()
    try:
        order = recover_checkout_by_payment_intent(db, payment_intent_id)
        return {"ok": True, "order_id": order.id}
    except Exception as exc:
        return JSONResponse(status_code=500, content={"ok": False, "error": str(exc)})
    finally:
        db.close()


@app.get("/support", response_class=HTMLResponse)
def support_form():
    return """
    <h1>Contact support</h1>
    <form method="post" action="/support">
      <input name="email" type="email" placeholder="[email protected]" required /><br/><br/>
      <input name="payment_intent_id" type="text" placeholder="Payment reference (optional)" /><br/><br/>
      <input name="subject" type="text" value="Charged but no account access" required /><br/><br/>
      <textarea name="message" placeholder="Describe what happened" rows="8" cols="60"></textarea><br/><br/>
      <button type="submit">Send</button>
    </form>
    """


@app.post("/support", response_class=HTMLResponse)
def submit_support(
    email: str = Form(...),
    subject: str = Form(...),
    message: str = Form(...),
    payment_intent_id: str = Form(default=""),
):
    db = SessionLocal()
    try:
        ticket = SupportTicket(
            id=generate_id("sup"),
            email=email,
            subject=subject,
            message=message,
            status=SupportTicketStatus.open,
            linked_payment_intent_id=payment_intent_id or None,
            created_at=now_utc(),
            updated_at=now_utc(),
        )
        db.add(ticket)
        db.commit()

        # Small-team workflow:
        # Try an immediate safe auto-recovery if a payment reference is present.
        resolution = ""
        if payment_intent_id:
            try:
                order = recover_checkout_by_payment_intent(db, payment_intent_id)
                ticket.status = SupportTicketStatus.resolved
                ticket.linked_order_id = order.id
                ticket.resolution_notes = f"Auto-recovered order {order.id} from support intake."
                ticket.updated_at = now_utc()
                db.commit()
                resolution = f"""
                <p>Good news: we found your payment and restored access.</p>
                <p>Order ID: {order.id}</p>
                <p>A confirmation email has been sent to {email}.</p>
                """
            except Exception as exc:
                ticket.status = SupportTicketStatus.investigating
                ticket.resolution_notes = f"Needs manual review. Auto-recovery failed: {exc}"
                ticket.updated_at = now_utc()
                db.commit()

        if not resolution:
            resolution = f"""
            <p>Thanks — your message has been received.</p>
            <p>Ticket ID: {ticket.id}</p>
            <p>Our small support team will review your payment and get you access or issue a refund if needed.</p>
            """

        return f"<h1>Support</h1>{resolution}"
    finally:
        db.close()


# ============================================================
# Reconciliation job
# ============================================================

def reconcile_successful_payments(hours_back: int = 48) -> List[str]:
    """
    Periodic job:
    - ask payment processor for successful charges in recent period
    - ensure every successful charge has a local order
    - repair missing order/account/email state

    Returns notes for logging/monitoring.
    """
    db = SessionLocal()
    notes = []
    try:
        since = now_utc() - timedelta(hours=hours_back)
        payments = payment_processor.list_successful_since(since)

        for payment in payments:
            existing_order = db.query(Order).filter(
                Order.payment_intent_id == payment.id
            ).first()

            if existing_order:
                # Also heal partial state if needed.
                checkout = db.query(CheckoutAttempt).filter(
                    CheckoutAttempt.payment_intent_id == payment.id
                ).first()
                if checkout:
                    provision_order_idempotently(db, checkout)
                notes.append(f"OK: payment {payment.id} already linked to order {existing_order.id}")
                continue

            # Missing order: this is the exact bug we want to catch.
            try:
                order = recover_checkout_by_payment_intent(db, payment.id)
                notes.append(f"RECOVERED: payment {payment.id} -> order {order.id}")
            except Exception as exc:
                notes.append(f"FAILED: payment {payment.id} could not be reconciled: {exc}")

        return notes
    finally:
        db.close()


# ============================================================
# Support/admin helpers
# ============================================================

def support_lookup(db: Session, email: Optional[str] = None, payment_intent_id: Optional[str] = None) -> dict:
    """
    Simple support lookup screen logic. Gives support a single place to inspect state.
    """
    result = {
        "accounts": [],
        "orders": [],
        "checkouts": [],
        "payments": [],
        "emails": [],
        "tickets": [],
    }

    if email:
        result["accounts"] = db.query(Account).filter(Account.email == email).all()
        result["orders"] = db.query(Order).filter(Order.email == email).all()
        result["checkouts"] = db.query(CheckoutAttempt).filter(CheckoutAttempt.email == email).all()
        result["emails"] = db.query(EmailLog).filter(EmailLog.to_email == email).all()
        result["tickets"] = db.query(SupportTicket).filter(SupportTicket.email == email).all()

    if payment_intent_id:
        payment = payment_processor.retrieve(payment_intent_id)
        if payment:
            result["payments"].append(payment)
        result["orders"].extend(
            db.query(Order).filter(Order.payment_intent_id == payment_intent_id).all()
        )
        result["checkouts"].extend(
            db.query(CheckoutAttempt).filter(CheckoutAttempt.payment_intent_id == payment_intent_id).all()
        )
        result["tickets"].extend(
            db.query(SupportTicket).filter(SupportTicket.linked_payment_intent_id == payment_intent_id).all()
        )

    return result


def support_recover_or_refund(db: Session, payment_intent_id: str, refund_if_unrecoverable: bool = False) -> str:
    """
    Safe support action:
    1. Try recovery first.
    2. Only refund if policy requires and recovery isn't possible.

    Since this is a mock processor, actual refund logic is omitted.
    """
    try:
        order = recover_checkout_by_payment_intent(db, payment_intent_id)
        return f"Recovered successfully. Order {order.id} is active."
    except Exception as exc:
        if refund_if_unrecoverable:
            # In a real processor integration, we'd issue a refund call here.
            return f"Recovery failed ({exc}). Refund should be issued manually/in processor."
        return f"Recovery failed: {exc}"


# ============================================================
# Manual demo runner
# ============================================================

if __name__ == "__main__":
    # Demonstrate the exact failure mode and recovery.
    db = SessionLocal()

    # 1) Create checkout and simulate successful payment + crash
    checkout = create_checkout_attempt(db, "[email protected]")
    payment = payment_processor.charge(
        email=checkout.email,
        amount_cents=ANNUAL_PLAN_PRICE_CENTS,
        metadata={"checkout_id": checkout.id},
    )
    checkout.payment_intent_id = payment.id
    checkout.status = CheckoutStatus.payment_succeeded
    db.commit()

    # Simulate crash before order creation
    mark_checkout_error(db, checkout, RuntimeError("Simulated crash after charge"))

    print("Before reconciliation:")
    print("Orders:", db.query(Order).count())
    print("Checkouts needing recovery:", db.query(CheckoutAttempt).filter(
        CheckoutAttempt.status == CheckoutStatus.recovery_needed
    ).count())

    db.close()

    # 2) Reconciliation repairs it
    notes = reconcile_successful_payments()
    print("\nReconciliation notes:")
    for n in notes:
        print("-", n)

    db = SessionLocal()
    print("\nAfter reconciliation:")
    print("Orders:", db.query(Order).count())
    print("Accounts:", db.query(Account).count())
    print("Emails sent:", db.query(EmailLog).count())

    for order in db.query(Order).all():
        print(
            f"Order={order.id}, email={order.email}, status={order.status}, "
            f"payment_intent_id={order.payment_intent_id}, email_status={order.confirmation_email_status}"
        )
    db.close()

What this code is doing

1. Error handling in checkout

In start_checkout():

• a CheckoutAttempt is written before charging
• the payment processor charge succeeds
• payment_intent_id is saved immediately
• if the app crashes after that, we mark the checkout as recovery_needed
• the user sees a recovery page, not a misleading “payment failed” message

That page explicitly says:

• your payment may have gone through
• do not pay again
• here is your reference
• we are automatically checking and will email you

That is much better than a blank page.

2. User-facing error page

render_recovery_page(...) provides:

• reassurance without promising a false outcome
• request not to retry payment
• checkout reference
• payment reference if available
• support path

This matters because the user’s first fear is:
“Did I just get charged for nothing?”

The page should reduce duplicate purchases and support load.

3. Confirmation email logic

send_confirmation_email_if_needed() only sends after:

• order exists
• account exists
• subscription is active

That prevents sending a “welcome, you’re active” email for a half-finished state.

It is idempotent: - if already sent, do nothing - if recovery happens later, it still sends exactly once

4. Reconciliation process

reconcile_successful_payments() is the safety net.

It: - pulls successful charges from the processor over a recent time window - checks whether each one has a local order - if not, reconstructs state from payment metadata and provisions the order

This is how the system catches: - payment succeeded - browser flow died - webhook failed - support has not been contacted yet

For a small team, this job is essential.
Run it every 5–15 minutes, plus perhaps a deeper daily sweep.

5. Webhook repair path

/webhook/payment-succeeded calls recover_checkout_by_payment_intent(...).

This is important because payment processors will usually retry webhooks automatically, so even if your checkout request crashed, the processor can still notify you later and let you recover.

In production: - verify webhook signatures - make webhook handling idempotent - return 2xx only after durable processing or enqueueing

6. Support workflow

For a 2-person team, support needs a single safe playbook.

The code gives that via: - support_lookup(...) - support_recover_or_refund(...) - auto-recovery during support form submission if a payment reference is provided

Recommended workflow:

When the user writes in saying “I was charged but got no access”

1. Search by email and payment reference.
2. Check:
3. successful payment exists?
4. order exists?
5. account exists?
6. confirmation email sent?
7. Run idempotent recovery using payment reference.
8. If recovery succeeds:
9. confirm account is active
10. resend confirmation/setup email if needed
11. resolve ticket
12. If recovery fails and payment is verified:
13. escalate for manual investigation
14. refund if policy/SLA requires and recovery cannot be completed promptly

Because recovery is idempotent, support can safely click it more than once.

Practical production improvements

If you were hardening this for real use, I’d add:

Stronger idempotency

• store a processor idempotency key on charge creation
• use a unique database constraint on payment_intent_id
• maybe also a unique processor customer+invoice relation if available

Outbox pattern for emails

Instead of sending email directly in the request: - write an email_outbox row in the same DB transaction as order activation - background worker sends and retries - ensures “order active but email missing” is also recoverable

Better transaction boundaries

A production version would likely: - persist charge result - queue provisioning - return a processing page rather than doing all work inline in the request

Observability

Add: - structured logs with checkout_id, payment_intent_id, order_id - alert on “successful payment with no order after N minutes” - dashboard for recovery-needed checkouts

Support tooling

Give support a tiny internal page with: - search by email / payment id - current state summary - “Recover access” button - “Resend confirmation email” button - “Refund” button if authorized

Refund policy

Decide and document: - if user is charged and unresolved after X hours, refund automatically? - if duplicate charges happen, refund duplicates automatically?

Why this architecture fits the scenario

The failure described is exactly the kind of thing that hurts trust:

• user sees bank charge
• no email
• no login
• blank page

The correct technical response is not just “try/except around checkout.”
It requires a multi-path recovery system:

• durable pre-charge checkout attempt
• payment reference persisted as soon as possible
• user-facing recovery messaging
• idempotent provisioning
• webhook repair
• periodic reconciliation
• support tools that use the same recovery code

That’s what the example above implements.

If you want, I can also provide: 1. a Stripe-specific version 2. a version using PostgreSQL + SQLAlchemy 2.0 async 3. a version with tests for the crash/recovery scenario