RevenueFlow.Payments 0.1.0-alpha.7.2

This is a prerelease version of RevenueFlow.Payments.
dotnet add package RevenueFlow.Payments --version 0.1.0-alpha.7.2
                    
NuGet\Install-Package RevenueFlow.Payments -Version 0.1.0-alpha.7.2
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="RevenueFlow.Payments" Version="0.1.0-alpha.7.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="RevenueFlow.Payments" Version="0.1.0-alpha.7.2" />
                    
Directory.Packages.props
<PackageReference Include="RevenueFlow.Payments" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add RevenueFlow.Payments --version 0.1.0-alpha.7.2
                    
#r "nuget: RevenueFlow.Payments, 0.1.0-alpha.7.2"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package RevenueFlow.Payments@0.1.0-alpha.7.2
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=RevenueFlow.Payments&version=0.1.0-alpha.7.2&prerelease
                    
Install as a Cake Addin
#tool nuget:?package=RevenueFlow.Payments&version=0.1.0-alpha.7.2&prerelease
                    
Install as a Cake Tool

RevenueFlow.Payments

Subscription composition and native offer changes use the same ProviderControlService durable prepare/claim/observe protocol as existing controls. Repeating an operation key with changed items, quantities, schedule dates or discounts conflicts. Unknown submissions are read-only reconciled and are never blindly resubmitted. Multi-item acquisition freezes every catalog snapshot and optional native discount, capability-checks the selected Core gateway and verifies the returned native item shape.

Personal CommerceWebhookProcessor supports complete normalized subscription line evidence through IRevenueSubscriptionBasketLifecycle. It resolves trusted owner/catalog policy separately for every item, requires one owner, monotonic revision and canonical parent, and commits the basket with parent ownership fences, intake completion and history atomically. Bounded invoice discovery retains known items until complete snapshots can expire omitted add-ons. A late invoice cannot reactivate an item excluded by a complete snapshot. Distinct native invoice-line economic identities retain the parent billing document. PaidAmountMinor is independent of list-price benefit allocations. Multi-item parent-invoice refunds and native team baskets remain unresolved pending explicit allocation/account composition support; no aggregate payment is assigned repeatedly to different items. Existing exact undiscounted single-item team observations keep their previous path.

Optional durable scheduling wraps provider history/known-reference recovery with fenced leases, resumable sweep identities, contiguous overlapping windows and safe backoff. Scoped health contributors expose reconciliation freshness, uncertain provider operations and explicitly selected event-outbox backlogs with bounded coverage. See reconciliation and health for setup and recovery boundaries.

Provider-neutral durable payment orchestration consumes IPaymentGateway and IPurchaseWebhookProvider from Core. A provider adapter contains protocol/transport behavior and references Core only. Select bindings per provider/account/user flow; one application may use several providers concurrently.

PaymentOperationService first persists a scoped operation with immutable amount/currency and a durable command receipt. Before submitting it atomically claims the operation by changing its state to SubmissionUnknown. Only the owner of a definite committed claim sends the outbound request. Repeated callers and restarted processes never automatically create it again. A crash between the claim and the request conservatively leaves an unknown operation. The stable idempotency key is supplied to the adapter, but provider key retention is not treated as permanent protection.

Reconciliation retrieves an already known ID or an operator-supplied candidate and verifies provider correlation to the durable operation UUID, amount, currency, mode and one-time purpose before binding it. If no provider ID is known, the operation remains unresolved until the application obtains a candidate through its provider's operational tooling. No provider call runs in a database callback. Creation never fulfills an order; RequiresAction, Processing and other intermediate statuses remain explicit.

Payment creation and retrieval check the selected provider binding before and after the awaited callback, including null responses. Binding drift rejects the new observation while preserving the prior durable state; a claimed unknown creation cannot be blindly resubmitted and can recover through original-binding reconciliation. Same-binding credential rotation remains supported. Applications must keep binding configuration stable; before/after checks cannot make arbitrary external rebinding atomic or detect changes restored entirely between checks.

BillingProviderMigrationService imports verified provider history using application-owned owner and catalog mappings. Pass the fingerprint from PreviewPageAsync to require the exact previewed page, including a retained page after a lost staging acknowledgement or a concurrent staging winner. A mismatch rejects before this call processes rows or advances the page. A matching fingerprint or an omitted fingerprint resumes the pinned page without rereading provider history or resolving mappings. Completed jobs remain no-ops.

