Cek Tagihan

Mengecek tagihan pascabayar (PLN, PDAM, BPJS, dan lainnya) sebelum dibayar.

POSThttps://api.zevaldigital.com/v1/bill/inquiry

Mengecek tagihan pascabayar (listrik PLN, PDAM, BPJS, PBB, cicilan, dan sejenisnya). Ini tahap pertama dari dua tahap: hasil cek berisi nama pelanggan, nilai tagihan, dan total yang harus dibayar. Setelah pelanggan setuju, bayar lewat Bayar Tagihan dengan ref_id yang sama. Cek tagihan tidak memotong saldo.

1
Cek tagihanKirim product_code (produk bertipe bill di Daftar Produk), destination (nomor pelanggan), dan ref_id baru.
2
Tampilkan ke pelangganTunjukkan customer_name, bill_amount, admin, dan total. Jangan menghitung sendiri: total sudah termasuk biaya admin.
3
BayarPanggil Bayar Tagihan dengan ref_id yang sama (dan amount = total) sebelum expires_at.

Yang perlu dikirim

Parameter	Tipe	Wajib	Keterangan
`secret_id`	string	Ya	Secret ID Anda.
`signature`	string	Ya	Hasil `md5(secret_id:secret_key:ref_id)` (menyertakan ref_id). Lihat halaman Autentikasi.
`product_code`	string	Ya	Kode produk tagihan dari Daftar Produk (yang `type`-nya `bill`), mis. `PLNPASCA`.
`destination`	string	Ya	Nomor pelanggan (ID pelanggan PLN, nomor PDAM, nomor BPJS, dst.). Contoh `120140007726`.
`ref_id`	string	Ya	Nomor dari sistem Anda, unik untuk setiap tagihan. Huruf, angka, titik, strip, garis bawah, maksimal 64 karakter. Dipakai lagi saat membayar.

Cek yang butuh waktuSebagian provider menjawab cek tagihan tidak seketika. Kami menunggu hingga sekitar 10 detik. Bila masih belum ada jawaban, status berisi pending: panggil ulang endpoint ini dengan ref_id yang sama persis setiap 2–3 detik sampai statusnya berubah. Panggilan ulang tidak membuat pengecekan baru dan tidak ada biaya.

Masa berlaku hasil cekHasil cek berlaku sekitar 15 menit dan tidak pernah melewati tengah malam (provider hanya menerima pembayaran di tanggal yang sama dengan pengecekan). Lihat expires_at. Lewat dari itu, cek ulang dengan ref_id baru.

Contoh kode

Memakai fungsi zeval() dari halaman Autentikasi. Argumen ketiga adalah ref_id, dipakai untuk menghitung signature.

PHP

<?php
$refId = 'BILL-1001';

$check = zeval('/v1/bill/inquiry', [
    'product_code' => 'PLNPASCA',
    'destination'  => '120140007726',
    'ref_id'       => $refId,
], $refId);

// Masih diproses? Ulangi dengan ref_id yang sama.
while ($check['status'] === 'success' && $check['data']['status'] === 'pending') {
    sleep(3);
    $check = zeval('/v1/bill/inquiry', [
        'product_code' => 'PLNPASCA',
        'destination'  => '120140007726',
        'ref_id'       => $refId,
    ], $refId);
}

if ($check['status'] === 'success' && $check['data']['status'] === 'success') {
    echo $check['data']['customer_name'] . ' - total Rp ' . $check['data']['total'];
} else {
    echo 'Gagal: ' . ($check['message'] ?? $check['data']['message']);
}

Node.js

const refId = 'BILL-1001';
const body = { product_code: 'PLNPASCA', destination: '120140007726', ref_id: refId };

let check = await zeval('/v1/bill/inquiry', body, refId);

// Masih diproses? Ulangi dengan ref_id yang sama.
while (check.status === 'success' && check.data.status === 'pending') {
  await new Promise((r) => setTimeout(r, 3000));
  check = await zeval('/v1/bill/inquiry', body, refId);
}

if (check.status === 'success' && check.data.status === 'success') {
  console.log(check.data.customer_name, '- total Rp', check.data.total);
} else {
  console.log('Gagal:', check.message ?? check.data.message);
}

Python

