Enable the donations stack to run on Stripe, PayPal, Square, or ePayMints (one gateway per church at a time) without controller rewrites, while keeping the architecture ready for future providers.
GatewayService+GatewayFactoryabstract provider behaviour, but controllers still grabgateways[0](DonateController, PaymentMethodController, CustomerController, SubscriptionController, GatewayController).GatewayRepoenforces a single row per church by deleting others, but there is no explicit helper for loading or swapping gateways.Gatewaymodel only hasprovider/publicKey/privateKey/webhookKey/productId/payFees; there is no place for provider-specific settings.Customerrecords hold only external ids; PayPal payer ids and other provider data are not stored.- PayPal implementation handles orders/webhooks but throws for customer/payment-method methods; Square/ePayMints providers do not exist yet.
- Secret logging was removed from
GatewayService.getGatewayConfig()(✅ done).
| Feature | Stripe | PayPal | Square | ePayMints |
|---|---|---|---|---|
| One-time card payments | ✅ | ✅ | ✅ | ✅ |
| Stored payment methods / vault | ✅ | ✅ | ❌ | |
| Subscriptions | ✅ | ✅ (plans required) | ✅ | |
| ACH / bank | ✅ | ❌ | ✅ | ✅ |
| Webhooks | ✅ | ✅ | ✅ | ✅ |
| Multi-currency | ✅ | ✅ |
- Catalogue every place we load a gateway and document the target helper (
GatewayService.getGatewayForChurch(churchId)). - Agree on required secrets/settings per provider and capture them in a shared configuration table.
- Define contract tests for the
IGatewayProviderinterface so new providers can be validated automatically.
- Gateways table
- Add
settings(JSON/text) for provider-specific configuration (Square locationId, PayPal returnUrl, ePayMints terminalId, etc.). - Add
environment(VARCHAR) to track sandbox/production. - Add
updatedAttimestamp column for auditability (existingcreatedtimestamps stay as-is or becomecreatedAt). - Keep
publicKey/privateKey/webhookKey/productIdfor Stripe compatibility; populatesettingsfor new providers.
- Add
- Customers table
- Add
providercolumn (VARCHAR) and optionalmetadataJSON so a church can retain historical identifiers during provider swaps. - Backfill existing rows with
provider='stripe'(or'paypal'where applicable).
- Add
- Gateway payment methods
- Create
gatewayPaymentMethodstable (camelCase column names:id,churchId,gatewayId,customerId,externalId,methodType,displayName,metadata,createdAt,updatedAt) to store vault references across providers.
- Create
- Write migration scripts with dry-run mode and data validation (ensure every church retains exactly one gateway row after migration).
- Update
src/modules/giving/models/Gateway.tsto includesettings,environment, timestamps. - Introduce a typed
GatewaySettingsinterface (shared) with provider-specific namespaces (StripeSettings, PayPalSettings, etc.). - Add
GatewayService.getGatewayForChurch(churchId)that returns the single configured gateway or throws a descriptive error. - Extend
GatewayService.getProviderCapabilities(gateway)to surface supported features (supportsVault,supportsACH,requiresPlans, etc.). - Update
GatewayFactoryto lazily register Square and ePayMints providers via feature flags (ENABLE_SQUARE,ENABLE_EPAYMINTS). - Ensure decrypted secrets never get logged; add unit tests covering new service helpers.
- Replace all
gateways[0]usage with the newGatewayService.getGatewayForChurchhelper. - In controllers, branch behaviour based on capability flags instead of provider name (e.g., PaymentMethodController should bail gracefully if
supportsVaultis false). - Update
GatewayControllerto include new settings fields when creating/updating gateways and validate provider requirements. - Move legacy fee calculations behind capability checks; rely on provider-specific
calculateFeeswhen available.
- PayPal
- ✅ Vault customer and payment-method flows implemented in
PayPalHelperand exposed viaPayPalGatewayProvider(create/list/delete with contract-safe error handling). - ✅ PayPal vault tokens are persisted in
gateway_payment_methodswith controller-level syncing for attach/detach flows. - ✅ Subscription plan creation uses helper wiring so dynamic-plan scenarios consume gateway settings and product fallbacks.
- ✅ Vault customer and payment-method flows implemented in
- Square
- ✅
SquareHelpercontinues to encapsulate API calls with environment resolution; provider now pulls credentials fromGateway.settingswith validation for required fields. - ✅
SquareGatewayProviderrespects capability flags and returns descriptive errors for unsupported operations while remaining feature-flagged. - ✅ Square-specific configuration (
locationId,applicationId,environment) now flows through the typed settings column.
- ✅
- ePayMints
- ✅
EPayMintsHelperprovides REST scaffolding for card + ACH flows keyed off gateway settings. - ✅
EPayMintsGatewayProvideradvertises unsupported capabilities with explicit exceptions and reuses shared settings plumbing.
- ✅
- ✅ Provider implementations surface clear error messages for unsupported flows so controllers can relay actionable messaging.
- Unit-test helpers and providers with mocked SDK clients.
- Add integration tests hitting Stripe & PayPal sandbox; create contract tests for Square/ePayMints using recorded fixtures where live sandboxes are unavailable.
- Verify webhook signature flows end-to-end for each provider.
- Add structured logs around provider calls (request id, provider, operation, success/failure) without leaking secrets.
- Ship schema migrations and shared-service updates behind feature flags; confirm Stripe regression tests pass.
- Enable PayPal vault functionality for pilot churches, followed by Square/ePayMints once validated.
- Update onboarding documentation with provider-specific setup steps, required environment variables, and capability matrices.
- Train support on switching providers (data migration checklist, how to rotate secrets, what features differ).
- Add SDK packages:
@paypal/checkout-server-sdk(already used),square(latest), ePayMints client (REST wrapper or custom implementation), ensure versions pinned. - Environment variables per provider (client IDs, secrets, location IDs, terminal IDs, feature flags): add to
.envtemplate and deployment manifests.
- Churches can switch providers via configuration changes only (no code edits, outage < 5 minutes).
- Stripe functionality remains unchanged post-migration.
- PayPal vault flows reach parity with Stripe (create/update/list payment methods, subscriptions).
- Square/ePayMints support one-time payments and respect feature capability flags.
- Automated tests cover at least one happy path per provider and provider capability detection.
- Migration fallout: run migrations in staging with production-sized data; keep rollback scripts and backups.
- API limits/latency: centralise retry/backoff in helpers; add metrics to monitor response times per provider.
- Partial capability coverage: gate new UI/flows behind capability checks and communicate unsupported features via error responses.
- Security/compliance: ensure new tables/columns leverage encryption-at-rest and do not store raw PAN data; review PCI scope before go-live.
- Weeks 1–2: Phases 1 & 2 (schema, services, tests for existing providers).
- Weeks 3–4: Phase 3 controller updates + PayPal vault parity.
- Weeks 5–6: Implement & test Square and ePayMints providers.
- Weeks 7–8: Phase 5/6 testing, documentation, rollout.
- Finalise migration scripts (Phase 1) and review with DBA.
- Prepare
GatewayServicehelper refactor PR (Phase 2). - Draft PayPal Vault helper implementation outline and integration tests (Phase 4.1).