💳 BTSBots On-Chain Instant Payment Integration Developer Guide

This document guides third-party merchants (e-commerce, digital subscriptions, GameFi, etc.) on how to integrate zero-fee, instant crypto payments on the BitShares blockchain via BTSBots.

---

💡 1. Payment Architecture & Workflow

[ Buyer / User ] ---- (1) Submit Order on Merchant Web ----> [ Merchant Web ]
     |                                                           | (2) Generate Prefixed Memo
     |                                                           v
     +---- (3) Send On-Chain Transfer (Memo) ----> [ BitShares Blockchain ]
                                                         |
                                                         v (WebSocket Stream)
[ Merchant System ] <--- (5) HTTP POST Callback Notification --- [ BizBots Daemon ]

1. Order Generation: Merchant generates order ID with prefix, e.g., exa_order_883921.
2. Transfer: User scans QR code using BTSBots Wallet App and transfers funds.
3. On-Chain Monitoring: Merchant's biz_bots.py listens for transfers and decrypts on-chain memos.
4. Fulfillment: biz_bots.py verifies amount and asset, sending a signed POST callback to the merchant server.

---

⚙️ 2. Configuring biz_rules.json

{
  "description": "Merchant Payment Listener Routing",
  "updated_at": "2026-08-12 20:00:00",
  "pay_endpoint": {
    "exa_": "https://api.my-shop.com/v1/payment/checkout-notify",
    "sub_": "https://api.my-shop.com/v1/payment/subscription-notify"
  }
}

---

🛠️ 3. Option A: Querying Status via biz_proxy.py

Query order status via internal proxy API: GET /biz-internel/check-payment?order_id=exa_2026081299&app_id=my-shop.com.

---

💻 4. Option B: Custom Web Payment Callback Example (FastAPI)

import json
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from btsbots.graphene_light import verify_message as bts_verify_message

app = FastAPI()

TRUSTED_BOT_PUBKEY = "BTS6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV"

class PaymentCallbackPayload(BaseModel):
    data: str
    pubkey: str
    signature: str

@app.post("/v1/payment/checkout-notify")
async def handle_payment_notification(payload: PaymentCallbackPayload):
    if payload.pubkey != TRUSTED_BOT_PUBKEY:
        raise HTTPException(status_code=403, detail="Untrusted notification source")

    if not bts_verify_message(payload.data, payload.signature, payload.pubkey):
        raise HTTPException(status_code=400, detail="Invalid payment signature")

    pay_data = json.loads(payload.data)
    order_id = pay_data.get("order_id")
    tx_id = pay_data.get("tx_id")
    amount = float(pay_data.get("amount"))
    asset = pay_data.get("asset")

    print(f"💰 [Payment Received]: Order {order_id} | On-Chain TX: {tx_id} | Amount: {amount} {asset}")

    return {"status": "ok"}

---

🔗 5. Standard Payment QR Scheme

btsbots://transfer?to=merchant_account&asset=CNY&amount=150&memo=exa_2026081299&goods=VIP%20Annual%20Subscription