Cara Mengatur Isi Ulang Saldo Otomatis di Panel SMM melalui API

Apa yang perlu disiapkan sebelum mengatur isi ulang otomatis

Isi ulang otomatis menghubungkan saldo panel SMM dengan layanan pembayaran atau billing internal. Layanan memeriksa sisa saldo, membuat pembayaran saat mencapai ambang yang ditentukan, dan mengkreditkan dana hanya setelah pembayaran dikonfirmasi. Agar berfungsi, diperlukan dokumentasi API panel, akses ke API pembayaran, kunci terpisah untuk lingkungan pengujian dan produksi, serta log semua operasi.

Sebelum pengembangan, periksa apakah API panel dapat mengembalikan saldo, menerima permintaan kredit, menampilkan riwayat isi ulang, dan menerima pengenal operasi eksternal. Jika panel tidak mendukung kredit melalui API, otomatisasi hanya dapat membuat permintaan atau mengirim notifikasi ke operator. Kekurangan opsi ini — dana tetap harus disetor secara manual.

Pisahkan pemeriksaan saldo dan keputusan pembayaran

Pemeriksaan sisa saldo sebaiknya dijalankan sebagai tugas terpisah sesuai jadwal. Tugas ini mengambil saldo, membandingkannya dengan ambang, dan meneruskan hasilnya ke penangan isi ulang. Jangan membuat pembayaran tepat saat respons API tanpa memeriksa operasi yang belum selesai: tugas paralel dapat melihat saldo rendah yang sama dan membuat beberapa pembayaran.

Sebelum pembayaran baru, penangan harus memeriksa apakah ada operasi berstatus "dibuat", "menunggu pembayaran", atau "sedang dikonfirmasi". Jika ada catatan seperti itu, upaya baru tidak dijalankan hingga rekonsiliasi selesai. Kekurangan pemrosesan berurutan — jika respons API eksternal lambat, isi ulang dapat dimulai lebih lambat dibandingkan dengan beberapa permintaan paralel.

Pilih ambang dan logika jumlah isi ulang

Ambang saldo dipilih dengan cadangan untuk pesanan aktif, antrean di pemasok, dan keterlambatan pembayaran. Untuk kanal dengan aktivitas tidak merata, berpatokan hanya pada rata-rata pengeluaran itu berisiko: setelah streaming, peluncuran iklan, atau pesanan massal, pengurangan bisa meningkat tajam. Tingkat kritis ditetapkan secara terpisah, di mana notifikasi dikirim, tetapi pembayaran tidak harus dibuat otomatis.

Jumlah isi ulang dapat tetap atau dihitung dari pengeluaran selama periode tertentu. Jumlah tetap lebih mudah untuk dikontrol dan direkonsiliasi. Kekurangannya — pada periode tenang, dana berlebih dapat tersimpan di saldo, dan saat pesanan meningkat tajam, satu isi ulang mungkin tidak cukup. Jumlah terhitung lebih fleksibel, tetapi memerlukan pembersihan statistik dari pengurangan dan pengembalian yang tidak normal.

Atur batas keuangan secara terpisah dari ambang

Ambang hanya menjawab pertanyaan kapan sistem diizinkan memulai proses isi ulang. Batas menjawab pertanyaan lain: berapa banyak dana yang boleh didebit. Tetapkan jumlah maksimum per operasi, batas total per periode, dan saldo yang diizinkan setelah kredit. Aturan ini diperiksa sebelum pembayaran dibuat, bukan setelah dibayar.

Isi ulang otomatis tidak boleh mendebit dana tanpa batas per operasi dan periode. Jika jumlah terhitung melebihi yang diizinkan, operasi sebaiknya dialihkan ke pemeriksaan manual dan notifikasi dikirim. Kekurangan batas ketat — saat pengeluaran tumbuh cepat, saldo dapat habis sebelum karyawan yang bertanggung jawab mengonfirmasi kenaikan batas.

Buat kunci terpisah dan lindungi akses

