Payment API

Payment API memungkinkan Anda membuat sesi pembayaran, mengarahkan pelanggan ke checkout terhosting, dan melacak status pembayaran.

Buat pembayaran

{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Checkout yang dihosting, H2H, dan jumlah crypto yang tepat

Endpoint yang sama mendukung tiga bentuk faktur yang berbeda. Pilih salah satunya dengan sengaja; jangan mencampur semantik jumlah mereka.

Checkout yang dihosting dengan pilihan pembayar

Kirim amount, currency, order_id, dan url_callback, tetapi hilangkan to_currency dan network. Respon berisi result.url; address, qr, dan kadang-kadang bidang pembayar tetap null sampai pembayar memilih arah di halaman yang dihosting.

{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}

Faktur H2H alamat langsung

Kirimkan kedua to_currency dan network. 2328.io membuat faktur blockchain selama panggilan API, jadi respons yang berhasil dapat ditampilkan di dalam checkout Anda tanpa mengarahkan pelanggan.

{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}

Tampilkan nilai-nilai ini persis seperti dikembalikan:

• payer_amount dan payer_currency — instruksi pembayaran;
• network dan address — satu-satunya tujuan untuk faktur ini;
• qr — URI data untuk alamat yang sama;
• expires_at — batas waktu faktur;
• url — fallback host yang berguna ketika checkout kustom tidak dapat diselesaikan.

Faktur untuk jumlah kripto yang tepat

Masukkan cryptocurrency ke dalam currency ketika faktur itu sendiri dinyatakan dalam crypto:

{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}

Nilai crypto yang diminta dipertahankan dalam payer_currency / payer_amount. Layanan ini juga dapat mempertahankan valuasi USD secara internal untuk bidang akuntansi dan nilai tukar; jangan ganti instruksi crypto yang tepat dengan valuasi tersebut. Pertahankan string desimal yang dikembalikan, termasuk presisi di belakang koma.

Untuk cryptocurrency dengan hanya satu jaringan yang didukung, jaringan dapat dipilih secara otomatis. Namun, tetap disarankan untuk secara eksplisit menyertakan network untuk integrasi yang deterministik. Untuk aset multi-jaringan seperti stablecoin, selalu kirimkan.

Idempoten dan percobaan ulang

order_id bersifat terbatas pada proyek pedagang yang terautentikasi dan berfungsi sebagai kunci idempoten pembuatan. Jika pembayaran sudah ada, API akan mengembalikan sesi tersebut dengan state: 0.

Algoritma pembuatan yang disarankan:

1. Masukkan percobaan pembayaran lokal Anda dan order_id unik ke dalam satu transaksi basis data.
2. Kirim permintaan API yang telah ditandatangani.
3. Simpan uuid yang dikembalikan dan respons lengkap.
4. Jika hasil HTTP hilang, coba ulang permintaan yang sama atau query /v1/payment/info melalui order_id.
5. Jangan pernah membuat pesanan lokal kedua hanya karena permintaan hulu mengalami timeout.

Kasus tepi pembayaran

URL pengembalian browser hanya untuk navigasi. Seorang pelanggan bisa membukanya tanpa membayar, menutupnya setelah membayar, atau memutarnya kembali nanti. Hanya status API/webhook yang terverifikasi yang dapat menyelesaikan pesanan pedagang.

Info pembayaran

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

Daftar pembayaran

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"