Migration pages default to 20 observations, with a supported budget of 1–20 and the same bound for retained rows. This accommodates an entire native Apple history page; Apple requires a budget of at least 20, while other readers can support smaller budgets. The page budget is part of the frozen request identity: recovery must re-supply its original value, and a changed budget conflicts. Native provider continuation cursors remain opaque and unchanged.

PurchaseWebhookInbox verifies through the configured adapter before committing raw event JSON, its original raw-byte SHA-256, normalized evidence and a command receipt together. It rejects a different payload reusing the same scoped provider event ID. Unknown fields remain in RawPayload, never in logs or ToString. Raw events are limited to 32 KiB and complete envelopes must fit 64 KiB/depth 32; unsupported input rejects before durable acknowledgment and is never truncated. Storage JSON avoids HTML-oriented escaping expansion. Application HTTP request buffering should enforce a matching bound. Retention/access controls for opaque provider data are application responsibilities.

PurchaseWebhookProcessor resolves persisted observations through an application-owned IPurchasePaymentBindingResolver. Return an existing authorized user and immutable frozen offer; do not infer ownership from arbitrary customer metadata. Quantity-one, currency and amount must match confirmed evidence. Order effects and the inbox completion revision are committed in the same commerce transaction, including on economic replay. Integration provider and originating store/account/transaction are retained independently.

Reconstruct the inbox after restart, use bounded ListIncompleteAsync pages and ProcessAsync, and repeat later scans from the beginning because pages are live. Continue through empty filtered pages while NextAfterId is nonnull. Unresolved bindings and failed fulfillment leave intake incomplete. The supplied in-memory adapter proves local behavior only; durable recovery requires a durable conforming store shared by inbox and fulfillment.

CommerceWebhookInbox extends verified intake to Core lifecycle/reconciliation evidence. CommerceWebhookProcessor consumes IRevenueLifecycleService and IPurchaseFulfillmentService with trusted application resolution; purchase/renewal, trial/state changes, refunds/reversals and disputes join completion plus normalized/raw observation history in the domain transaction. Provider timestamps are not versions. Unsupported/transfer/observe-only input remains discoverable for explicit policy. Sensitive providers can choose fingerprint-only retention; non-JSON forms use a verified JSON envelope.

An authenticated webhook retry with the same provider event ID and original-byte digest returns the first durable observation, including its completion state. A fresh provider API read during verification may have advanced; it cannot replace that accepted evidence. Changed bytes conflict. API-only reconciliations retain strict normalized-snapshot identity checks.

When direct and aggregate integrations expose different lineage IDs for the same subscription, the trusted resolver can supply CommerceObservationBinding.CanonicalSubscriptionId. Configure the same canonical chain and monotonic revision authority before initial ingestion through either adapter. Subscription state and paid-period provenance use this chain; original provider/account/transaction evidence remains retained. This mapping does not infer ownership or rewrite existing chains.

ProviderPurchaseActionService commits intent/claim before acknowledgment or consumption, persists only a hash of the sensitive reference and never auto-resends an uncertain action. Prepared intents remain eligible for their first execution. Read-only reconciliation requires the application to resupply its securely held reference. Payment observations include the operation revision in receipt identity so legitimate status cycles remain applicable. Downstream provider state is allowlisted, never a raw error/secret dump.

ProviderControlService consumes Core subscription/refund gateways. It commits each intent/claim/result with transition history and selected outboxes, enforces one definite submission owner, and never resends after uncertainty/restart. Reconciliation is read only; success does not directly alter commerce benefits. Sensitive references are hashed, re-supplied and omitted from JSON. Unsupported policies reject before persistence/I/O; unknown/malformed stored schema/status cannot default to Ready. See control semantics and capabilities.

Optional inbound queue

CommerceWebhookIngress preserves the application's endpoint and fulfillment policy. Without a queue, supply a scoped CommerceWebhookInbox and an application callback that invokes its configured commerce processor; intake and that callback run inline. There is no implicit process-local buffer.

