Developer Guides

Set up the HaloPay environment locally to build and test features.

Prerequisites

Node.js (v18+)
Stellar testnet account
PostgreSQL (if running a local database)

Initializing the API Backend

The halopay-api repository houses the Express server handling authentication, KYC routing, and webhook ingestion. Clone the repository to your local workspace and resolve dependencies.

cd halopay-api
npm install
npm run dev

The server binds to port 4000 by default and initializes the WebSocket listener on the /ws/payments route. You must define several critical environment variables in a local .env file to establish network connectivity.

Variable	Description
`PORT`	Defines the listening port for the Express HTTP server.
`STELLAR_NETWORK`	Dictates the target ledger. Acceptable values are `TESTNET` or `PUBLIC`.
`ANCHOR_HOME_DOMAIN`	Specifies the domain of the liquidity partner for SEP-10 challenge generation.
`SIGNING_SEED`	Holds the private Ed25519 cryptographic key for signing automated anchor requests.

Bootstrapping the POS Client

The halopay-pos repository contains the Next.js frontend. Navigate into the directory, install dependencies, and launch the application.

cd halopay-pos
npm install
npm run dev

The Next.js framework compiles the React components and launches the local server on port 3000.

The application utilizes a service worker for offline caching. You must test PWA functionality using a Chromium-based browser with network throttling enabled in the developer tools. Simulate an offline state to verify the QR generator logic successfully constructs URIs using the fallback exchange rates stored in local storage.

Review the technical reference documentation to understand the event lifecycle between the frontend components and the backend WebSocket broadcaster.

End-User Guides Technical Reference