# 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:

1. Buat akun merchant dan project di [2328.io](https://2328.io)
2. Dapatkan **project UUID** dan **API key** Anda dari pengaturan project
3. Buat **Payout API key** terpisah jika Anda berencana menggunakan penarikan
4. Baca bagian [Authentication](/docs/authentication) untuk mempelajari cara menandatangani permintaan
5. Lakukan panggilan [Create Payment](/docs/payments) pertama Anda

## Base URL

Semua permintaan API produksi menggunakan base URL berikut:

```
https://api.2328.io/api
```

> **WARNING:** Semua 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. |

> **INFO:** 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_id` sebelum permintaan pertama dan simpan permintaan lengkap bersamanya. Upaya ulang dengan `order_id` yang 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.