Farouqui-fx/amana-escrow

# Amana — Escrow for social commerce **Amana** (Hausa/Arabic: trust, a thing kept safe) is an escrow layer for Instagram and Twitter/X vendors in Nigeria. Buyers pay into escrow instead of straight to a seller's account; sellers only get paid once the buyer confirms the item arrived. Built for the Nomba Challenge hackathon, using Nomba's Checkout, Transfers, and Webhooks APIs. ## How it works 1. Seller creates an order (product, price, their bank details) and gets a shareable link. 2. Buyer opens the link and pays via Nomba's hosted checkout (card or transfer). 3. Nomba sends a **webhook** to Amana's server confirming payment → order flips to "held in escrow." 4. Buyer clicks "I received my order" → Amana calls Nomba's transfer API to pay the seller. This is a **webhook-native** design on purpose: the server never polls Nomba for payment status — it reacts to the `payment_success` event the moment Nomba sends it, which is what makes the buyer's page update live without a refresh. ## Project structure ``` amana/ backend/ Express API + webhook handler + Nomba client server.js src/ nombaClient.js auth, checkout orders, bank lookup, payouts db.js simple JSON-file order store (swap for Postgres later) routes/orders.js order CRUD, pay, confirm-delivery routes/webhook.js receives Nomba's payment_success events utils/verifySignature.js HMAC signature check frontend/ Static seller dashboard + buyer order page (vanilla JS) ``` ## Setup 1. **Get Nomba API credentials**: log into your Nomba dashboard → Settings → API Keys, and Settings → Webhooks. You'll need `accountId`, `client_id`, `client_secret`, and (once you register a webhook URL) a signature key. 2. **Install & configure the backend:** ```bash cd backend npm install cp .env.example .env # fill in NOMBA_ACCOUNT_ID, NOMBA_CLIENT_ID, NOMBA_CLIENT_SECRET, NOMBA_SIGNATURE_KEY ``` 3. **Expose your server for Nomba's webhook** (Nomba needs a public URL to POST to). Duri …