Untuk skrip isi ulang otomatis, gunakan kunci API terpisah dengan hak minimum: membaca saldo, membuat pembayaran, memeriksa status, dan mengkredit operasi yang dikonfirmasi. Akses ke pengguna, pengaturan layanan, pesanan, dan penarikan dana tidak diperlukan untuk kunci ini. Jika layanan mendukung pembatasan berdasarkan alamat IP, izinkan permintaan hanya dari server integrasi.

Kunci disimpan dalam variabel lingkungan atau penyimpanan rahasia yang aman. Jangan meneruskannya ke kode browser, log, repositori publik, dan pesan kesalahan. Setiap kunci harus memiliki pemilik dan prosedur penggantian yang jelas. Kekurangan rotasi kunci yang sering — isi ulang akan berhenti jika rahasia baru tidak diperbarui di semua proses kerja.

Buat pembayaran dengan pengenal unik

Setiap isi ulang diberi pengenal internal sebelum memanggil API pembayaran. Pengenal disimpan di log dan diteruskan sebagai kunci idempotensi atau nomor operasi eksternal. Saat terjadi timeout jaringan, permintaan yang sama dapat diulang dengan pengenal yang sama: layanan pembayaran harus mengembalikan operasi yang sudah dibuat, bukan mendebit dana dua kali.

Berikut adalah contoh umum permintaan. Ganti nama field dan alamat dengan nilai dari dokumentasi penyedia tertentu. Variabel PAYMENT_ID menyimpan ID unik yang dibuat sebelumnya, dan CALLBACK_URL mengarah ke penangan webhook.

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

Jangan menentukan keunikan pembayaran hanya berdasarkan jumlah dan waktu pembuatan. Dua isi ulang yang identik bisa sah, sedangkan permintaan ulang setelah kegagalan tidak. Kekurangan ID eksternal di basis data sendiri — ID harus disimpan dengan andal dan tidak digunakan ulang setelah operasi dibatalkan.

Periksa saldo dan simpan status operasi

Permintaan saldo harus dilakukan sebelum keputusan isi ulang baru dan setelah kredit berhasil. Permintaan umum dapat terlihat seperti ini: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". Dalam respons, simpan tidak hanya jumlah, tetapi juga waktu pemeriksaan, agar tidak mengambil keputusan berdasarkan data yang sudah usang.

Untuk setiap operasi, buat catatan dengan ID internal, ID pembayaran di penyedia, jumlah, mata uang, waktu pembuatan, status, respons API, dan alasan kesalahan. Rantai status yang sesuai: "dibuat", "menunggu pembayaran", "dibayar", "sedang dikreditkan", "dikreditkan", "dibatalkan", "memerlukan pemeriksaan".

Kredit ke panel hanya diizinkan untuk pembayaran yang dikonfirmasi dan belum diproses. Jangan menimpa status tanpa riwayat: saat terjadi sengketa, harus terlihat permintaan apa yang dikirim dan mengapa operasi diubah. Kekurangan log terperinci — log dapat berisi data sensitif, sehingga aksesnya dibatasi.

Terima webhook dan cocokkan status pembayaran

Halaman pembayaran berhasil dan pengalihan pengguna tidak mengonfirmasi masuknya dana. Konfirmasi diberikan oleh webhook dari layanan pembayaran atau pemeriksaan ulang status melalui API-nya. Saat menerima webhook, periksa tanda tangan, waktu pengiriman, ID pembayaran, ID eksternal, jumlah, dan mata uang. Hanya setelah itu ubah operasi ke status pembayaran terkonfirmasi.

Setelah memeriksa webhook, sebaiknya minta status pembayaran terkini dari penyedia. Contohnya: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". Cocokkan status dengan data log, lalu kirim permintaan kredit ke panel SMM dengan ID internal yang sama.

Webhook berulang tidak boleh membuat kredit kedua. Penangan menemukan operasi berdasarkan ID eksternal, melihat status "dikreditkan", dan mengembalikan respons berhasil tanpa tindakan baru. Kekurangan webhook — webhook dapat tertunda atau tidak sampai jika penangan tidak tersedia.

