Fin Escrow Hold

Escrow Hold

When to Use

• Marketplace P2P transactions where buyer pays before seller delivers
• Bounty claims where payout is contingent on acceptance
• Any transaction requiring trusted intermediary pattern

Rules

1. Debit buyer instantly — funds leave their wallet immediately
2. Hold in escrow account — not in seller's wallet yet
3. Atomic — buyer debit + escrow entry in single transaction
4. Escrow expires after configurable timeout → auto-refund
5. Both parties can see escrow status

Pattern: Escrow Hold Service

from decimal import Decimal
from django.db import transaction
from apps.wallet.models import Wallet, Transaction
from apps.marketplace.models import EscrowHold
import uuid

@transaction.atomic
def create_escrow(
    buyer_id: int,
    seller_id: int,
    amount: Decimal,
    listing_id: int,
    hold_days: int = 14,
) -> EscrowHold:
    """Hold buyer funds in escrow for a marketplace trade."""
    if amount <= Decimal("0"):
        raise ValueError("Escrow amount must be positive")

    wallet = Wallet.objects.select_for_update().get(user_id=buyer_id)
    if wallet.balance < amount:
        raise ValueError("Insufficient balance for escrow")

    # Debit buyer
    wallet.balance -= amount
    wallet.save(update_fields=["balance", "updated_at"])

    ref = str(uuid.uuid4())
    Transaction.objects.create(
        wallet=wallet, amount=-amount,
        transaction_type="escrow_hold",
        reason=f"Escrow for listing #{listing_id}",
        reference=ref, balance_after=wallet.balance,
    )

    from datetime import date, timedelta
    return EscrowHold.objects.create(
        buyer_id=buyer_id, seller_id=seller_id,
        amount=amount, listing_id=listing_id,
        reference=ref, status="held",
        expires_at=date.today() + timedelta(days=hold_days),
    )