Finance Engine¶
Status: Draft for review
Purpose¶
Own monetary transaction execution and financial records: payment intents/transactions, refunds, invoices, tenant/customer financial ledgers, commissions/earnings/withdrawals where the commercial model requires them, and subscription-billing integration facts.
Owns¶
- Payment transaction state and gateway references
- Refunds
- Invoices/receipts
- Taxes/fees/commission calculations that are financial policy
- Provider/partner earnings and withdrawals if retained by target product
- Reconciliation records
- Tenant subscription billing integration state
Non-goals¶
It does not own offering pricing rules/quotes, booking availability, plan definitions, or raw gateway implementation details beyond finance adapters/references.
API contract — functional surface¶
These are contract-level resources and operations, not final controller/file names.
| Method | Route | Primary actor | Contract intent |
|---|---|---|---|
| POST | /api/public/v1/payments/intents |
Customer | Create payment intent for eligible order/booking. |
| GET | /api/public/v1/payments/{id}/status |
Customer | Read customer-visible payment status. |
| POST | /api/tenant/v1/refunds |
Finance Manager | Initiate permitted refund against transaction. |
| GET | /api/tenant/v1/transactions |
Finance Manager | Search tenant transactions/reconciliation state. |
| GET | /api/tenant/v1/invoices/{id} |
Authorized Tenant/Customer | Retrieve invoice metadata/document entitlement. |
| GET | /api/tenant/v1/earnings |
Finance Manager | Read earnings/commission aggregates where enabled. |
| POST | /api/tenant/v1/withdrawals |
Eligible Payee | Request withdrawal where enabled. |
| PATCH | /api/platform/v1/withdrawals/{id} |
Platform Finance/Admin | Process/approve withdrawal where platform-managed. |
| POST | /webhooks/payments/{provider} |
Payment Provider | Receive verified provider payment callbacks. |
All mutating operations apply the global tenant, authorization, audit and idempotency rules where relevant.
Events¶
payment.intent_createdpayment.authorizedpayment.capturedpayment.failedpayment.refundedinvoice.issuedwithdrawal.requestedwithdrawal.completedreconciliation.mismatch
Roles & responsibility matrix¶
Legend: A accountable, R responsible, C consulted, I informed, — none.
| Capability | Platform Admin | Tenant Owner | Tenant Admin | Specialist/Manager | Customer/Visitor |
|---|---|---|---|---|---|
| Financial platform policy | A | C | I | R | I |
| Tenant refunds | I | A | C | R | I |
| Transaction reporting | I | A | C | R | I |
| Customer payment | — | I | I | C | R |
| Platform-managed payout/withdrawal | A/R | C | I | C | I |
Dependencies¶
- Commerce Engine for order/booking/price quote references
- Platform Engine for plan/subscription identity
- Integration Engine for gateway adapters/secrets
- Operations for reconciliation jobs/audit
Internationalization Contract¶
- Money/currency/tax calculations are locale-neutral; display formatting and localized labels are resolved separately.
- Invoice/customer-facing finance text can be localized by recipient/document locale.
- Currency selection/exchange logic must never be inferred solely from language locale.
Security / isolation requirements¶
- Money stored/transmitted in minor units + currency.
- Payment webhooks verified and idempotent.
- Financial state cannot be altered by general tenant staff without permission.
- Refund/payment operations are auditable and replay-safe.
Acceptance criteria¶
- Legacy payment gateway, invoice, commission/earnings/withdrawal behavior has an explicit migration decision.
- Payment state and booking state remain separately modeled.
- Reconciliation detects provider/platform disagreement.