> ## Documentation Index
> Fetch the complete documentation index at: https://o1pay.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Saldo Merchant

> Cek saldo toko dan saldo utama merchant secara real-time.

`GET /api/v1/balance`

Mengambil informasi saldo terkini. Endpoint ini mendukung dua metode autentikasi: menggunakan kredensial toko (`agentCode` dan `merchantCode`) yang dilindungi IP Whitelist, atau menggunakan Bearer Token sesi login merchant.

## Autentikasi dengan kredensial toko

| Parameter | Lokasi | Tipe | Wajib | Deskripsi |
| - | - | - | - | - |
| agentCode | query | string | Ya | Kode agen unik toko aktif |
| merchantCode | query | string | Ya | Kode merchant unik toko aktif |

### Contoh request

```bash cURL theme={null}
curl -X GET "http://localhost:5173/api/v1/balance?agentCode=AGT-XXXXXXXX&merchantCode=MERCHANT_CODE"
```

```javascript JavaScript theme={null}
const params = new URLSearchParams({
  agentCode: "AGT-XXXXXXXX",
  merchantCode: "MERCHANT_CODE",
});
const res = await fetch(`http://localhost:5173/api/v1/balance?${params}`);
const { data } = await res.json();
console.log(data.balance, data.mainBalance);
```

```php PHP theme={null}
<?php
$query = http_build_query([
    "agentCode" => "AGT-XXXXXXXX",
    "merchantCode" => "MERCHANT_CODE",
]);
$response = file_get_contents("http://localhost:5173/api/v1/balance?" . $query);
$data = json_decode($response, true)["data"];
echo $data["balance"] . " " . $data["mainBalance"];
```

```javascript Node.js theme={null}
import axios from "axios";

const { data: res } = await axios.get("http://localhost:5173/api/v1/balance", {
  params: { agentCode: "AGT-XXXXXXXX", merchantCode: "MERCHANT_CODE" },
});
console.log(res.data.balance, res.data.mainBalance);
```

```python Python theme={null}
import requests

res = requests.get(
    "http://localhost:5173/api/v1/balance",
    params={"agentCode": "AGT-XXXXXXXX", "merchantCode": "MERCHANT_CODE"},
)
data = res.json()["data"]
print(data["balance"], data["mainBalance"])
```

```go Golang theme={null}
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
	"net/url"
)

func main() {
	q := url.Values{}
	q.Set("agentCode", "AGT-XXXXXXXX")
	q.Set("merchantCode", "MERCHANT_CODE")

	resp, err := http.Get("http://localhost:5173/api/v1/balance?" + q.Encode())
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]any
	json.NewDecoder(resp.Body).Decode(&result)
	data := result["data"].(map[string]any)
	fmt.Println(data["balance"], data["mainBalance"])
}
```

```rust Rust theme={null}
// Cargo.toml: reqwest = { version = "0.12", features = ["json"] }, serde_json = "1", tokio = { version = "1", features = ["full"] }
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let res: Value = reqwest::Client::new()
        .get("http://localhost:5173/api/v1/balance")
        .query(&[("agentCode", "AGT-XXXXXXXX"), ("merchantCode", "MERCHANT_CODE")])
        .send()
        .await?
        .json()
        .await?;

    println!("{} {}", res["data"]["balance"], res["data"]["mainBalance"]);
    Ok(())
}
```

### Contoh response

```json theme={null}
{
  "success": true,
  "data": {
    "storeId": "store_xxxxxxxxxxxxxxxx",
    "storeName": "NAMA MERCHANT",
    "agentCode": "AGT-XXXXXXXX",
    "merchantCode": "MERCHANT_CODE",
    "balance": 850000,
    "totalEarned": 12500000,
    "mainBalance": 3500000,
    "currency": "IDR",
    "updatedAt": "2026-11-03T12:00:00.000Z"
  }
}
```

## Autentikasi dengan Bearer Token

| Parameter | Lokasi | Tipe | Wajib | Deskripsi |
| - | - | - | - | - |
| Authorization | header | string | Ya | Bearer \<token> dari sesi login merchant |

> [!WARNING]
>
> Jangan ekspos token ini di sisi client/frontend. Panggil hanya dari backend server Anda.

### Contoh request

```bash cURL theme={null}
curl -X GET "http://localhost:5173/api/v1/balance" \
  -H "Authorization: Bearer <token_anda>"
```

```javascript JavaScript theme={null}
const res = await fetch("http://localhost:5173/api/v1/balance", {
  headers: { Authorization: "Bearer <token_anda>" },
});
const { data } = await res.json();
console.log(data.mainBalance, data.combinedBalance);
```

```php PHP theme={null}
<?php
$ch = curl_init("http://localhost:5173/api/v1/balance");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => ["Authorization: Bearer <token_anda>"],
    CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true)["data"];
echo $data["mainBalance"] . " " . $data["combinedBalance"];
```

```javascript Node.js theme={null}
import axios from "axios";

const { data: res } = await axios.get("http://localhost:5173/api/v1/balance", {
  headers: { Authorization: "Bearer <token_anda>" },
});
console.log(res.data.mainBalance, res.data.combinedBalance);
```

```python Python theme={null}
import requests

res = requests.get(
    "http://localhost:5173/api/v1/balance",
    headers={"Authorization": "Bearer <token_anda>"},
)
data = res.json()["data"]
print(data["mainBalance"], data["combinedBalance"])
```

```go Golang theme={null}
package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "http://localhost:5173/api/v1/balance", nil)
	req.Header.Set("Authorization", "Bearer <token_anda>")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()

	var result map[string]any
	json.NewDecoder(resp.Body).Decode(&result)
	data := result["data"].(map[string]any)
	fmt.Println(data["mainBalance"], data["combinedBalance"])
}
```

```rust Rust theme={null}
// Cargo.toml: reqwest = { version = "0.12", features = ["json"] }, serde_json = "1", tokio = { version = "1", features = ["full"] }
use serde_json::Value;

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let res: Value = reqwest::Client::new()
        .get("http://localhost:5173/api/v1/balance")
        .bearer_auth("<token_anda>")
        .send()
        .await?
        .json()
        .await?;

    println!("{} {}", res["data"]["mainBalance"], res["data"]["combinedBalance"]);
    Ok(())
}
```

### Contoh response

Saldo ditampilkan dalam satuan Rupiah (IDR) tanpa desimal.

```json theme={null}
{
  "success": true,
  "data": {
    "mainBalance": 3500000,
    "totalReceived": 15000000,
    "totalStoreBalance": 850000,
    "combinedBalance": 4350000,
    "stores": [
      {
        "storeId": "store_xxxxxxxxxxxxxxxx",
        "storeName": "Toko Utama",
        "status": "active",
        "balance": 850000,
        "totalEarned": 12500000,
        "currency": "IDR"
      }
    ],
    "currency": "IDR",
    "updatedAt": "2026-11-03T12:00:00.000Z"
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.