# Dokumentasi Integrasi Mbongshop API (v3)

Dokumentasi ini ditujukan bagi Software Engineer / Developer yang akan mengintegrasikan sistem dengan layanan Host-to-Host (H2H) dan REST API Mbongshop.

Dokumentasi ini terhubung langsung ke **Environment Staging / Simulator**:
* **Base URL:** `https://mbongshop-simulate.app-staging.my.id`
* **Web Simulator Dashboard:** [https://mbongshop-simulate.app-staging.my.id/](https://mbongshop-simulate.app-staging.my.id/)
* **Format Request & Response:** JSON (`application/json`)
* **Protokol:** HTTPS

---

## 1. Autentikasi & Header

Setiap request ke API wajib menyertakan **API Key** pada header HTTP `Authorization`:

```http
Authorization: Bearer dbc1bce5-f3da-4438-97e3-5f398b4f8fcc
Content-Type: application/json
Accept: application/json
```

| Header | Wajib? | Nilai / Format | Keterangan |
| :--- | :---: | :--- | :--- |
| `Authorization` | **Ya** | `Bearer <API_KEY>` | Kunci autentikasi reseller/merchant |
| `Content-Type` | **Ya** | `application/json` | Format body pengiriman request |
| `Accept` | Opsional | `application/json` | Ekspektasi format balasan |

> [!NOTE]
> Pada lingkungan produksi Mbongshop sesungguhnya, IP Address server backend Anda juga wajib didaftarkan (di-whitelist) melalui dashboard merchant Mbongshop.

---

## 2. Format Respon Standar

Semua respon API mengembalikan format wrapper standar:

### Respon Sukses (HTTP 200)
```json
{
  "error": false,
  "code": 200,
  "message": "Success",
  "data": { ... }
}
```

### Respon Gagal (HTTP 4xx / 5xx)
```json
{
  "error": true,
  "code": 400,
  "message": "Pesan deskripsi error"
}
```

---

## 3. Daftar Endpoint API

### 3.1. Cek Saldo Akun (Check Balance)

Digunakan untuk memeriksa sisa deposit saldo reseller.

* **Endpoint:** `/api/v3/balance`
* **Method:** `POST` atau `GET`
* **Request Body:** Tidak ada / `{}`

#### Contoh Request (cURL)
```bash
curl -sSL -X POST "https://mbongshop-simulate.app-staging.my.id/api/v3/balance" \
  -H "Authorization: Bearer dbc1bce5-f3da-4438-97e3-5f398b4f8fcc" \
  -H "Content-Type: application/json"
```

#### Contoh Respon (HTTP 200)
```json
{
  "error": false,
  "code": 200,
  "message": "Success",
  "data": {
    "id": 6937,
    "username": "giyoboo95",
    "membership": "gold",
    "balance": 973556
  }
}
```

---

### 3.2. Mengambil Daftar Produk (Get Products)

Mendapatkan daftar seluruh game/kategori produk yang tersedia beserta struktur input form (misalnya kebutuhan `User ID`, `Zone ID`, dll).

* **Endpoint:** `/api/v3/product`
* **Method:** `POST`
* **Request Body:** `{}`

#### Contoh Respon (HTTP 200)
```json
{
  "error": false,
  "code": 200,
  "message": "Success",
  "data": [
    {
      "code": "8BP",
      "name": "8 Ball Poll",
      "isActive": true,
      "inputs": [
        {
          "name": "ID",
          "type": "text",
          "title": "ID",
          "options": [],
          "placeholder": "",
          "minLength": 0,
          "maxLength": 0,
          "regexValidation": ""
        }
      ]
    },
    {
      "code": "MLBB",
      "name": "Mobile Legends",
      "isActive": true,
      "inputs": [
        {
          "name": "User ID",
          "type": "text",
          "title": "User ID"
        },
        {
          "name": "Zone ID",
          "type": "text",
          "title": "Zone ID"
        }
      ]
    }
  ]
}
```

---

### 3.3. Mengambil Daftar Varian Produk (Get Variants)

Mendapatkan seluruh daftar item/denom beserta harga modal reseller.

* **Endpoint:** `/api/v3/variant`
* **Method:** `POST`
* **Request Body:** `{}`

#### Contoh Respon (HTTP 200)
```json
{
  "error": false,
  "code": 200,
  "message": "Success",
  "data": [
    {
      "id": 4056,
      "code": "AB_PP",
      "name": "Pilihan Pemula",
      "isActive": true,
      "price": 13222,
      "processDuration": 0
    },
    {
      "id": 771,
      "code": "FF_ID_140",
      "name": "140 Diamonds",
      "isActive": true,
      "price": 18366,
      "processDuration": 0
    }
  ]
}
```

---

### 3.4. Mengambil Detail Varian Berdasarkan Kode (Get Variant Detail)

* **Endpoint:** `/api/v3/variant/{code}`
* **Method:** `POST`
* **Parameter URL:** `{code}` — Kode varian produk (contoh: `AB_PP`, `FF_ID_140`)

#### Contoh Request (cURL)
```bash
curl -sSL -X POST "https://mbongshop-simulate.app-staging.my.id/api/v3/variant/AB_PP" \
  -H "Authorization: Bearer dbc1bce5-f3da-4438-97e3-5f398b4f8fcc"
```

#### Contoh Respon (HTTP 200)
```json
{
  "error": false,
  "code": 200,
  "message": "Success",
  "data": {
    "id": 4056,
    "code": "AB_PP",
    "name": "Pilihan Pemula",
    "isActive": true,
    "price": 13222,
    "processDuration": 0
  }
}
```

---

### 3.5. Membuat Transaksi / Checkout (Create Order)

Memproses pembelian atau top-up varian produk.

* **Endpoint:** `/api/v3/checkout` atau `/api/v3/order`
* **Method:** `POST`
* **Request Body (JSON):**

| Parameter | Tipe Data | Wajib? | Keterangan |
| :--- | :---: | :---: | :--- |
| `code` | String | **Ya** | Kode varian produk (contoh: `AB_PP`, `FF_ID_140`). Alias: `variant_code`. |
| `target` | String / Object | **Ya** | Nomor tujuan / Player ID / Zone ID penerima. |
| `ref_id` | String | **Ya** | Invoice / Transaction Reference ID unik dari sistem merchant Anda. |
| `callback_url` | String | Opsional | URL webhook endpoint server Anda untuk menerima notifikasi otomatis saat transaksi selesai. |

#### Contoh Payload Request
```json
{
  "code": "AB_PP",
  "target": "12345678",
  "ref_id": "TRX-APP-20261027-001",
  "callback_url": "https://api-kamu.com/api/callback/mbongshop"
}
```

#### Contoh Request (cURL)
```bash
curl -sSL -X POST "https://mbongshop-simulate.app-staging.my.id/api/v3/checkout" \
  -H "Authorization: Bearer dbc1bce5-f3da-4438-97e3-5f398b4f8fcc" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "AB_PP",
    "target": "12345678",
    "ref_id": "TRX-APP-20261027-001",
    "callback_url": "https://api-kamu.com/api/callback/mbongshop"
  }'
```

#### Respon Berhasil (HTTP 200)
```json
{
  "error": false,
  "code": 200,
  "message": "Success",
  "data": {
    "invoiceNumber": "MBS-20261027030348-9451",
    "ref_id": "TRX-APP-20261027-001",
    "code": "AB_PP",
    "name": "Pilihan Pemula",
    "price": 13222,
    "status": "PROCESSING",
    "target": "12345678",
    "sn": "SN-20261027030348524211",
    "balance_before": 986778,
    "balance_after": 973556,
    "created_at": "2026-10-27T03:03:48.803Z"
  }
}
```

#### Respon Gagal (Saldo Kurang)
```json
{
  "error": true,
  "code": 400,
  "message": "Saldo tidak mencukupi. Sisa saldo: Rp 5.000, Harga produk: Rp 13.222"
}
```

---

### 3.6. Cek Status Order (Check Order Status)

Digunakan untuk melakukan inquiry status pesanan.

* **Endpoint:** `/api/v3/order/{invoiceNumber}`
* **Method:** `POST` atau `GET`
* **Parameter URL:**
  * `{invoiceNumber}` — Mendukung pencarian menggunakan **Nomor Invoice Mbongshop** (`MBS-...`) **ATAU** menggunakan **`ref_id`** unik dari sistem Anda!

#### Contoh Request (cURL)
```bash
# Inquiry menggunakan ref_id sistem merchant
curl -sSL -X POST "https://mbongshop-simulate.app-staging.my.id/api/v3/order/TRX-APP-20261027-001" \
  -H "Authorization: Bearer dbc1bce5-f3da-4438-97e3-5f398b4f8fcc"
```

#### Respon Berhasil (HTTP 200)
```json
{
  "error": false,
  "code": 200,
  "message": "Success",
  "data": {
    "invoiceNumber": "MBS-20261027030348-9451",
    "ref_id": "TRX-APP-20261027-001",
    "code": "AB_PP",
    "name": "Pilihan Pemula",
    "price": 13222,
    "status": "SUCCESS",
    "target": "12345678",
    "sn": "SN-20261027030348524211",
    "note": "Transaksi Berhasil",
    "balance_before": 986778,
    "balance_after": 973556,
    "created_at": "2026-10-27T03:03:48.803Z",
    "updated_at": "2026-10-27T03:03:51.827Z"
  }
}
```

---

## 4. Webhook / Callback Notifikasi

Ketika Anda menyertakan parameter `callback_url` pada saat checkout, server Mbongshop Simulator akan secara otomatis menembak endpoint webhook Anda dalam kurun waktu ~3 detik setelah status berubah menjadi `SUCCESS` atau `FAILED`.

### 4.1. Spesifikasi Payload Webhook

* **HTTP Method:** `POST`
* **Content-Type:** `application/json`
* **User-Agent:** `Mbongshop-Webhook/3.0`

#### Contoh Payload yang Diterima Server Anda:
```json
{
  "invoiceNumber": "MBS-20261027030348-9451",
  "ref_id": "TRX-APP-20261027-001",
  "code": "AB_PP",
  "name": "Pilihan Pemula",
  "price": 13222,
  "status": "SUCCESS",
  "target": "12345678",
  "sn": "SN-20261027030348524211",
  "note": "Transaksi Berhasil",
  "updated_at": "2026-10-27T03:03:51.827Z"
}
```

### 4.2. Ekspektasi Respon Callback

Endpoint callback Anda wajib merespon dengan status **HTTP 200 OK**:
```json
{
  "status": "ok"
}
```

---

## 5. Status Transaksi

| Nilai Status | Keterangan |
| :--- | :--- |
| `PROCESSING` | Pesanan sedang dalam antrean atau sedang dikirimkan ke provider game |
| `SUCCESS` | Transaksi berhasil dan Serial Number (SN) telah diterbitkan |
| `FAILED` | Transaksi gagal (misal: ID tujuan salah atau gangguan sistem), saldo di-refund |

---

## 6. Contoh Implementasi Kode

### 6.1. Node.js (JavaScript / TypeScript - Fetch API)

```typescript
const BASE_URL = 'https://mbongshop-simulate.app-staging.my.id';
const API_KEY = 'dbc1bce5-f3da-4438-97e3-5f398b4f8fcc';

// 1. Cek Saldo
async function checkBalance() {
  const res = await fetch(`${BASE_URL}/api/v3/balance`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    }
  });
  return await res.json();
}

// 2. Checkout Pesanan
async function createOrder(variantCode, targetUserId, merchantRefId, callbackUrl) {
  const res = await fetch(`${BASE_URL}/api/v3/checkout`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      code: variantCode,
      target: targetUserId,
      ref_id: merchantRefId,
      callback_url: callbackUrl
    })
  });
  return await res.json();
}

// 3. Cek Status Pesanan
async function checkOrderStatus(invoiceOrRefId) {
  const res = await fetch(`${BASE_URL}/api/v3/order/${encodeURIComponent(invoiceOrRefId)}`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });
  return await res.json();
}
```

---

### 6.2. PHP (cURL)

```php
<?php

class MbongshopClient {
    private $baseUrl = 'https://mbongshop-simulate.app-staging.my.id';
    private $apiKey  = 'dbc1bce5-f3da-4438-97e3-5f398b4f8fcc';

    private function request($endpoint, $payload = null) {
        $ch = curl_init($this->baseUrl . $endpoint);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->apiKey,
            'Content-Type: application/json',
            'Accept: application/json'
        ]);

        if ($payload !== null) {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
        }

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        return json_decode($response, true);
    }

    public function getBalance() {
        return $this->request('/api/v3/balance', []);
    }

    public function checkout($variantCode, $target, $refId, $callbackUrl = null) {
        return $this->request('/api/v3/checkout', [
            'code'         => $variantCode,
            'target'       => $target,
            'ref_id'       => $refId,
            'callback_url' => $callbackUrl
        ]);
    }

    public function getOrderStatus($invoiceOrRefId) {
        return $this->request('/api/v3/order/' . urlencode($invoiceOrRefId), []);
    }
}

// Contoh Penggunaan:
$client = new MbongshopClient();
$order = $client->checkout('AB_PP', '12345678', 'INV-' . time(), 'https://domain-anda.com/webhook');
print_r($order);
```

---

### 6.3. Python (Requests)

```python
import requests

BASE_URL = "https://mbongshop-simulate.app-staging.my.id"
API_KEY = "dbc1bce5-f3da-4438-97e3-5f398b4f8fcc"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# 1. Cek Saldo
def get_balance():
    response = requests.post(f"{BASE_URL}/api/v3/balance", headers=headers)
    return response.json()

# 2. Checkout Pesanan
def checkout(variant_code, target_id, ref_id, callback_url=None):
    payload = {
        "code": variant_code,
        "target": target_id,
        "ref_id": ref_id,
        "callback_url": callback_url
    }
    response = requests.post(f"{BASE_URL}/api/v3/checkout", json=payload, headers=headers)
    return response.json()

# 3. Cek Status Pesanan
def check_order(invoice_or_ref_id):
    response = requests.post(f"{BASE_URL}/api/v3/order/{invoice_or_ref_id}", headers=headers)
    return response.json()

# Jalankan contoh
if __name__ == "__main__":
    print(get_balance())
```

---

## 7. Web Simulator Dashboard

Untuk mempermudah tim developer menguji skenario tanpa perlu membuka database SQLite secara langsung:

Kunjungi: **[https://mbongshop-simulate.app-staging.my.id/](https://mbongshop-simulate.app-staging.my.id/)**

Fitur Dashboard:
1. **Atur Saldo:** Mengubah nominal saldo deposit simulasi secara instan.
2. **Form Checkout:** Menjalankan order langsung dari web browser.
3. **Tabel Riwayat Transaksi:** Memantau status pesanan (`PROCESSING`, `SUCCESS`, `FAILED`) secara real-time.
4. **Manual Status Override:** Tombol untuk mensimulasikan order berhasil (*Success*) atau gagal (*Failed*).
5. **Manual Trigger Webhook:** Tombol untuk mengirim ulang (*re-trigger*) webhook callback ke URL server Anda.