Cara Kerja Poin, Kuota, dan Pembayaran

API.MY.ID punya tiga model harga yang berjalan berdampingan. Memahami perbedaannya akan menghemat biaya Anda, dan yang lebih penting, mencegah error yang tidak perlu di produksi.

Tiga model

• •Gratis — hari libur dan jadwal sholat. Tanpa key, tanpa kuota, selamanya.
• •Kuota bulanan — endpoint data (wilayah, sekolah, kurs, IP). 5.000 hits gratis/bulan per key; berlangganan untuk kuota lebih besar.
• •Poin (pay-per-use) — endpoint AI (OCR, CV, artikel, hapus background). Bayar hanya untuk hit yang berhasil.

Poin: 1 IDR = 1 poin

Kursnya sengaja dibuat sesederhana mungkin agar Anda bisa menghitung biaya di kepala. Top up Rp 100.000 memberi 100.000 poin. Sebuah scan KTP memotong 150 poin, artinya Rp 150 per scan — dan Rp 100.000 cukup untuk sekitar 666 scan.

POST /ocr/ktp            →   150 poin
POST /ocr/sim            →   300 poin
POST /cv/extract         →   300 poin
POST /image/remove-bg    →   300 poin
POST /articles/generate  → 1.300 poin

Dua janji penting

Sistem poin dirancang agar Anda tidak pernah membayar untuk sesuatu yang tidak Anda dapatkan:

• •Poin hanya terpotong saat berhasil. Request yang ditolak karena parameter salah tidak memotong apa pun.
• •Kegagalan upstream mengembalikan poin. Jika layanan AI di belakang gagal setelah poin terpotong, poin dikembalikan otomatis dalam transaksi yang sama.

Menangani 402 dengan benar

Saat saldo tidak cukup, endpoint mengembalikan 402 Payment Required — dan yang membuatnya berguna: error itu memberi tahu persis berapa yang dibutuhkan dan berapa sisa Anda.

{
  "status": "error",
  "code": 402,
  "message": "This endpoint costs 300 points per successful hit but your balance is 120.",
  "needed": 300,
  "balance": 120,
  "hint": "POST /billing/topup"
}

Karena payload-nya terstruktur, Anda bisa mengubahnya menjadi top-up otomatis alih-alih membangunkan tim on-call:

async function panggilAI(path, body) {
  let res = await kirim(path, body);

  if (res.status === 402) {
    const err = await res.json();
    // isi ulang cukup untuk pekerjaan ini plus penyangga
    await topUp(Math.max(err.needed * 20, 100000));
    res = await kirim(path, body);          // coba sekali lagi
  }
  return res.json();
}

Alur pembayaran

Top up dan langganan diproses lewat Midtrans. Alurnya tiga langkah, dan langkah ketiga terjadi tanpa Anda menunggu:

• •Backend Anda memanggil POST /billing/topup dan menerima snap_token.
• •Frontend membuka popup pembayaran Midtrans dengan token itu.
• •Setelah pembayaran lunas, Midtrans mengirim webhook ke kami — saldo Anda bertambah otomatis, biasanya dalam hitungan detik.

Perhatikan bahwa saldo bertambah karena webhook settlement, bukan karena popup ditutup. Jangan menambah saldo di frontend saat callback onSuccess berjalan; cukup panggil ulang /keys/me untuk menampilkan angka yang benar dari server.

Kapan memilih yang mana

Kalau pemakaian Anda stabil dan bisa diprediksi — misalnya form checkout yang memanggil API Wilayah ribuan kali sehari — langganan lebih murah dan menghilangkan risiko kehabisan saldo. Kalau pemakaian Anda berbentuk lonjakan — OCR KTP hanya saat ada pengguna baru mendaftar — poin lebih masuk akal: Anda tidak membayar apa pun di hari yang sepi.