Dokumentasi API Reseller MokuGram

Sistem API Host-to-Host (H2H) resmi untuk integrasi otomatis top up Telegram Stars dan Telegram Premium ke aplikasi, website e-commerce, atau bot Anda secara instan 24/7.

⚡ Autentikasi API

Seluruh panggilan endpoint API Reseller wajib menyertakan autentikasi menggunakan API Key akun Anda. API Key dapat diperoleh melalui dashboard pengguna atau dibuatkan oleh Admin.

Metode Autentikasi yang Didukung:
  • Header: X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxx (Sangat Direkomendasikan)
  • Header: Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
  • Parameter URL: ?api_key=sk_live_xxxxxxxxxxxxxxxxxxxx

Base URL Server:

Production Base URL 
https://mokugram.com

1. Profil Reseller & Cek Saldo

GET POST /api/v1/reseller/profile

Mengambil informasi detail akun reseller, sisa saldo IDR aktif, role akun, dan webhook URL yang terdaftar.

Contoh Response (JSON) 
{
  "status": true,
  "message": "Profil reseller berhasil diambil",
  "data": {
    "user_id": 12,
    "username": "reseller_pro",
    "name": "Toko Digital Sejahtera",
    "role": "RESELLER",
    "balance": 1500000,
    "api_key": "sk_live_9a8b...4f1e",
    "webhook_url": "https://tokosaya.com/api/mokugram-callback",
    "ip_whitelist": "103.150.22.1",
    "created_at": "2026-09-20 14:30:00"
  }
}

2. Daftar Layanan & Harga

GET /api/v1/reseller/services

Mengambil katalog seluruh produk Telegram Stars dan Telegram Premium aktif beserta kalkulasi harga reseller setelah diskon VIP.

Contoh Response (JSON) 
{
  "status": true,
  "message": "Daftar layanan & harga reseller",
  "pricing_info": {
    "user_role": "RESELLER",
    "reseller_discount_percent": 5.0,
    "min_stars": 50,
    "max_stars": 50000
  },
  "services": {
    "stars": [
      {
        "service_code": "STARS_50",
        "service_type": "STARS",
        "name": "Telegram 50 Stars",
        "amount": 50,
        "regular_price_idr": 14500,
        "reseller_price_idr": 13775,
        "discount_amount_idr": 725,
        "status": "AVAILABLE"
      },
      {
        "service_code": "STARS_100",
        "service_type": "STARS",
        "name": "Telegram 100 Stars",
        "amount": 100,
        "regular_price_idr": 29000,
        "reseller_price_idr": 27550,
        "discount_amount_idr": 1450,
        "status": "AVAILABLE"
      }
    ],
    "premium": [
      {
        "service_code": "PREMIUM_3M",
        "service_type": "PREMIUM",
        "name": "Telegram Premium 3 Bulan",
        "duration_months": 3,
        "regular_price_idr": 231000,
        "reseller_price_idr": 219450,
        "discount_amount_idr": 11550,
        "status": "AVAILABLE"
      }
    ]
  }
}

3. Validasi Username Telegram

POST /api/v1/reseller/check-username

Memvalidasi apakah username Telegram tujuan valid, merupakan akun pengguna perorangan (bukan channel/bot), dan mengecek apakah eligible untuk Telegram Premium.

Parameter Tipe Wajib Keterangan
username String Wajib Username Telegram tujuan (dengan atau tanpa tanda @)
service String Opsional Pilihan: STARS atau PREMIUM (Default: STARS)
duration_months Integer Opsional Durasi jika mengecek Premium: 3, 6, atau 12
Contoh Response (JSON) 
{
  "status": true,
  "valid": true,
  "username": "johndoe",
  "name": "John Doe",
  "photo": "https://...",
  "premium_eligible": true,
  "message": "Username Telegram valid dan siap menerima Stars/Premium"
}

4. Buat Pesanan (Order Execution)

POST /api/v1/reseller/order

Menempatkan order transaksi pembelian Telegram Stars atau Telegram Premium. Biaya pesanan akan dipotong langsung dari saldo akun reseller secara atomic. Jika pengiriman gagal, saldo otomatis dikembalikan (Auto-Refund).

