Saldo

Saldo dan mutasi.

Saldo

GET https://api.ongkirhub.com/v1/wallet

Saldo tersedia dan saldo yang ditahan. Kunci test membaca saldo uji.

Akses (scope): wallet:read.

Butuh kunci API (bearerAuth)

Contoh permintaan

curl -X GET "https://api.ongkirhub.com/v1/wallet" \
  -H "Authorization: Bearer ohk_test_xxx"

Respons

200 Saldo.

X-Request-Id: ID permintaan untuk dukungan.
RateLimit-Limit: Batas permintaan per jendela waktu.
RateLimit-Remaining: Sisa permintaan di jendela waktu ini.
RateLimit-Reset: Detik sampai jendela waktu berikutnya.

Field respons 200
Field	Keterangan
`livemode` boolean, wajib	False untuk saldo uji (kunci test).
`currency` string, wajib	- Nilai: `IDR`
`available` integer, wajib	Saldo yang bisa dipakai. Rupiah, bilangan bulat.
`held` integer, wajib	Saldo yang ditahan untuk pengiriman yang sedang diproses. Rupiah, bilangan bulat.
`updatedAt` string (date-time) \| null, wajib	Terakhir berubah.

{
  "livemode": true,
  "currency": "IDR",
  "available": 488000,
  "held": 12000,
  "updatedAt": "2026-10-11T03:01:00.000Z"
}

401 Kunci API tidak dikirim, tidak valid, atau sudah dicabut.

X-Request-Id: ID permintaan untuk dukungan.

{
  "error": {
    "code": "unauthenticated",
    "message": "Kunci API tidak valid, sudah dicabut, atau tidak dikirim. Kirim header Authorization: Bearer <kunci API>.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
  }
}

403 Kunci API tidak punya akses (scope) untuk endpoint ini.

X-Request-Id: ID permintaan untuk dukungan.
RateLimit-Limit: Batas permintaan per jendela waktu.
RateLimit-Remaining: Sisa permintaan di jendela waktu ini.
RateLimit-Reset: Detik sampai jendela waktu berikutnya.

{
  "error": {
    "code": "forbidden",
    "message": "Kunci API ini tidak punya akses ke endpoint ini. Tambahkan akses yang dibutuhkan di menu Developer.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12",
    "details": {
      "requiredScope": "shipments:write"
    }
  }
}

429 Batas permintaan terlampaui.
X-Request-Id

ID permintaan untuk dukungan.

RateLimit-Limit

Batas permintaan per jendela waktu.

RateLimit-Remaining

Sisa permintaan di jendela waktu ini.

RateLimit-Reset

Detik sampai jendela waktu berikutnya.

Retry-After

Detik sampai boleh mencoba lagi.
```
{
  "error": {
    "code": "rate_limited",
    "message": "Terlalu banyak permintaan. Tunggu sebentar, lalu coba lagi.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12",
    "details": {
      "retryAfterSec": 21
    }
  }
}
```
500 Kesalahan di sistem OngkirHub. Aman dicoba ulang dengan Idempotency-Key yang sama.
X-Request-Id

ID permintaan untuk dukungan.

RateLimit-Limit

Batas permintaan per jendela waktu.

RateLimit-Remaining

Sisa permintaan di jendela waktu ini.

RateLimit-Reset

Detik sampai jendela waktu berikutnya.
```
{
  "error": {
    "code": "internal_error",
    "message": "Terjadi kesalahan di sistem kami. Coba lagi sebentar lagi.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
  }
}
```

Mutasi saldo

GET https://api.ongkirhub.com/v1/wallet/transactions

Riwayat perubahan saldo, terbaru dulu. Kunci test membaca mutasi saldo uji.

Akses (scope): wallet:read.

Butuh kunci API (bearerAuth)

Parameter query

Parameter query
Field	Keterangan
`type` string	Jenis mutasi. Nilai: `topupholdreleasecapturerefundadjustmentbonus`
`createdFrom` string (date-time)	Dibuat sejak (inklusif), ISO 8601.
`createdTo` string (date-time)	Dibuat sebelum (eksklusif), ISO 8601.
`limit` integer	Jumlah data per halaman.
`cursor` string	nextCursor dari halaman sebelumnya.

Contoh permintaan

curl -X GET "https://api.ongkirhub.com/v1/wallet/transactions" \
  -H "Authorization: Bearer ohk_test_xxx"

Respons

200 Satu halaman mutasi.

X-Request-Id: ID permintaan untuk dukungan.
RateLimit-Limit: Batas permintaan per jendela waktu.
RateLimit-Remaining: Sisa permintaan di jendela waktu ini.
RateLimit-Reset: Detik sampai jendela waktu berikutnya.

Field respons 200
Field	Keterangan
`data` array<WalletTransaction>, wajib	-
`hasMore` boolean, wajib	Masih ada data setelah halaman ini.
`nextCursor` string \| null, wajib	Kirim sebagai parameter `cursor` untuk halaman berikutnya. Null di halaman terakhir.

