Informasi Umum
Spesifikasi teknis untuk integrasi pemrosesan pembayaran dan penarikan kripto dengan 2328.io.
Selamat datang di dokumentasi API 2328.io. Referensi ini menjelaskan cara mengintegrasikan pemrosesan pembayaran kripto dan penarikan ke dalam aplikasi Anda.
Memulai
Untuk memulai integrasi:
- Buat akun merchant dan project di 2328.io
- Dapatkan project UUID dan API key Anda dari pengaturan project
- Buat Payout API key terpisah jika Anda berencana menggunakan penarikan
- Baca bagian Authentication untuk mempelajari cara menandatangani permintaan
- Lakukan panggilan Create Payment pertama Anda
Base URL
Semua permintaan API produksi menggunakan base URL berikut:
https://api.2328.io/apiSemua permintaan harus dilakukan melalui HTTPS. Permintaan tanpa HTTPS akan diblokir.
Apa yang dapat Anda lakukan
Dengan API 2328.io Anda dapat:
- Menerima pembayaran kripto — buat sesi pembayaran dan arahkan pelanggan ke checkout terhosting atau Telegram MiniApp
- Menarik dana — kirim penarikan secara terprogram dari saldo merchant Anda ke alamat blockchain mana pun
- Cek saldo — lihat saldo akun merchant per mata uang, ekuivalen USD, dan jumlah yang terkunci AML
- Menggunakan dompet statis — buat alamat deposit permanen yang terikat pada pengguna atau pesanan
- Mengambil nilai tukar — dapatkan nilai tukar real-time untuk pasangan fiat dan kripto
- Menerima webhook — dapatkan notifikasi seketika saat status pembayaran berubah
Batas laju permintaan
API mengizinkan hingga 10 permintaan per detik per project. Permintaan yang melebihi batas akan menerima respon HTTP 429 Too Many Requests — mundur dan coba lagi.
Pilih pola integrasi yang tepat
| Persyaratan | Pola yang disarankan | Mengapa |
|---|---|---|
| Biarkan pelanggan memilih cara membayar | Checkout yang dihosting | Buat pembayaran dan alihkan ke result.url; 2328.io menampilkan arah yang tersedia saat ini. |
| Pertahankan pelanggan di dalam checkout Anda sendiri | Tagihan dengan alamat langsung H2H | Kirim to_currency dan network saat membuat pembayaran; tampilkan address, payer_amount, dan qr yang dikembalikan. |
Kenakan biaya tepat sesuai 25 USDT atau 0.001 BTC | Tagihan dalam denominasi kripto | Letakkan cryptocurrency di currency dan jumlah desimal yang tepat di amount. |
| Berikan setiap pengguna alamat deposit yang dapat digunakan kembali | Dompet statis | Alamat ini bersifat permanen dan dapat menerima banyak deposit independen. |
| Normalkan aset yang masuk menjadi satu mata uang saldo | Konversi otomatis | Konfigurasikan aturan proyek di dashboard dan gunakan hasil convert saat konversi selesai. |
| Tukar saldo merchant yang ada | Konversi manual | Pratinjau dengan /v1/convert/price, lalu eksekusi dengan /v1/convert. |
| Kirim dana ke alamat blockchain | Pembayaran | Gunakan kunci API Payout yang terpisah, hitung terlebih dahulu, dan rekonsiliasi status pembayaran. |
Hosted checkout dan H2H adalah dua presentasi dari Payment API yang sama. H2H tidak membuat pembayaran yang lebih lemah atau tidak ditandatangani: backend tetap membuat faktur, 2328.io tetap memiliki alamat dan status, dan webhook yang ditandatangani tetap menjadi otoritas untuk penyelesaian.
Invarian integrasi
Aturan-aturan ini berlaku untuk setiap integrasi produksi:
- Backend only — jaga kunci API agar tidak keluar dari browser, aplikasi seluler, log, analitik, dan tangkapan layar dukungan.
- Decimal strings — kirim dan simpan uang sebagai string. Jangan pernah membulatkan mata uang kripto atau nilai tukar dengan aritmetika floating-point biner.
- Immutable idempotency keys — buat
order_idsebelum permintaan pertama dan simpan permintaan lengkap bersamanya. Upaya ulang denganorder_idyang sama dapat mengembalikan objek asli daripada menerapkan bidang yang diubah. - Webhook-first settlement — pengalihan, polling klien, hash transaksi yang diberikan pengguna, dan batas waktu HTTP bukan bukti pembayaran.
- Verify, deduplicate, then mutate — verifikasi HMAC, klaim catatan idempoten secara atomik, perbarui pesanan/saldo sekali, dan kembalikan HTTP 200 dengan cepat.
- Reconciliation — secara berkala periksa status pembayaran, dompet statis, dan pembayaran agar webhook yang hilang tidak meninggalkan ketidaksepakatan permanen.
- Dynamic availability — memvalidasi pasangan mata uang/jaringan dengan
/v1/directions; aset yang didukung masih bisa memiliki satu arah setoran atau penarikan yang sementara dinonaktifkan. - Explicit status policy — tentukan bagaimana produk Anda menangani pembayaran sebagian, kelebihan pembayaran, kedaluwarsa, blokir AML, fallback konversi, dan timeout hulu yang ambigu sebelum diluncurkan.
Data yang disarankan untuk disimpan
Untuk pembayaran, simpan minimal uuid, order_id, badan permintaan asli, amount, currency, payer_currency, payer_amount, network, address, expires_at, payment_status terbaru, txid, payment_amount, merchant_amount, blok convert opsional, dan payload webhook mentah yang telah diverifikasi.
Untuk dompet statis, simpan dompet uuid, alamat, mata uang, jaringan, referensi pelanggan/akun, status, dan URL callback secara terpisah dari catatan setoran. Setiap setoran membutuhkan transaksi uuid, txid, status, jumlah yang diterima, jumlah pedagang, dan hasil konversi masing-masing.