Plan: Payment Provider Abstraction¶
Status: ✅ Done · Date: 2026-11-15 · ADR: ADR-0038 · Builds on: plan-sepay-payments
Overview¶
Move every SePay-specific piece of the payment feature behind a PaymentProvider port so that switching or adding a vendor touches one adapter package plus configuration. SePay becomes the first adapter; its behaviour does not change.
Objective¶
After this plan, adding vendor X means:
service/payment/<x>/withXProvider implements PaymentProvider(+XTransferFeedif it has a pull API) and its tests extendingPaymentProviderContractTestapp.payment.<x>.*inapplication.yaml, secrets in env/HelmPAYMENT_PROVIDER=<x>for new orders; point the vendor's webhook at/webhooks/payments/<x>
No change to orders, settlement, admin API, frontend, i18n or schema.
Scope¶
In Scope¶
- Neutral model, port, registry, ingestion and reconcile services
- SePay adapter (move, not rewrite)
- Generic webhook controller with
/webhooks/sepayalias - Config split with
SEPAY_*env fallbacks - Migration
sepay_transactions→payment_transactions,payment_orders.provider, job rename - Admin API + frontend neutral naming
Out of Scope¶
- Integrating a second real vendor
- Renaming Harness flag keys
- Card / hosted checkout flow
Technical Approach¶
See ADR-0038 for the port, model and data model. Two-hats rule: PP-1..PP-3 are refactors (tests unchanged in meaning, no schema change); PP-4 is the schema change; PP-5 the API/UI rename. Commit between hats.
Key Decisions¶
- Registry of providers, one selected for new orders, all configured ones accept webhooks/reconcile (safe switch)
provider_tx_idis a string; surrogateidis what admin uses- Old webhook URL and Harness flag keys kept
Implementation Steps¶
| ID | Task | Done when | Depends |
|---|---|---|---|
| PP-1 | Neutral model + port: BankTransfer, FeedTransfer, PaymentInstructions, WebhookRequest/WebhookResult, PaymentProvider, TransferFeed, ProviderApiException, PaymentProviderRegistry (by id, active() from app.payment.provider, unknown id fails at startup). Extract PaymentIngestionService from SepayWebhookServiceImpl.process (dedupe by provider tx id, then bank reference + amount; code extraction; match; settle) |
Ingestion tests cover every branch of today's process tests via a fake provider; BeanConstructorTest green |
— |
| PP-2 | SePay adapter in service/payment/sepay/: SepayProvider (IP allowlist, HMAC, parse → BankTransfer, VietQR URL), SepayTransferFeed (API v2 client, paging, 400 ms pause, delivered flag). PaymentReconcileService neutral (T-1 day pass + checkOrder), log line unchanged + provider=. PaymentWebhookController POST /webhooks/payments/{provider} + alias /webhooks/sepay; whitelist both paths in AppConstant. Delete SepayWebhookService*, SepayReconcileService*, SepayWebhookController, VietQrUrlBuilder |
Moved SePay tests green (HMAC, skew, size cap, IP, parse, paging, 401/429/bad JSON); PaymentProviderContractTest added and extended by SePay; status-order 503 → 403 → 413 → 401 → 400 → 200 unchanged |
PP-1 |
| PP-3 | Config: AppProperties.Payment (provider, bank account fields, code prefix, TTL, min donation) + Payment.Sepay (secrets, URLs, IPs); application.yaml with PAYMENT_* falling back to SEPAY_*; PaymentOrderServiceImpl uses registry.active().instructions(...) |
Config binding test; existing order tests green; env on prod unchanged still boots | PP-2 |
| PP-4 | Migration 202611150001-payment-transactions.sql: rename table, add id BIGSERIAL PK, provider, provider_tx_id, unique (provider, provider_tx_id), backfill, drop sepay_id PK; rename indexes; payment_orders.provider default 'sepay'; scheduled_job reconcile-sepay → reconcile-payments. Entity PaymentTransaction, repo PaymentTransactionRepository (insertIgnore on the new unique key), purge query updated; storageId hash removed (UUIDs stored as text) |
Migration applies on a copy of prod schema; repo query tests green; ScheduledJobMigrationTest updated; app boots locally |
PP-3 |
| PP-5 | Admin API + FE: /admin/payments/transactions/{id}/link|ignore (surrogate id), POST /orders/{id}/check-provider, AdminTransactionDto.id + provider, error keys error.payment.providerApiFailed|providerApiNotConfigured; FE adminPayments.js, useAdminPayments.js, AdminPaymentsTab.jsx use id, label "Check with {{provider}}" en/vi |
Controller, service and Vitest tests green; i18n parity test green; lint/build green | PP-4 |
| PP-6 | Docs: ADR-0038 → Accepted, ADR-0037 note, runbook "Add a payment provider" checklist, plan-sepay-payments config table, tracking.md, Tech Strategy row says "Payments: provider port, SePay adapter" | Docs merged; tracking ✅ | PP-5 |
Sequential: each step moves code the next one depends on.
Files to Modify¶
- New:
service/payment/(model, port, registry,PaymentIngestionService,PaymentReconcileService),service/payment/sepay/,web/PaymentWebhookController.java,entity/PaymentTransaction.java,repo/PaymentTransactionRepository.java, Liquibase changeset - Changed:
PaymentOrderServiceImpl,AdminPaymentService(Impl),AdminPaymentController,PaymentController,AppProperties,application.yaml,AppConstant,AppScheduler,JobRegistry,PaymentOrderRepository,AdminTransactionDto,AdminOrderCheckDto, i18nmessages*.properties - Removed:
SepayWebhookService(Impl),SepayReconcileService(Impl),SepayWebhookController,SepayTxPayload,SepayTransaction,SepayTransactionRepository,VietQrUrlBuilder - Frontend:
api/adminPayments.js,hooks/useAdminPayments.js,components/admin/AdminPaymentsTab.jsx(+ test),i18n/locales/{en,vi}/admin.json - Helm: optional
PAYMENT_PROVIDERenv (defaults tosepay)
Testing Strategy¶
Unit Tests¶
- Ingestion with a fake provider: duplicate tx id, same reference + amount under another id,
OUTignored, no code → UNMATCHED, cancelled order → UNMATCHED, exact / over / under / accumulate, Premium extension - Two fake providers registered: webhook and reconcile route by id; new orders use the active one
PaymentProviderContractTest:receiverejects an empty body, never throws on garbage,instructionsencodes the code
Integration Tests¶
- Repository tests for
insertIgnoreon(provider, provider_tx_id)and the purge query
Manual Testing¶
startLocal.shboots (no@SpringBootTestin CI)- SePay Test mode: simulated transfer → order PAID; both webhook URLs answer
- Admin: link, ignore, check-provider on a pending order
Rollback Plan¶
PP-1..PP-3 revert cleanly (no schema). PP-4 ships a Liquibase rollback block (rename back, restore sepay_id PK from provider_tx_id where numeric). Payments are not live, so data loss risk is limited to test rows.
Risks¶
| Risk | Mitigation |
|---|---|
| Behaviour drift while moving SePay code | Move tests with code before editing; diff test names to confirm none dropped |
| Rolling deploy: old pod writes to renamed table | Payments not live; deploy outside donation traffic; old pod only fails on payment endpoints |
| Grafana panel parses the reconcile log line | Keep the text, append provider= at the end, check the panel after deploy |
| Old reconcile rows carry hashed negative ids | Backfilled as text; reference + amount dedupe still blocks double credit |
Checklist¶
Before Starting¶
- [ ] ADR-0038 approved by owner
- [ ] TASKS.md section added
Before Merge¶
- [ ]
mvn verifygreen, coverage ≥ 90% - [ ]
npm run lint && npm test && npm run buildgreen - [ ] App boots locally; SePay sandbox webhook credits an order
Progress Log¶
| Date | Note |
|---|---|
| 2026-11-15 | Plan drafted and approved |
| 2026-11-15 | PP-1..PP-4 built together (the interim long sepay_id mapping would have been throw-away work, and payments are not live); PP-5 admin API + FE; PP-6 docs. mvn verify 2229 tests green, coverage met; webapp lint, 825 tests, build green. App boot against a database not verified locally (no local Postgres) |