Developer · API

Dompet & ledger

Saldo tercatat, saldo tersedia, alokasi pesanan, dan riwayat append-only dalam rupiah utuh.

Sebelum mengirim request

Dompet pengguna hanya memiliki endpoint baca. Perubahan saldo dilakukan oleh transaksi domain, settlement order, dan pembayaran terverifikasi. Jangan membangun PATCH saldo atau menghitung saldo otoritatif dari ledger di browser.

Kontrak nyata, nilai contoh

Endpoint, field, dan status HTTP mengikuti implementasi. Nilai ID, nomor, OTP, waktu, saldo, serta quote di contoh adalah ilustrasi, bukan data akun atau pilihan yang bisa langsung dibeli. Ganti dengan data dari instalasimu. Halaman ini tidak mengirim request atau menjalankan transaksi.

JavaScript dijalankan pada origin aplikasi setelah login. Contoh cURL memakai PING_ORIGIN dan cookie jar PING_COOKIE_JAR dari panduan autentikasi. Sukses memakai { ok: true, data }; create juga HTTP 200, bukan 201. Semua endpoint di halaman ini memerlukan sesi aktif dan dapat mengembalikan 401, 403, atau 500.

Baca saldo

GET/api/walletSession cookie

Saldo tercatat, alokasi pesanan, dan saldo tersedia dalam integer IDR. Gunakan nilai server untuk memutuskan apakah pengguna dapat membeli nomor.

GET /api/wallet · JavaScript

const response = await fetch("/api/wallet", {
  credentials: "same-origin",
  cache: "no-store",
});
const body = await response.json();

if (!response.ok || !body.ok) {
  throw Object.assign(
    new Error(body.error?.message ?? "Request gagal"),
    { code: body.error?.code, status: response.status },
  );
}

const data = body.data;

Riwayat ledger

GET/api/wallet/ledgerSession cookie

Entri ledger milik pengguna, terbaru lebih dahulu, dengan pagination offset. Respons berisi baris ledger asli, bukan Transaction dari mapper tampilan. Semua query dibatasi userId sesi di SQL.

Riwayat ledger
Parameter	Tipe	Wajib	Keterangan
limit (query)	integer	Tidak	Ukuran halaman 1–100; default 50.
offset (query)	integer	Tidak	Offset mulai 0. Lanjutkan offset + limit saat hasMore true.
type (query)	DEPOSIT \| HOLD \| CAPTURE \| RELEASE \| REFUND \| ADJUSTMENT	Tidak	Filter satu jenis ledger. Hilangkan parameter untuk semua jenis.
direction (query)	all \| credit \| debit	Tidak	Filter nominal tampilan sebelum pagination dan total. HOLD/CAPTURE termasuk debit; ADJUSTMENT mengikuti tanda nominal. Reset offset ketika filter berubah.

GET /api/wallet/ledger · JavaScript

const response = await fetch("/api/wallet/ledger?limit=50&offset=0&type=HOLD&direction=credit", {
  credentials: "same-origin",
  cache: "no-store",
});
const body = await response.json();

if (!response.ok || !body.ok) {
  throw Object.assign(
    new Error(body.error?.message ?? "Request gagal"),
    { code: body.error?.code, status: response.status },
  );
}

const data = body.data;

Riwayat ledger
Kode error	HTTP	Tindakan
VALIDATION_ERROR	400	Periksa tipe, field wajib, format UUID, dan field tambahan.

Schema · Wallet

Schema · Wallet
Field	Tipe	Wajib	Keterangan
balance	integer	Ya	Saldo tercatat, termasuk alokasi untuk pesanan aktif.
held	integer	Ya	Alokasi saldo untuk order, belum menjadi pembebanan akhir.
available	integer	Ya	Saldo yang dapat dipakai. Gunakan nilai server, bukan perhitungan client.

Schema · LedgerEntry

Schema · LedgerEntry
Field	Tipe	Wajib	Keterangan
id	string	Ya	Sesuai tipe yang ditampilkan.
type	DEPOSIT \| HOLD \| CAPTURE \| RELEASE \| REFUND \| ADJUSTMENT	Ya	Sesuai tipe yang ditampilkan.
amount	integer	Ya	Nominal ledger asli. HOLD/CAPTURE bukan angka negatif tampilan; ADJUSTMENT dapat bertanda.
referenceType	string \| null	Ya	Sesuai tipe yang ditampilkan.
referenceId	string \| null	Ya	ID referensi milik pengguna, misalnya order, pembayaran, atau voucher. Selalu null untuk bonus referral agar ID akun lain tidak terbuka.
note	string \| null	Ya	Catatan untuk pelanggan. Alasan internal penyesuaian admin diganti label umum.
createdAt	string · date-time	Ya	ISO 8601 dengan zona waktu.

Schema · LedgerPage

Schema · LedgerPage
Field	Tipe	Wajib	Keterangan
entries	LedgerEntry[]	Ya	Sesuai tipe yang ditampilkan.
wallet	Wallet	Ya	Lihat schema Wallet pada OpenAPI.
pagination	object	Ya	Sesuai tipe yang ditampilkan.