Host-to-Host API * v1

Dokumentasi API

Integrasikan sistem laman web anda dengan kami sebagai pembekal produk H2H.

Pengenalan

Semua permintaan menggunakan kaedah POST dengan badan JSON. Base URL endpoint:

POST https://bybanana.my/api/v1/{endpoint}

Pengepala Wajib

Content-Type: application/json

Pengesahan & Signature

Setiap permintaan mesti menyertakan api_id, api_key, dan signature dalam badan JSON. Signature dikira menggunakan formula MD5.

API ID

Log masuk untuk melihat

API Key

Log masuk untuk melihat

Formula Signature

signature = HMAC-SHA256(
    METHOD + "|" + PATH + "|" + timestamp + "|" + nonce,
    api_key
)

Aktifkan suis Status Akses API dalam menu Integrasi API, dan pastikan IP pelayan anda didaftarkan dalam IP Whitelist supaya permintaan tidak ditolak.

Cara menghitung signature (PHP)

$apiId     = 'API_ID_ANDA';
$apiKey    = 'API_KEY_ANDA';
$method    = 'POST';
$path      = '/api/v1/profile';          // path LENGKAP dari base_url('api/v1')
$timestamp = time();                     // unix timestamp (detik)
$nonce     = bin2hex(random_bytes(16));  // string acak unik, min 8 karakter

$canonical = $method . '|' . $path . '|' . $timestamp . '|' . $nonce;
$signature = hash_hmac('sha256', $canonical, $apiKey);

$payload = [
    'api_id'    => $apiId,
    'timestamp' => $timestamp,
    'nonce'     => $nonce,
    'signature' => $signature,
    // ...field lain (order_id, service_id, dst)
];

api_key TIDAK dikirim dalam body — hanya dipakai untuk menghitung signature. Field timestamp (±300 detik dari waktu server) dan nonce (unik, tidak boleh dipakai ulang) wajib dikirim. Tiap request butuh signature berbeda. Skema lama md5(api_id + api_key) sudah tidak didukung.

Contoh Badan (semua endpoint)

{
  "api_id": "YOUR_API_ID",
  "timestamp": 1700000000,
  "nonce": "a1b2c3d4e5f6",
  "signature": "HMAC-SHA256(POST|/api/v1/profile|1700000000|a1b2c3d4e5f6, api_key)"
}

Semak Profil / Baki

Dapatkan maklumat akaun reseller: nama pengguna, baki, dan tahap harga (peranan).

POST https://bybanana.my/api/v1/profile

Contoh Permintaan

{
  "api_id": "YOUR_API_ID",
  "timestamp": 1700000000,
  "nonce": "a1b2c3d4e5f6",
  "signature": "HMAC-SHA256(POST|/api/v1/profile|1700000000|a1b2c3d4e5f6, api_key)"
}

Respons

{
  "status": true,
  "msg": "Berjaya mendapatkan data profil",
  "data": {
    "username": "resellerku",
    "balance": "150000",
    "role": "Gold"
  }
}

Senarai Perkhidmatan (Senarai Harga)

Dapatkan semua produk beserta harga mengikut tahap anda (Basic / Gold / Platinum). Gunakan id sebagai service_id semasa membuat pesanan.

POST https://bybanana.my/api/v1/service

Contoh Permintaan

Parameter	Jenis	Penerangan
`api_id` *	string	Pengesahan & Signature
`timestamp` *	integer	Unix timestamp (detik), ±300 detik dari waktu server.
`nonce` *	string	String acak unik (min 8 karakter), tidak boleh dipakai ulang.
`signature` *	string	HMAC-SHA256(METHOD\|PATH\|timestamp\|nonce, api_key)
`region`	string	Opsional. Filter hasil ke 1 region saja. Bisa diisi nama (`"Indonesia"`) atau kode (`"ID"`), tidak case-sensitive. Kalau dikosongkan, semua region dikembalikan sekaligus. Alias: `negara`.

{
  "api_id": "YOUR_API_ID",
  "timestamp": 1700000000,
  "nonce": "a1b2c3d4e5f6",
  "signature": "HMAC-SHA256(POST|/api/v1/service|1700000000|a1b2c3d4e5f6, api_key)",
  "region": "Indonesia"
}

Respons

[
  {
    "status": true,
    "msg": "Berjaya mendapatkan data perkhidmatan",
    "data": {
      "id": "101",
      "game": "Mobile Legends",
      "game_display": "Mobile Legends (Indonesia)",
      "region_code": "ID",
      "region_name": "Indonesia",
      "nama_layanan": "86 Diamonds",
      "negara": "ID",
      "harga": {
        "regular": "21500",
        "basic": "21000",
        "gold": "20500",
        "platinum": "20000"
      },
      "status": "available"
    }
  }
]

Objek harga berisi 4 tingkatan harga sesuai role akun reseller Anda: regular (akun tanpa subscription aktif), basic, gold, dan platinum. Harga yang dibebankan saat order (endpoint /order) otomatis mengikuti role akun Anda saat ini — lihat field role pada respons /profile di atas.

Field negara berisi kode region produk (ID, MY, PH, SG, TH, …), diturunkan dari Master Type yang terkait dengan produk (produk.tipe → product_types → master_types.negara).