Tangani timeout, retry, dan pembayaran yang macet

Saat terjadi timeout setelah pembayaran dibuat, jangan kirim permintaan baru dengan ID berbeda. Pertama, temukan operasi berdasarkan pengenal internal atau ulangi permintaan dengan kunci idempotensi yang sama. Jika penyedia menerima permintaan awal, penyedia akan mengembalikan pembayaran yang sudah ada. Ini melindungi dari pendebitan ganda saat koneksi terputus.

Jika webhook tidak datang dalam waktu yang ditentukan, tugas latar belakang meminta status pembayaran melalui API. Pemeriksaan ulang dilakukan dengan jeda yang meningkat dan jumlah percobaan terbatas, agar tidak membebani API dan log. Operasi yang lama menunggu dialihkan ke pemeriksaan manual, bukan dianggap dibatalkan tanpa rekonsiliasi.

Saat ada respons tentang kesalahan jaringan sementara atau API tidak tersedia, retry diperbolehkan. Saat penolakan pembayaran, jumlah salah, tanda tangan webhook tidak valid, atau batas terlampaui, permintaan sebaiknya tidak diulang otomatis. Kekurangan retry — retry mempersulit logika status dan dapat menimbulkan beban berlebih saat terjadi kegagalan massal di penyedia.

Kreditkan pembayaran yang dikonfirmasi ke panel SMM

Sebelum kredit, penangan memeriksa sekali lagi: jumlah tidak melebihi batas, mata uang cocok, operasi belum dibatalkan, dan statusnya belum "dikreditkan". Permintaan meneruskan jumlah dan pengenal pembayaran eksternal. Jika API panel mendukung kunci idempotensi, gunakan ID operasi internal yang sama.

Bentuk umum permintaan: curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

Setelah respons panel, minta saldo kembali dan simpan hasilnya di log. Jika dana telah didebit di layanan pembayaran tetapi API panel mengembalikan kesalahan, jangan buat pembayaran baru. Operasi tetap berstatus "memerlukan pemeriksaan" hingga upaya kredit ulang atau rekonsiliasi manual. Kekurangan skema hati-hati ini — saldo mungkin sementara tidak terisi ulang secara otomatis.

Tambahkan notifikasi, sakelar, dan pemeriksaan peluncuran

Notifikasi diperlukan untuk penyimpangan: saldo turun di bawah tingkat kritis, pembayaran ditolak, webhook tidak diterima, batas terlampaui, API tidak tersedia, atau operasi memerlukan pemeriksaan manual. Dalam pesan, cukup cantumkan ID internal, status, dan alasan. Jangan sertakan kunci API, tanda tangan webhook, dan detail pembayaran.

Sediakan sakelar terpisah untuk isi ulang otomatis tanpa menghapus integrasi. Sakelar ini diperlukan saat mengganti penyedia, pekerjaan teknis, dugaan kesalahan, atau perubahan pengeluaran yang tiba-tiba. Kekurangan sakelar sudah jelas: jika tidak dinyalakan kembali setelah pekerjaan, saldo dapat habis selama pesanan aktif.

Daftar periksa sebelum mengaktifkan isi ulang otomatis

• Pemeriksaan saldo tidak membuat pembayaran selama ada operasi yang belum selesai.
• Untuk setiap pembayaran dibuat ID internal unik dan kunci idempotensi.
• Batas untuk satu operasi dan periode tertentu telah diatur.
• Webhook diperiksa berdasarkan tanda tangan, jumlah, mata uang, dan pengenal.
• Jika webhook tidak ada, pemeriksaan ulang status melalui API dijalankan.
• Timeout tidak menyebabkan pembuatan pembayaran kedua sebelum pembayaran pertama diperiksa.
• Kredit ke panel dilakukan satu kali dan dicatat di log.
• Mode pengujian telah diperiksa untuk keberhasilan, penolakan, webhook duplikat, dan API tidak tersedia.