SUBTC Protocol Integration with BILLmanager — Overview (Russian Hosting Billing System)

## 1. Introduction

BILLmanager (from ISPsystem) is a widely used Russian billing and hosting automation platform for:
- VPS management
- Dedicated servers
- Shared hosting
- Domain provisioning

Integrating SUBTC Protocol turns BILLmanager into a **fully automated Bitcoin-native billing system**.

---

## 2. Integration Concept

SUBTC acts as the **Bitcoin payment execution layer**
BILLmanager acts as the **service provisioning and billing layer**

Flow:

Client → BILLmanager Invoice → SUBTC API → Bitcoin Network → Payment Confirmation → Service Activation

---

## 3. Integration Architecture

### 1. Payment Module (BILLmanager Gateway)

BILLmanager supports custom payment modules via PHP.

Create a module such as:

/usr/local/mgr5/pm/billmgr/subtc/

Responsibilities:
- Generate BTC payment address per invoice
- Attach wallet_id to invoice
- Track payment status
- Confirm and finalize invoice

---

### 2. SUBTC API Communication Layer

BILLmanager communicates with SUBTC using HTTP (curl or PHP requests).

Core API methods:
- wallet_create
- wallet_receive
- wallet_poll
- wallet_wait_event
- wallet_send (for refunds or payouts)

---

## 4. Payment Flow

### Step 1 — Invoice Creation

BILLmanager creates invoice:
- service_id
- user_id
- amount (converted to satoshis)

---

### Step 2 — Generate Bitcoin Address

$response = curl_post("https://api.subtc.net/v1/btc?mode=wallet_receive", [
  "wallet_id" => $wallet_id
]);

$address = $response["address"];

The address is shown in BILLmanager client panel.

---

Step 3 — Customer Payment

User sends BTC to the generated address.

BILLmanager stores:

invoice_id

address

expected_sat

---

Step 4 — Payment Monitoring

Option A: Polling

curl_post("https://api.subtc.net/v1/btc?mode=wallet_poll", [
  "wallet_id" => $wallet_id,
  "address" => $address,
  "expected_sat" => $amount_sat
]);

Option B: Webhook (Recommended)

curl_post("https://api.subtc.net/v1/btc?mode=wallet_wait_event", [
  "wallet_id" => $wallet_id,
  "address" => $address,
  "expected_sat" => $amount_sat,
  "callback_url" => "https://your-billmanager.com/subtc-webhook"
]);

---

Step 5 — Service Activation

When:

received_sat >= expected_sat

BILLmanager automatically:

Marks invoice as paid

Activates hosting/VPS/dedicated server

Sends confirmation email to client

---

5. Webhook Handler Example

$data = json_decode(file_get_contents("php://input"), true);

if ($data["reached"] && $data["received_sat"] >= $data["expected_sat"]) {
    mark_invoice_paid($data["invoice_id"]);
    activate_service($data["service_id"]);
}

---

6. Wallet Strategy

Recommended structure:

Hot Wallet (payment processing layer)

Billing Wallet (BILLmanager operational funds)

Cold Wallet (secure storage / treasury)

Best practice:

Automatic periodic withdrawal from hot wallet

Separate accounting per client service

---

7. Security Best Practices

Store X-SUBTC-KEY securely (never in frontend)

Use HTTPS for all callbacks

Validate webhook signatures (if enabled)

Use idempotency headers to prevent duplicate payments

Isolate billing server from public API exposure

Optional: deploy via Docker or VM sandbox

---

8. Advantages of SUBTC + BILLmanager

No Bitcoin node required

No RPC / blockchain sync complexity

Works on Mainnet & Testnet

Fully API-driven automation

Compatible with AI agents and scripts

Lightweight curl-based architecture

---

9. Use Cases

Russian hosting providers

VPS / dedicated server companies

Domain registrars

Cloud infrastructure providers

SaaS billing automation

---

10. Conclusion

SUBTC transforms BILLmanager into a Bitcoin-native billing engine.

BILLmanager = billing + provisioning system
SUBTC = Bitcoin payment execution layer

Result:

→ Fully automated hosting infrastructure with native Bitcoin payments, minimal complexity, and high automation readiness.