Idempotency Ref ID: Sertakan parameter ref_id unik dari sistem Anda (misal ID transaksi di database Anda). Jika request terputus atau timeout, pengiriman ulang dengan ref_id yang sama TIDAK AKAN mendebit saldo Anda dua kali.
Parameter Tipe Wajib Keterangan
ref_id String Wajib ID referensi unik dari transaksi sistem Anda (3 - 64 karakter)
service String Wajib Jenis layanan: STARS atau PREMIUM
amount Integer Wajib Jumlah Stars (misal 100) atau Durasi Bulan Premium (3, 6, 12)
recipient String Wajib Username Telegram penerima produk (misal: "alexander")
Contoh Response Sukses (HTTP 200) 
{
  "status": true,
  "message": "Transaksi berhasil! 100 STARS sukses dikirim ke @alexander",
  "data": {
    "order_id": 1405,
    "invoice_code": "INV-RES-1727581290-4102",
    "ref_id": "TRX-STORE-9921",
    "service": "STARS",
    "amount": 100,
    "recipient": "alexander",
    "price_idr": 27550,
    "current_balance": 1472450,
    "status": "SUCCESS",
    "tx_hash": "6b3a29f8c14d9b7342e0520b",
    "created_at": "2026-09-29 10:30:15"
  }
}

5. Cek Status Pesanan

GET /api/v1/reseller/status/{identifier}

Mengecek status terkini suatu transaksi. Parameter identifier dapat diisi dengan order_id sistem MokuGram, invoice_code, atau ref_id Anda.

Contoh Response (JSON) 
{
  "status": true,
  "data": {
    "order_id": 1405,
    "invoice_code": "INV-RES-1727581290-4102",
    "ref_id": "TRX-STORE-9921",
    "service": "STARS",
    "amount": 100,
    "recipient": "alexander",
    "price_idr": 27550,
    "status": "SUCCESS",
    "tx_hash": "6b3a29f8c14d9b7342e0520b",
    "error_message": "",
    "created_at": "2026-09-29 10:30:15"
  }
}

7. Webhook & Verifikasi Signature

Jika Anda mendaftarkan Webhook URL di pengaturan akun, server kami akan mengirimkan HTTP POST event secara real-time saat status pesanan selesai (SUCCESS atau FAILED).

Header Keamanan: Setiap request webhook memuat header X-MokuGram-Signature yang merupakan HMAC-SHA256 dari payload JSON menggunakan API Key Anda sebagai secret key.
Verifikasi Signature di PHP 
<?php
$apiKey = "sk_live_your_api_key_here";
$rawPayload = file_get_contents('php://input');
$signatureHeader = $_SERVER['HTTP_X_MOKUGRAM_SIGNATURE'] ?? '';

$expectedSignature = hash_hmac('sha256', $rawPayload, $apiKey);
if (!hash_equals($expectedSignature, $signatureHeader)) {
    http_response_code(401);
    die("Invalid webhook signature");
}

$data = json_decode($rawPayload, true);
// Proses data order: $data['ref_id'], $data['status'], dll.
echo json_encode(["received" => true]);
?>

8. Contoh Kode Pemanggilan API

Berikut adalah contoh siap pakai untuk membuat order di berbagai bahasa pemrograman:

Python (requests) 
import requests

API_KEY = "sk_live_your_api_key_here"
BASE_URL = "https://mokugram.com"

payload = {
    "ref_id": "ORDER-DEMO-001",
    "service": "STARS",
    "amount": 100,
    "recipient": "telegram_username"
}

headers = {
    "Content-Type": "application/json",
    "X-API-Key": API_KEY
}

response = requests.post(f"{BASE_URL}/api/v1/reseller/order", json=payload, headers=headers)
print(response.status_code, response.json())
cURL (Terminal / Bash) 
curl -X POST "https://mokugram.com/api/v1/reseller/order" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: sk_live_your_api_key_here" \
     -d '{
       "ref_id": "ORDER-DEMO-001",
       "service": "STARS",
       "amount": 100,
       "recipient": "telegram_username"
     }'