Add a payment adapter

Openfront's payment adapter dispatcher supports two provider modes:

• a local adapter module such as stripe, paypal, or manual under features/integrations/payment;
• an external HTTP route app, selected by storing an HTTP endpoint in each operation field on the PaymentProvider record.

This database configuration is intentional: a merchant can connect or replace an external payment app without adding that app's implementation to the Openfront repository.

How dispatch works

features/keystone/utils/paymentProviderAdapter.ts reads the configured field for the requested operation:

• createPaymentFunction
• capturePaymentFunction
• refundPaymentFunction
• getPaymentStatusFunction
• generatePaymentLinkFunction
• handleWebhookFunction

If the value starts with http, Openfront sends a JSON POST to that URL. Otherwise, it imports features/integrations/payment/<value>.ts and invokes the export named by the operation field.

For example, payment creation sends the external route a body shaped like:

{
  "provider": "the configured provider record",
  "cart": "the current cart projection",
  "amount": 2500,
  "currency": "USD"
}

Other routes receive the same provider object plus operation-specific values such as paymentId, amount, event, or headers. The route's JSON response must match the provider-neutral result expected by the Openfront caller.

Configure an external route app

1. Deploy one trusted HTTPS route per operation, or deliberately route several operation fields to one app that can distinguish the request shape.
2. Create a PaymentProvider record with its name, pp_… code, enabled state, credentials/metadata, regions, and operation URLs.
3. Implement only the operations the payment app actually supports, while ensuring unsupported calls fail explicitly.
4. Test the provider against a disposable Openfront host and provider sandbox.
5. Verify payment initiation, browser handoff, capture, refund, status, payment-link, webhook, timeout, and reconciliation behavior required by the intended checkout.

Current source limitations

The generic dispatcher supports external payment routes, but the complete Ecommerce flow is not yet provider-neutral:

• the dashboard creation UI exposes built-in presets rather than a complete external-route form;
• completeActiveCart.ts and invoice completion still switch on the built-in Stripe, PayPal, and manual provider codes instead of completing through the configured adapter contract;
• webhook ingress and signature handling must be verified against each route app's raw-body requirements;
• the bridge currently has no built-in timeout, destination policy, adapter authentication, or runtime response schema.

Therefore a custom external adapter can participate in generic adapter calls, but a complete checkout cannot be claimed until the target revision removes the hard-coded completion switch and passes end-to-end tests.

Required verification

• unauthorized users cannot create or alter provider routes or credentials;
• each operation reaches only its configured adapter destination;
• the adapter authenticates the Openfront caller and rejects replay where relevant;
• amounts and currency come from persisted server state;
• duplicate create/capture/refund requests have one provider effect;
• malformed, oversized, delayed, or partial adapter responses fail closed;
• provider credentials and payment data do not appear in logs or client responses;
• invalid and replayed webhooks make no state change;
• uncertain responses reconcile before another payment action.

See Payment providers.