MineCommerce

Tebex-like self-hosted shop plugin for Paper 1.21 — sell ranks, items, and packages directly through your WooCommerce or Shopify store with Stripe payments, without high fees or third-party lock-in.

MineCommerce connects your store and your Minecraft server:

• Players buy on your store (WooCommerce/Shopify + Stripe).
• Webhooks trigger fulfillment in-game.
• Deliverables: items, ranks (LuckPerms), currency (Vault), or custom commands.

---

Features

• WooCommerce + Shopify support
• SQLite (default), MySQL, Postgres database support
• Account linking (/minecommerce link <code>)
• Order fulfillment (commands, items, ranks, currency)
• Refunds & revokes with audit logging
• Retry queue with persistence across restarts
• Bedrock UI support (via Floodgate + Geyser)
• Store GUI with categories and product images
• Scheduled sync or real-time webhooks
• Configurable mappings (mappings.yml)
• JSON logs + REST API for monitoring
• Secure webhook verification (HMAC)

---

Installation

1. Download the latest MineCommerce.jar.

2. Drop into your server’s plugins/ folder.

3. Restart the server to generate configs:

   • config.yml
   • mappings.yml
   • minecommerce.db (if SQLite)

---

Configuration

config.yml

server:
  http_enabled: true
  http_port: 8443
  webhook_secret: "CHANGE_ME"
  store_url: "https://example.com/store"
  platform: woocommerce   # generic|woocommerce|shopify
  link_template: ""

delivery:
  retry_attempts: 5
  retry_backoff_seconds: 60

link:
  code_length: 6
  code_ttl_seconds: 900

security:
  verify_ssl: true
  max_webhook_age_seconds: 600

database:
  type: sqlite
  sqlite:
    path: minecommerce.db
  mysql:
    host: 127.0.0.1
    port: 3306
    user: minecommerce
    password: secret_password
    database: minecommerce
    ssl: true
  postgres:
    host: 127.0.0.1
    port: 5432
    user: minecommerce
    password: secret_password
    database: minecommerce
    ssl: true

woocommerce:
  base_url: "https://yourstore.example"
  consumer_key: "ck_..."
  consumer_secret: "cs_..."

shopify:
  shop: "your-shop"
  api_version: "2024-07"
  access_token: "shpat_..."

sync:
  enabled: true
  schedule_minutes: 60
  mode: write_mappings
  image_as_button: true

---

mappings.yml

Link SKUs from WooCommerce/Shopify → in-game actions.

products:
  vip_30d:
    name: "VIP Rank (30 days)"
    icon: "EMERALD"
    price: 9.99
    description: "30 days of VIP access"
    product_id: "123"       # WooCommerce product ID
    variant_id: "45678901"  # Shopify variant ID
    actions:
      - type: permission_group
        group: vip
        duration_days: 30
      - type: command
        command: "say {player} is now a VIP!"
      - type: currency
        amount: 1000

categories:
  featured:
    name: "Featured"
    icon: "GOLD_INGOT"
    description: "Top picks"
    skus:
      - vip_30d

Actions supported: command, permission_group, currency, item. Placeholders: {player}, {uuid}, {order_id}, {sku}.

---

Sync & Webhooks

Manual Sync

/minecommerce admin sync

• Fetches products & categories
• Rewrites mappings.yml
• Updates images, SKUs, variants

Scheduled Sync

Configured via:

sync:
  enabled: true
  schedule_minutes: 60

Webhooks

• Endpoint: POST http://<server>:<port>/api/v1/sync
• Secure via X-Timestamp + X-Signature (HMAC SHA256 with webhook_secret)

---

Shopify Delta

• Endpoint: /api/v1/webhooks/shopify
• Example payload:

{ "id": 9876543210 }

WooCommerce Delta

• Endpoint: /api/v1/webhooks/woocommerce
• Example payload:

{ "resource": "product", "id": 12345 }

---

Commands

Command	Permission	Description
/store	minecommerce.store	Open in-game store GUI / send store link
/minecommerce link <code>	—	Link player to store account
/minecommerce status	—	Check order status
/minecommerce admin sync	minecommerce.admin	Run manual sync
/minecommerce admin deliver <id>	minecommerce.admin	Manually deliver order
/minecommerce admin revoke <id>	minecommerce.admin	Revoke an order
/minecommerce admin reload	minecommerce.admin	Reload config

---

Security

• HMAC-signed webhook verification
• Timestamp validation (max_webhook_age_seconds)
• Idempotent deliveries (no duplication)
• No card data stored (handled by Stripe)

---

Example Flow

1. Player buys VIP (30 days) on WooCommerce/Shopify.

2. Store → Stripe → order completed.

3. Webhook → MineCommerce plugin.

4. Plugin looks up SKU → runs mapped actions:

   • Add LuckPerms group vip (30d expiry).
   • Give 1000 Vault currency.
   • Run custom server command.

5. Delivery logged; retries if failure.

---

Troubleshooting

• No products found: check API credentials and published products.
• Images not showing: enable image_as_button: true and confirm product has images.
• Webhook 401 errors: re-check signature generation and webhook secret.
• SQLite locking: migrate to MySQL/Postgres for production.

---

Roadmap

• [x] SQLite support
• [x] MySQL/Postgres support
• [x] LuckPerms & Vault integration
• [x] REST API (/api/v1/orders, /api/v1/refunds, /api/v1/health)
• [x] Refunds/revokes

---

Soft Dependencies

• LuckPerms — ranks/permissions
• Vault — economy integration
• Floodgate + Geyser — Bedrock UI with images

---

Support

• Issues & feature requests: GitHub tracker
• Logs: plugins/MineCommerce/logs/
• Configs: config.yml, mappings.yml (remove secrets)