⌂ Chapter 05 · Commerce & Merchants
Commerce & Merchant Rails
Local Business & Merchant Network
Independent diaspora and regional merchants (bookshops, restaurants, cultural artisans) can register as verified Hearth Partners.
Shopkeeper Loyalty Vouchers[Spec]
- Partners issue community discounts or reward Min to members who present a valid pass.
- Vouchers are store credit only — redeemable at the issuing partner, never convertible to cash.
Point-of-Sale (POS) QR Verification[Spec]
The merchant scans the customer’s Apple/Google Wallet pass or physical card QR code. The system verifies membership validity and applies eligible community discounts or deposits reward Min.
https://api.vinmin.gg/v1/pos/verifyVerify a scanned pass or card QR at the point of sale.
Header: authorization: Bearer <merchant_key>
Body
{ "qr": "vm1:WP-000000", "merchant_id": "hp_madurai_books" }Response 200
{ "valid": true, "member_tier": "Witness", "eligible_discount_pct": 10, "era": "Aarambam" }Return to Loyalty Voucher
If a customer returns a product, the merchant can issue a loyalty refund directly into the member’s VinMin wallet pass as a store credit voucher, keeping capital circulating locally.
https://api.vinmin.gg/v1/pos/return-voucherIssue a returns-to-voucher store credit onto a member pass.
Header: authorization: Bearer <merchant_key>
Body
{ "qr": "vm1:WP-000000", "amount_minor": 1250, "currency": "GBP", "reason": "return" }Response 200
{ "voucher_id": "vch_8f2a", "status": "issued", "redeemable_at": "hp_madurai_books" }