{
  "data": [
    {
      "id": "6709f1c9a1b2c3d4e5f6071a",
      "type": "hold",
      "amount": -12000,
      "availableAfter": 488000,
      "heldAfter": 12000,
      "ref": {
        "type": "shipment",
        "id": "OH0HZ3K7Q2M4XB"
      },
      "note": null,
      "createdAt": "2026-10-11T03:01:00.000Z"
    },
    {
      "id": "6709e0a2a1b2c3d4e5f60701",
      "type": "topup",
      "amount": 500000,
      "availableAfter": 500000,
      "heldAfter": 0,
      "ref": {
        "type": "topup",
        "id": "TU0HZ2Y1X0W9VA"
      },
      "note": null,
      "createdAt": "2026-10-10T02:00:00.000Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "WzE3OTE1OTc2MDAwMDAsIjY3MDllMGEyYTFiMmMzZDRlNWY2MDcwMSJd"
}

400 Permintaan tidak bisa dibaca: JSON rusak, cursor atau Idempotency-Key tidak valid.
X-Request-Id

ID permintaan untuk dukungan.

RateLimit-Limit

Batas permintaan per jendela waktu.

RateLimit-Remaining

Sisa permintaan di jendela waktu ini.

RateLimit-Reset

Detik sampai jendela waktu berikutnya.
```
{
  "error": {
    "code": "invalid_request",
    "message": "Body bukan JSON yang valid.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
  }
}
```

401 Kunci API tidak dikirim, tidak valid, atau sudah dicabut.

X-Request-Id: ID permintaan untuk dukungan.

{
  "error": {
    "code": "unauthenticated",
    "message": "Kunci API tidak valid, sudah dicabut, atau tidak dikirim. Kirim header Authorization: Bearer <kunci API>.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
  }
}

403 Kunci API tidak punya akses (scope) untuk endpoint ini.

X-Request-Id: ID permintaan untuk dukungan.
RateLimit-Limit: Batas permintaan per jendela waktu.
RateLimit-Remaining: Sisa permintaan di jendela waktu ini.
RateLimit-Reset: Detik sampai jendela waktu berikutnya.

{
  "error": {
    "code": "forbidden",
    "message": "Kunci API ini tidak punya akses ke endpoint ini. Tambahkan akses yang dibutuhkan di menu Developer.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12",
    "details": {
      "requiredScope": "shipments:write"
    }
  }
}

422 Isi permintaan belum valid.

X-Request-Id: ID permintaan untuk dukungan.
RateLimit-Limit: Batas permintaan per jendela waktu.
RateLimit-Remaining: Sisa permintaan di jendela waktu ini.
RateLimit-Reset: Detik sampai jendela waktu berikutnya.

{
  "error": {
    "code": "validation_error",
    "message": "Ada data yang belum lengkap atau belum sesuai. Periksa lagi isianmu.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12",
    "details": {
      "fields": [
        {
          "path": "receiver.location.zipcode",
          "message": "Kode pos harus 5 digit"
        }
      ]
    }
  }
}

429 Batas permintaan terlampaui.
X-Request-Id

ID permintaan untuk dukungan.

RateLimit-Limit

Batas permintaan per jendela waktu.

RateLimit-Remaining

Sisa permintaan di jendela waktu ini.

RateLimit-Reset

Detik sampai jendela waktu berikutnya.

Retry-After

Detik sampai boleh mencoba lagi.
```
{
  "error": {
    "code": "rate_limited",
    "message": "Terlalu banyak permintaan. Tunggu sebentar, lalu coba lagi.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12",
    "details": {
      "retryAfterSec": 21
    }
  }
}
```
500 Kesalahan di sistem OngkirHub. Aman dicoba ulang dengan Idempotency-Key yang sama.
X-Request-Id

ID permintaan untuk dukungan.

RateLimit-Limit

Batas permintaan per jendela waktu.

RateLimit-Remaining

Sisa permintaan di jendela waktu ini.

RateLimit-Reset

Detik sampai jendela waktu berikutnya.
```
{
  "error": {
    "code": "internal_error",
    "message": "Terjadi kesalahan di sistem kami. Coba lagi sebentar lagi.",
    "request_id": "req_5f0c2a9e7b1d4c3a8e6f0b12"
  }
}
```

Skema objek

Objek yang dipakai di halaman ini, dijelaskan sekali di sini.

WalletTransaction

Field objek WalletTransaction
Field	Keterangan
`id` string, wajib	ID mutasi.
`type` string, wajib	topup: isi saldo. hold: saldo ditahan saat pengiriman dibuat. capture: tahanan dipakai setelah kurir menerima pesanan. release: tahanan dikembalikan karena pesanan gagal. refund: pengembalian setelah pembatalan disetujui. adjustment dan bonus: penyesuaian oleh tim OngkirHub. Nilai: `topupholdreleasecapturerefundadjustmentbonus`
`amount` integer, wajib	Perubahan saldo tersedia dalam rupiah (negatif berarti berkurang). Untuk capture: perubahan saldo ditahan.
`availableAfter` integer, wajib	Saldo tersedia setelah mutasi. Rupiah, bilangan bulat.
`heldAfter` integer, wajib	Saldo ditahan setelah mutasi. Rupiah, bilangan bulat.
`ref` object \| null, wajib	-
`ref.type` string, wajib	- Nilai: `shipmenttopupcancellationclaimmanual`
`ref.id` string, wajib	ID terkait, contoh OH… atau TU…
`note` string \| null, wajib	Catatan.
`createdAt` string (date-time), wajib	Waktu mutasi.