With an IRevenueInboundQueuePublisher and IRevenueInboundEnvelopeProtector, ingress does not access the commerce database. Only DurableAccepted authorizes the endpoint to acknowledge the provider. Rejected, uncertain, canceled or thrown publication must produce a retryable endpoint result; queued ingress never falls back to inline execution. The host maps these results to its provider's HTTP acknowledgment requirements.

Queue payloads contain a versioned envelope binding original bytes and their SHA-256 digest to the complete provider scope, account, mode, route configuration, queue identity, message identity and received/verified timestamps. Original authentication headers are omitted. AesGcmInboundEnvelopeProtector provides authenticated AES-256-GCM encryption with an application-owned key ring independent of commerce storage. Retain decryption keys for all queue and dead-letter retention, rotate the active key for new admissions, and restrict publisher/consumer permissions. Raw body admission is bounded to 32 KiB; protected messages to 1 MiB. No queue contents, receipts, keys or provider exceptions should be logged.

Custom envelope protectors must throw RevenueInboundEnvelopeException for invalid seals or protected data. Keep temporary external key-service failures distinct: they retry through the queue rather than dead-lettering valid events. Distribute new decryption keys before enabling them for ingress encryption.

Ingress serializes plaintext into temporary pooled memory and retains its owner until ProtectAsync completes. Custom protectors may borrow that input only for the duration of their returned operation. Ingress snapshots the protected result before clearing and returning the entire temporary buffer, including on cancellation or failure. Published messages remain independently owned even if a custom protector returned an alias of its input; this does not remove the requirement for encryption.

Providers implementing Core ICommerceWebhookAdmissionProvider authenticate the transport at ingress and defer remote enrichment to the worker. Their sealed ProviderAuthenticatedWebhook.Evidence may include sensitive provider references required for enrichment. Custom adapters without that capability perform their existing full verification before publication; their provider API must therefore be available during admission. Workers never recheck expired ingress signatures or change a verification clock. Authenticated messages have no library-imposed age expiry; the application chooses queue retention and keeps compatible route configuration and keys for replay.

Explicitly register CommerceInboundQueueProcessor with a selected binding and inbox, optionally wrapped in RevenueInboundQueueWorker. The processor unseals and validates routing and schema, enriches split-authenticated evidence, then durably accepts the original bytes into the existing inbox. Broker acknowledgment follows confirmed inbox acceptance. Original-byte retry semantics preserve the first accepted normalized snapshot even if a subsequent provider API read has changed. Queue delivery is at least once; existing provider-event and economic deduplication remain authoritative. Domain effects, inbox completion, history and outbound events continue to share the existing commerce transaction.

For a shared queue containing multiple providers or scopes, use the processor overload accepting application-owned ICommerceInboundQueueRouteResolver. Resolution runs only after envelope protection and schema validation. A returned CommerceInboundQueueRoute must exactly match the sealed binding and configuration identity, including scope, provider account and mode. The resolver selects preauthorized provider/inbox/callback instances; message contents never establish credentials or authorize new tenants. Return null for a permanently unknown route, which dead-letters the item; throw for temporarily unavailable route configuration, which retries. The fixed-route overload is suitable for a queue dedicated to that route.

The queue processor can invoke an optional application processing callback before acknowledgment. Otherwise the host must run its existing incomplete-inbox recovery/processing policy after the durable handoff. Failures after an uncertain database response or queue acknowledgment safely replay the same inbox identity. Transient database/provider failures use bounded exponential delay and have no automatic attempt-count dead-letter threshold. Invalid seals, bindings, schema, authenticated evidence or conflicting event identities are dead-lettered; an application may explicitly throw RevenueInboundPermanentFailureException for permanent policy rejection. Restore keys/configuration or fix processing before explicit adapter redrive.

Consumers must implement fenced leases and renewal, delayed retry and durable dead-letter publication before source acknowledgment. Those guarantees may be broker-native or implemented by the adapter; inspect its documented limits. A queue backed by the same unavailable database cannot buffer that database's outage. No cross-database atomicity or exactly-once broker delivery is promised.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (2)

Showing the top 2 NuGet packages that depend on RevenueFlow.Payments:

Package Downloads
RevenueFlow.SelfService

Durable customer center selections, provider controls, retention and billing reminders.

RevenueFlow

RevenueFlow commerce composition with internal administrative issuance. External providers and stores are explicit opt-ins.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.1.0-alpha.7.2 58 11/10/2026