@maxnate/plugin-payments

Admin capability + plugin install for @maxnate/payments-core. Owns the paymentModule extension that other plugins (plugin-ecommerce, plugin-booking, plugin-nonprofit, plugin-finance, plugin-travel, …) consume via ctx.get('paymentModule').

npm install @maxnate/plugin-payments @maxnate/payments-core

What it provides

| Surface | Value | |---|---| | Extension key | paymentModule | | Admin pages | /admin/payments, /admin/payments/:provider | | Admin API | Provider catalog, gateway self-test, manual instruction sets, proof upload/review, webhook URL discovery | | Install order | 100 (registers before industry plugins) | | Webhook integration | Use paymentModule.processWebhook(...) from a host route |

Install

import { paymentsPlugin } from '@maxnate/plugin-payments'
import { SnippeProvider, snippeSchema } from '@maxnate/provider-snippe'

system.use(paymentsPlugin({
  providers: [{ id: 'snippe', adapter: new SnippeProvider(), schema: snippeSchema }],
  secretsCodec: mySecretsCodec
}))

Industry plugins do not need any code changes — they continue to call ctx.get('paymentModule') exactly as before.

UI And Admin Boundary

plugin-payments is the admin/backend orchestration layer. It is not the customer-facing checkout UI itself.

Shared Terminology

• Customer UI: the payment or checkout experience in your own app.
• Admin UI: the tenant/operator-facing payments configuration and review screens.
• Provider-hosted checkout: a payment page hosted by the payment provider.
• Provider dashboard: the provider's own dashboard for account-level setup.

What This Plugin Is For

• tenant payment-provider configuration
• admin-side credential management
• webhook URL discovery
• gateway self-test
• manual/offline payment review workflows
• provider selection and routing helpers
• exposing a stable paymentModule to other system plugins

What You Can Build With It

• an admin payments screen for each tenant under /admin/payments
• provider setup forms driven by provider capabilities/schema
• a manual-payment review queue for receipts, IDs, screenshots, and approval actions
• a gateway operations dashboard showing webhook URLs, enabled providers, and routing policy
• customer-facing checkout flows in your own app by calling ctx.get('paymentModule')

What It Does Not Do For You

• it does not render your storefront, booking, donation, or invoice checkout pages
• it does not replace provider-hosted checkout UIs like Snippe Sessions
• it does not create provider dashboards or bypass provider account setup
• it does not own payout/disbursement flows; those remain out of scope for this package

Customer UI vs Admin UI

• Admin UI: use plugin-payments to configure providers, manage credentials, review manual payments, and inspect webhook/setup information.
• Customer UI: build this in your project or industry plugin (plugin-ecommerce, plugin-booking, plugin-nonprofit, etc.) using the paymentModule methods.
• Provider-hosted UI: when a provider supports hosted checkout (for example Snippe Sessions), your project can launch that flow, but the actual hosted payment page still belongs to the provider.

Recommended Pattern

• use plugin-payments for tenant configuration and payment operations
• use your project UI for business-specific checkout UX
• use provider-hosted checkout only when you intentionally want the provider to own the payment page

Manual Payments Support

plugin-payments now exposes backend helpers for Phase C manual/offline flows:

• provider discovery: getAvailableProviders()
• side-effect-free connection validation: selfTestGateway()
• tenant instruction set CRUD: listInstructionSets(), upsertInstructionSet(), deleteInstructionSet()
• proof workflow: uploadPaymentProof(), getPaymentProofUrl(), reviewManualPayment(), listPendingManualReviews()
• admin setup: listWebhookUrls(), regenerateWebhookSecret()
• routing helpers: selectProvider(), createManualIntent(), getRoutingPolicy(), setRoutingPolicy()
• reconciliation/reporting: fetchProviderLedger(), reconcileProviderLedger(), getDashboardMetrics()

Notes

• Use paymentModule.selfTestGateway(...) for side-effect-free provider validation.

Peer dependencies

| Peer | Required | Notes | |---|---|---| | @maxnate/payments-core | yes (^0.3.0) | Registry, types, webhook orchestration | | @system-core/core | optional (^0.12.0) | Required when used as a system-core plugin |

See also

• @maxnate/payments-core — registry + provider interface
• @maxnate/provider-snippe, @maxnate/provider-clickpesa, @maxnate/provider-selcom — built-in providers
• packages/payments/payments-core/docs/ARCHITECTURE.md — full architecture diagram