VinMin Codex

⌂ Chapter 05 · Commerce & Merchants

Commerce & Merchant Rails

[Spec]Shopkeeper loyalty vouchers, returns-to-voucher, and the POS QR verification API for Hearth Partners.

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.

POSThttps://api.vinmin.gg/v1/pos/verify

Verify 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.

POSThttps://api.vinmin.gg/v1/pos/return-voucher

Issue 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" }
Next chapter →6. MOZI Cognitive Engine & Developer Bridges