Field baru — disarankan dipakai untuk integrasi baru:
• game_display — nama game yang sudah termasuk region, siap tampil langsung sebagai judul/brand di listing Anda (mis. "Mobile Legends (Indonesia)"). Kalau region belum terdeteksi untuk suatu produk, nilainya sama dengan game (tanpa suffix).
• region_code — kode ISO region ("ID", "MY", dst), sama isinya dengan negara. Bisa null kalau region belum terdeteksi.
• region_name — nama region dalam bentuk terbaca manusia ("Indonesia"), sesuai penamaan Master Type yang admin atur sendiri di panel Bybanana.

Field game tetap dipertahankan apa adanya (nama game polos, tanpa suffix region) untuk kompatibilitas mundur — integrasi lama tidak akan rusak. Kalau ingin listing game Anda otomatis terpisah per region (mis. "Mobile Legends (Indonesia)" dan "Mobile Legends (Malaysia)" sebagai 2 entri berbeda), kelompokkan produk berdasarkan game_display, bukan game.

Buat Pesanan

Buat transaksi baru. Baki akan ditolak secara automatik mengikut tahap harga anda. order_id dibuat oleh sistem anda dan mesti unik.

POST https://bybanana.my/api/v1/order

Parameter

Parameter	Jenis	Penerangan
`order_id` *	string	ID transaksi unik dari sistem anda
`service_id` *	string	ID Perkhidmatan (dari endpoint /service)
`target_id` *	string	ID Pengguna / nombor destinasi
`target_server`	string	Zone / Pelayan (jika ada)

Contoh Permintaan

{
  "api_id": "YOUR_API_ID",
  "timestamp": 1700000000,
  "nonce": "a1b2c3d4e5f6",
  "signature": "HMAC-SHA256(POST|/api/v1/order|1700000000|a1b2c3d4e5f6, api_key)",
  "order_id": "TRX-1700000001",
  "service_id": "101",
  "target_id": "123456789",
  "target_server": "2001"
}

Respons Berjaya

{
  "status": true,
  "msg": "Pesanan berjaya! Pesanan sedang diproses",
  "data": {
    "order_id": "TRX-1700000001",
    "nama_layanan": "86 Diamonds",
    "service_id": "101",
    "target_id": "123456789",
    "target_server": "2001",
    "status": "Proses",
    "note": ""
  }
}

Respons Ralat

{
  "status": false,
  "msg": "order_id wajib diisi"
}

{
  "status": false,
  "msg": "order_id sudah tersedia pada sistem kami",
  "data": { "status": "error" }
}

{
  "status": false,
  "msg": "service_id tidak ditemukan"
}

{
  "status": false,
  "msg": "Saldo anda tidak mencukupi"
}

Semak Status Transaksi

Semak status semasa transaksi berdasarkan order_id.

POST https://bybanana.my/api/v1/status

Parameter

Parameter	Jenis	Penerangan
`order_id` *	string	ID transaksi yang ingin disemak

Contoh Permintaan

{
  "api_id": "YOUR_API_ID",
  "timestamp": 1700000000,
  "nonce": "a1b2c3d4e5f6",
  "signature": "HMAC-SHA256(POST|/api/v1/status|1700000000|a1b2c3d4e5f6, api_key)",
  "order_id": "TRX-1700000001"
}

Respons

{
  "status": true,
  "msg": "Butiran transaksi berjaya diperoleh",
  "data": {
    "order_id": "TRX-1700000001",
    "status": "Sukses",
    "note": "SN: 1234567890"
  }
}

Semak Nama Samaran

Sahkan ID Pengguna permainan untuk mendapatkan nama samaran pemilik akaun sebelum membuat pesanan.

POST https://bybanana.my/api/v1/nickname

Endpoint ini tidak memerlukan pengesahan (api_id / api_key / signature). Hanya hantar code, id, dan zone. Respons diteruskan seadanya daripada pembekal nickname.

Contoh Permintaan

{
  "code": "mlbb",
  "id": "123456789",
  "zone": "2001"
}

Callback / Webhook

Apabila status pesanan berubah (contohnya dari Processing ke Success / Failed), sistem kami secara automatik menghantar POST JSON ke Callback URL yang anda tetapkan dalam menu Integrasi API.

Payload Yang Kami Hantar

POST {Callback URL Anda}
Content-Type: application/json
X-Signature: md5(api_id + order_id + status + webhook_secret)

{
  "event": "order.status",
  "order_id": "TRX-1700000001",
  "service_id": "101",
  "product": "86 Diamonds",
  "status": "Sukses",
  "note": "SN: 1234567890",
  "sn": "SN: 1234567890",
  "target_id": "123456789",
  "target_server": "2001",
  "price": 20500,
  "timestamp": 1700000123,
  "signature": "md5(api_id + order_id + status + webhook_secret)"
}

Pengesahan Signature (PHP)

$payload = json_decode(file_get_contents('php://input'), true);
$expected = md5($api_id . $payload['order_id'] . $payload['status'] . $webhook_secret);
if ($_SERVER['HTTP_X_SIGNATURE'] === $expected) {
    // valid — update status order di sistem Anda
    http_response_code(200);
    echo 'OK';
}

Balas dengan HTTP 200 supaya callback dianggap berjaya. Jika gagal, status callback boleh dilihat di Integrasi API → Sejarah Panggilan Balik.

Senarai Status Transaksi

Status yang mungkin muncul dalam medan status:

Pending Diproses Berjaya Gagal Bayaran Balik