FreClean Payment

FreClean's payment abstraction layer: one PaymentProvider interface for cash, card, and Celo Web3 payments, the Celo on-chain verification worker, the Supported Assets Registry, and a placeholder-but-real-pattern CeloHT webhook receiver.

Part of the FreClean ecosystem. freclean-api owns payment storage and exposes /api/payments; this service reads from that API, checks Celo, and pushes verified status transitions back — it does not maintain its own payments database.

Status

In development. The Celo JSON-RPC client (src/celo/celoClient.ts) makes real calls against a live Celo RPC endpoint (public Forno endpoint by default). The Supported Assets Registry ships empty — no asset can be paid with until it is added with a real, verified contract address (registerVerifiedAsset refuses entries without one).

Why this is a separate service from freclean-api

freclean-api needed a payments endpoint from day one, so it has a self-contained status-transition guard (see that repo's src/modules/payments.ts). This repo is the part that actually checks reality — querying Celo, matching a Supported Assets Registry, and (later) verifying CeloHT webhooks — kept separate so freclean-api doesn't need blockchain dependencies, and so this service can be scaled or restarted independently as a background worker.

Core concepts

Entity	File
PaymentIntent, Payment, PaymentMethod, PaymentStatus, Transaction, Refund	src/core/types.ts
PaymentProvider interface	src/core/PaymentProvider.ts
Cash / Card / Web3 adapters	src/adapters/
Celo JSON-RPC client	src/celo/celoClient.ts
Supported Assets Registry	src/registry/assetRegistry.ts
Verification worker	src/worker/
CeloHT webhook (interface only — see below)	src/webhook/celoHtWebhook.ts

How Web3 verification works

1. freclean-api creates a web3 payment (status requested) when a customer starts checkout in freclean-dapp.
2. The worker (npm run dev:worker) polls freclean-api every POLL_INTERVAL_MS for pending Web3 payments.
3. For each, Web3CeloAdapter.checkStatus() either verifies a reported txHash directly, or scans recent Celo blocks for a matching ERC-20 Transfer into FreClean's treasury wallet.
4. Once a match reaches MIN_CONFIRMATIONS blocks, the worker pushes verified (then confirmed, once freclean-api's own transition rules allow it) back through POST /api/payments/:id/transition.

No step here can jump a payment straight to confirmed — see isForwardTransition in src/core/types.ts, enforced identically in freclean-api.

CeloHT integration status

FreClean's CeloHT partnership is real, but CeloHT's exact webhook payload and signing header are Not provided as of this writing. src/webhook/celoHtWebhook.ts implements the verification pattern FreClean will use (HMAC-SHA256, constant-time compare) with a placeholder payload type — filling in the real shape once CeloHT documents it should not require touching anything else in this service.

Getting started

npm install
cp .env.example .env
npm test
npm run dev:worker      # starts the polling loop

Roadmap for this repo

• Add the first real entry to the Supported Assets Registry once an asset is verified
• Replace the default public Celo RPC with a dedicated provider
• Wire the real CeloHT webhook payload once documented
• Card adapter: integrate a real processor
• Add retry/backoff for pushTransition failures

Security

See SECURITY.md — in particular: this service never holds a private key.

License

Not provided.