import time

ref_id = "BILL-1001"
body = {"product_code": "PLNPASCA", "destination": "120140007726", "ref_id": ref_id}

check = zeval("/v1/bill/inquiry", body, ref_id)

# Masih diproses? Ulangi dengan ref_id yang sama.
while check["status"] == "success" and check["data"]["status"] == "pending":
    time.sleep(3)
    check = zeval("/v1/bill/inquiry", body, ref_id)

if check["status"] == "success" and check["data"]["status"] == "success":
    print(check["data"]["customer_name"], "- total Rp", check["data"]["total"])
else:
    print("Gagal:", check.get("message") or check["data"]["message"])

Contoh respons

Tagihan ditemukan

HTTP 200

{
  "code": 200,
  "status": "success",
  "message": "Cek tagihan diproses.",
  "data": {
    "trx_id": "TRX261007K7Q2M9",
    "ref_id": "BILL-1001",
    "product_code": "PLNPASCA",
    "product_name": "PLN Pascabayar",
    "destination": "120140007726",
    "status": "success",
    "customer_name": "FITRI WARDHANI",
    "period": "202610",
    "bill_amount": 239439,
    "admin": 5000,
    "total": 244439,
    "detail": {
      "tarif": "R1M",
      "daya": 900,
      "sheets": 1,
      "meter": null,
      "periods": [
        { "period": "202610", "bill": 239439, "admin": 4000, "penalty": 0 }
      ]
    },
    "expires_at": "2026-10-07 18:30:00",
    "message": "Tagihan ditemukan. Bayar sebelum expires_at."
  }
}

Belum ada jawaban dari provider (panggil ulang)

HTTP 200

{
  "code": 200,
  "status": "success",
  "message": "Cek tagihan diproses.",
  "data": {
    "trx_id": "TRX261007K7Q2M9",
    "ref_id": "BILL-1001",
    "status": "pending",
    "customer_name": null,
    "total": null,
    "message": "Tagihan sedang dicek. Panggil ulang dengan ref_id yang sama."
  }
}

Tagihan tidak bisa dicek (mis. sudah dibayar atau nomor salah)

HTTP 200

{
  "code": 200,
  "status": "success",
  "message": "Cek tagihan diproses.",
  "data": {
    "trx_id": "TRX261007K7Q2M9",
    "ref_id": "BILL-1001",
    "status": "failed",
    "total": null,
    "message": "Tagihan sudah dibayar"
  }
}

Perhatikan: pada jawaban ini status di tingkat atas hanya berarti request Anda diterima. Hasil cek ada di data.status.

Isi data

Parameter	Tipe	Keterangan
`trx_id`	string	Nomor referensi dari kami. Nomor ini juga menjadi `trx_id` transaksi pembayarannya.
`ref_id`	string	Nomor dari sistem Anda (yang Anda kirim).
`product_code`	string	Kode produk.
`product_name`	string	Nama produk.
`destination`	string	Nomor pelanggan.
`status`	string	`success` = tagihan ditemukan, `pending` = belum ada jawaban (panggil ulang), `failed` = tidak bisa dicek (lihat `message`), `expired` = hasil cek sudah kedaluwarsa, `paid` = sudah dibayar.
`customer_name`	string \| null	Nama pelanggan. Sebagian provider menyamarkan sebagian huruf.
`period`	string \| null	Periode tagihan, mis. 202610 (Oktober 2026).
`bill_amount`	integer \| null	Nilai tagihan (rupiah).
`admin`	integer \| null	Biaya admin (rupiah), sudah gabungan seluruh biaya layanan.
`total`	integer \| null	Total yang akan dipotong dari saldo Anda saat membayar (rupiah). Kirim nilai ini sebagai `amount` saat membayar.
`detail`	object \| null	Rincian: `tarif`, `daya`, `sheets` (jumlah lembar), `meter`, dan `periods` (per periode: `period`, `bill`, `admin`, `penalty`). Isi yang tidak tersedia dari provider bernilai `null`.
`expires_at`	string \| null	Batas waktu bayar (WIB). Hanya terisi saat `status` = `success`.
`message`	string	Keterangan singkat.

← SebelumnyaBuat Transaksi Berikutnya →Bayar Tagihan