Payment providers
Local and external payment adapter dispatch, provider state, and current workflow boundaries.
Openfront stores payment-provider configuration in PaymentProvider records and dispatches standardized operations through features/keystone/utils/paymentProviderAdapter.ts.
A provider can use either:
- a local module token such as
stripe,paypal, ormanual; or - an HTTP endpoint for an independently deployed adapter app.
Each operation field is configured separately: creation, capture, refund, status, payment link, and webhook handling. Database-selected HTTP routes are part of the adapter design, allowing merchants to connect external payment apps without adding their implementation to the Openfront repository.
Dispatch contract
For HTTP fields, Openfront sends POST JSON containing the queried provider record and operation-specific arguments. For local fields, it dynamically imports features/integrations/payment/<configured value>.ts and calls the export matching the operation field.
The features/integrations/payment/index.ts object lists built-in modules, but the current Keystone dispatcher does not use that object as a static registry. The operation fields themselves control dispatch.
Data boundary
Payment providers, sessions, collections, payments, captures, and refunds attach provider-neutral state to carts, invoices, or orders. The adapter may require credentials and payment/customer context to call its upstream service, but Openfront should forward only what that operation needs and validate the adapter response before changing domain state.
Provider configuration is privileged: changing an operation URL changes which trusted app receives provider and payment data. Protect that configuration with operator authorization, endpoint policy, Openfront-to-adapter authentication, secret handling, redaction, timeouts, response schemas, idempotency, and reconciliation.
The current bridge does not provide those hardening controls automatically. It sends the selected provider object to any operation value beginning with http, with only a JSON content-type header. Review and harden this boundary for the deployment while preserving external adapter support.
Current workflow boundaries
Generic adapter dispatch is implemented for payment initiation and webhook handling, and helper functions exist for capture, refund, status, and payment links. The overall Ecommerce workflow is not fully generic:
- provider creation UI currently exposes built-in presets rather than full route-app configuration;
- checkout and invoice completion still contain hard-coded Stripe, PayPal, and manual code switches;
- several adapter helpers are not consistently used by the lifecycle paths;
- raw-body webhook requirements, replay handling, and external route authentication need target-specific verification.
A provider row or successful initiation call therefore does not prove complete payment processing.
Enabling a provider
- Choose local-module or external-route mode for each operation.
- Configure the provider record and regions through a privileged path.
- verify exact request and response shapes from the target revision.
- derive amounts, currencies, actor/cart/order identity, and allowed transitions on the server.
- add idempotency and unknown-outcome reconciliation.
- verify webhook origin/signature and replay handling.
- run initiation, browser handoff, completion, capture, refund, failure, timeout, and recovery tests.
Manual payment
Manual is an offline/operator boundary. It must not let an anonymous customer grant paid state or entitlement without the intended authorized settlement step.
Start with Add a payment adapter.