The dedicated settlement backend for HaloPay — a self-custodied Point-of-Sale and merchant settlement protocol built for crisis zones and offline environments where traditional digital banking infrastructure does not exist.
- SEP-10 Web Authentication: Standardized Stellar challenge-response flow issuing JWTs for secure merchant interactions.
- SEP-12 KYC Ingestion: Ingests merchant verification fields and binary government ID photos (
multipart/form-data) to transmit to Stellar anchors (e.g. MoneyGram). - SEP-24 Fiat Off-Ramp Orchestration: Programmatically converts aggregated USDC daily sales into local fiat via anchor off-ramp quotes and withdrawals.
- On-Chain Webhook & WebSocket Broadcaster: Listens to Stellar Horizon payment streams for incoming USDC aid payments and broadcasts instant payment confirmations to merchant POS devices over WebSockets.
graph TD
Client[HaloPay POS Client] -->|SEP-10 Auth| API[HaloPay API]
API -->|KYC & Settlement| Anchor[Stellar Anchor / MoneyGram]
Horizon[Stellar Horizon] -->|Webhook| API
API -->|WebSocket| Client
The HaloPay backend is entirely focused on providing a seamless bridge between a merchant who may have intermittent connectivity and the robust Stellar on-chain ecosystem.
- Authentication (SEP-10): Merchants sign an authentication challenge using their private Stellar key. The API verifies this signature and issues a JWT. This ensures that the backend only orchestrates fiat withdrawals for verifiable wallet owners.
- KYC Uploads (SEP-12): To comply with local regulations and anchor requirements, merchants must upload their government ID. Since these files are often large binary images, the API implements a secure
multipart/form-dataingestion route that validates file sizes and MIME types before forwarding the payload directly to a secure storage bucket and the Anchor. - Fiat Off-Ramp (SEP-24): When a merchant chooses to settle their USDC balance to local fiat (e.g., to their bank account or mobile money wallet), the API initiates the SEP-24 interactive withdrawal flow with an anchor like MoneyGram, abstracting away the complex Stellar network fees and reserve requirements.
- Resilient WebSocket Delivery: Since POS terminals can drop connection at any time, the API maintains a constant listener on the Stellar Horizon network. When it detects a payment to a registered merchant, it broadcasts it. If the merchant reconnects later, the system will instantly push any missed payments so the UI always reflects the true ledger state.
- Language: TypeScript (Node.js 20+)
- Framework: Express.js
- Blockchain Core:
@stellar/stellar-sdk - File Ingestion:
multer(handling multipart binary government ID images) - Real-Time Communication:
ws(WebSockets) - Validation & Auth: Zod, JSON Web Tokens
# Clone the repository
git clone https://github.com/HaloPaye/halopay-api.git
cd halopay-api
# Install dependencies
npm install
# Run dev environment
npm run dev
# Run unit tests
npm test| Maintainer | Contact / Telegram | Role |
|---|---|---|
| HaloPay Team | @HaloPayDev | Core Protocol Engineering |
| Lead Engineer | security@halopay.io | Security & Operations |
This project is licensed under the MIT License - see the LICENSE file for details.