Top Up Balance

Buat request top up saldo. Akan menghasilkan link pembayaran yang dapat dibayar oleh customer.

POST /v1/balance

Request Body

Parameter	Type	Description
`ref_id` Required	string	ID unik transaksi dari sistem Anda (idempoten). Jika sudah pernah dipakai → `REF_ID_ALREADY_EXIST`.
`code` Required	string	Kode payment channel = field `service` dari `/v1/balance/channels` (mis. `QRIS_CUSTOM`). Pakai hanya channel yang `status`-nya `on`; yang `off` dijawab `CODE_NOT_FOUND_OR_INACTIVE`.
`amount` Required	integer	Nominal top up (Rupiah), di luar biaya. Batasnya per channel — baca `minimum`/`maximum` dari `/v1/balance/channels`, jangan pakai angka tetap.

Yang perlu diperhatikan

Yang harus dibayar adalah amount, bukan price. price = nominal yang akan masuk ke saldo, fees = biaya, amount = total tagihan. Nominal final baru ditetapkan saat tagihan terbit, jadi amount di respons bisa berbeda sedikit dari hasil hitungan Anda memakai fee_flat/fee_percentage. Angka di respons yang berlaku.

expired_at berbeda-beda per metode. Masa berlaku ditentukan metode pembayarannya — QRIS umumnya jauh lebih pendek daripada Virtual Account, kadang hanya beberapa menit. Pakai expired_at dari respons sebagai satu-satunya acuan hitung mundur, jangan menganggapnya tetap.

payment_link/qr_link bisa null. Bila penyiapan pembayaran belum selesai, transaksinya tetap dibuat dengan status pending tetapi belum punya tautan/QR. Jangan mengirim ulang dengan ref_id baru — itu membuat dua tagihan. Ulangi permintaan dengan ref_id yang SAMA, atau cek statusnya.

Error

HTTP	message	Artinya
400	`REF_ID_ALREADY_EXIST`	Idempotensi. `ref_id` ini sudah punya transaksi — ambil transaksi lamanya, jangan buat yang baru.
400	`CODE_NOT_FOUND_OR_INACTIVE`	Kode channel tidak dikenal atau sedang tidak bisa dipakai untuk isi saldo. Muat ulang `/v1/balance/channels` dan pilih yang `status`-nya `on`.
400	`AMOUNT_MINIMUM_IS_…` / `AMOUNT_MAXIMUM_IS_…`	Nominal di luar rentang channel. Angkanya menempel di kodenya.
422	`TOPUP_DAILY_LIMIT` / `TRX_DAILY_LIMIT`	Batas harian akun Anda tercapai — bukan gangguan server. Jawabannya akan sama sampai kuota pulih, jadi jangan diulang otomatis. Rinciannya ada di field `error`.
500	`INTERNAL_SERVER_ERROR`	Gangguan di sisi kami. Aman diulang dengan `ref_id` yang SAMA.

Example Request

curl --request POST \
                  --url https://sekalipay.com/api/v1/balance \
                  --header 'X-APIKEY: YOUR_API_KEY' \
                  --header 'Content-Type: application/json' \
                  --data '{
                    "ref_id": "TP-1717000000",
                    "code": "QRIS_CUSTOM",
                    "amount": 100000
                  }'

Response Sample

200 OK

{
                  "message": "OK",
                  "data": {
                    "invoice": "INV...",
                    "ref_id": "TP-1717000000",
                    "amount": 101000,
                    "price": 100000,
                    "fees": 1000,
                    "payment_code": "QRIS_CUSTOM",
                    "status": "pending",
                    "payment_link": "https://...",
                    "payment_url": "https://...",
                    "qr_link": "https://...",
                    "expired_at": "...",
                    "expires_at": "..."
                  }
                }