Cek Saldo Merchant

Mengambil komponen saldo yang sama dengan dashboard Merchant. Endpoint ini bersifat read-only dan tidak melakukan reservasi, debit, kredit, maupun settlement saldo.

Endpoint

GET /api/v1/payin/balance

Autentikasi

Kirim token API Merchant melalui header token. Request juga mengikuti konfigurasi IP allowlist Pay-in milik Merchant apabila pembatasan IP diaktifkan.

Header	Wajib	Keterangan
token	Ya	Token API Merchant yang diberikan oleh KingsPay

Endpoint tidak menerima ID Merchant dari URL, query, ataupun body. Saldo selalu diambil dari pemilik token yang terautentikasi sehingga token tidak dapat digunakan untuk membaca saldo Merchant lain.

Contoh Request

curl --request GET \
  --url 'https://merchant-api.kingspay.id/api/v1/payin/balance' \
  --header 'token: <merchant-token>'

Request ini tidak memerlukan body.

Response Sukses

{
  "logId": "pQ8UqJjM2Nh4yA6xZs1K",
  "status": true,
  "message": "Balance inquiry successful",
  "data": {
    "balance": {
      "available": 100000,
      "pending": 49500
    }
  }
}

Field Response

Field	Tipe	Keterangan
logId	string	ID unik untuk pelacakan request
status	boolean	Status keberhasilan request
message	string	Pesan hasil request
data.balance.available	number	Saldo settled yang sudah dapat digunakan untuk payout
data.balance.pending	number	Dana bersih dari pay-in sukses yang belum masuk settlement

Nilai saldo dinormalisasi hingga maksimal dua angka desimal, sama seperti nilai yang ditampilkan pada dashboard Merchant.

Perhitungan Saldo

Available

available adalah saldo settled terkini yang tersimpan pada akun Merchant:

available = merchant.saldo

Nilai ini dapat berubah ketika settlement dikreditkan, payout didebit, atau payout gagal dikembalikan.

Pending

pending adalah total bersih seluruh pay-in yang sudah sukses tetapi belum memiliki settlement:

pending = SUM(amount - biayaPlatform)

Hanya transaksi dengan kondisi berikut yang dihitung:

status = success
idSettlement = NULL

biayaPlatform adalah fee Pay-in yang ditagihkan kepada Merchant. Karena itu, pending menunjukkan dana bersih yang akan diterima, bukan nilai kotor transaksi.

Contoh Perhitungan

Pay-in sukses:       Rp50.000
Fee Merchant:           Rp500
Belum settlement:           Ya

Tambahan pending = Rp50.000 - Rp500 = Rp49.500

Response Gagal

Token Tidak Dikirim

HTTP 401 Unauthorized

{
  "logId": "request-log-id",
  "status": false,
  "message": "Token not found"
}

Token Tidak Valid atau Merchant Tidak Aktif

HTTP 401 Unauthorized

{
  "logId": "request-log-id",
  "status": false,
  "message": "Token not valid"
}

Merchant berstatus tidak aktif akan menerima pesan Merchant not active.

IP Tidak Diizinkan

Jika IP allowlist Pay-in diaktifkan dan request berasal dari IP yang tidak terdaftar, API mengembalikan HTTP 403 Forbidden:

{
  "logId": "request-log-id",
  "status": false,
  "code": "IP_NOT_ALLOWED",
  "message": "Access is not allowed from this IP address"
}

Nilai Real-time

Endpoint membaca saldo langsung dari database, bukan dari cache autentikasi token. Namun request yang sedang berproses, settlement yang belum selesai, atau callback payout yang belum final dapat membuat nilai berubah pada request berikutnya.