Order

An Order represents a buyer's intent to purchase from a Store Page. It contains a derived Bitcoin address, an expiration window, and tracks payment status through its lifecycle.

Properties

Property	Type	Description
Id	int	Primary key
BuyerId	int?	FK → AppUser (null for anonymous orders)
SellerId	int	FK → AppUser (the store page owner)
StorePageId	int	FK → StorePage
PaymentDestinationId	int	FK → PaymentDestination
DerivedPaymentAddress	string	The unique Bitcoin address for this order
AccessToken	string	Bearer token for accessing purchased content
DerivationIndex	int	Index used to derive the payment address
NetAmountSats	long	Price before VAT
VatRate	decimal	VAT percentage applied
VatAmountSats	long	VAT amount in satoshis
TotalAmountSats	long	Total amount the buyer must pay
IsVatExempt	bool	Whether the buyer has a valid VAT ID
BuyerVatId	string?	Buyer's VAT identification number
DisplayAmountBtc	string	Human-readable BTC amount
FiatReferenceAmountUsd	decimal?	USD equivalent at time of order
ExpiresAtUtc	DateTime	4 hours from creation
Status	OrderStatus	Current payment status
IsAnonymous	bool	Whether this is an anonymous purchase
AnonymousEmail	string?	Email for anonymous buyer notifications
ClaimCode	string?	Code for anonymous buyers to claim the game
IsLightningPayment	bool	Whether this is a Lightning payment
InvoiceEnabled	bool	Whether an invoice should be generated

Order Statuses

Status	Description
Open	Created, awaiting payment
PaidPendingConfirmation	Payment detected on-chain, awaiting confirmations
Fulfilled	Payment confirmed, games delivered to buyer
Expired	4-hour window elapsed without payment
Cancelled	Buyer cancelled before paying
Returned	Order reversed (refund)
Revoked	Access revoked by seller/admin

Payment Flow

Order Created (Open)
  │
  ├─ On-chain: PaymentDetector polls blockchain
  │   → PaidPendingConfirmation (detected)
  │   → Fulfilled (confirmed)
  │
  ├─ Lightning: Webhook receives settlement
  │   → Fulfilled (instant)
  │
  ├─ 4 hours elapse → Expired
  │
  └─ Buyer cancels → Cancelled

Address Derivation

Each order gets a unique Bitcoin address derived from the seller's xpub/descriptor:

1. PaymentAddressAllocator atomically increments DerivationIndex on the seller's PaymentDestination.
2. NBitcoinPaymentAddressDerivationService derives the address using NBitcoin.
3. The address is registered with the Payment Detector for monitoring.

Relationships

Order (N) ──── (1) AppUser   (buyer, optional)
Order (N) ──── (1) AppUser   (seller)
Order (N) ──── (1) StorePage
Order (N) ──── (1) PaymentDestination
Order (1) ──── (N) OrderItem