Panduan integrasi

Server Anda membuat pembayaran lewat API, lalu kokiwa mengirim webhook saat dana masuk. Dana langsung masuk ke dompet Anda di on-chain; kokiwa tidak pernah menyimpannya.

Persiapan

Semua ini dilakukan di dasbor merchant.

1. DaftarVerifikasi email, siapkan aplikasi autentikator, dan simpan kode pemulihan.
2. Buat proyekSatu proyek mewakili satu produk atau situs Anda, dengan alamat penerimaan, API key, dan webhook sendiri.
3. Atur penerimaanDi halaman Pengaturan penerimaan proyek, pilih chain, metode penerimaan, dan token, lalu daftarkan alamat penerimaan di tiap chain dengan dompet Anda. Alamat penerimaan dicatat on-chain dan hanya dompet yang mendaftarkannya yang bisa mengubahnya. Pendaftaran butuh sedikit gas; satu dompet bisa mendaftarkan semua chain EVM.
4. Buat API keyKey hanya ditampilkan sekali. Simpan di variabel lingkungan server, jangan di front-end atau aplikasi.
5. Atur webhookDi halaman Webhook, masukkan URL https, simpan rahasia tanda tangan, lalu klik Kirim peristiwa uji untuk memastikan diterima.

Pilih cara menerima

Anda bisa memakai keduanya.

Pembayaran

Buat pembayaran saat pengguna memesan, lalu buka checkout_url yang dikembalikan untuknya. Permintaan di bawah menawarkan semua chain tempat proyek menerima USDT, dan pengguna memilih salah satunya.

curl https://api.kokiwa.com/v1/payment_intents \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-10086" \
  -d '{
    "currency": "USDT",
    "amount": "25.00",
    "customer": "user_42",
    "metadata": { "order_id": "10086" },
    "success_url": "https://your-shop.com/orders/10086"
  }'

Alamat setoran

Isi customer dengan ID pengguna di sistem Anda. Panggilan berulang untuk pengguna yang sama mengembalikan alamat yang sama.

curl https://api.kokiwa.com/v1/deposit_addresses \
  -H "Authorization: Bearer $KOKIWA_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "customer": "user_42" }'

Konfirmasi pembayaran

Setelah pembayaran terkonfirmasi on-chain, kokiwa mengirim webhook. Kreditkan hanya berdasarkan webhook, jangan karena pengguna kembali ke success_url.

• Pembayaran: saat payment_intent.paid, tandai pesanan sudah dibayar.
• Alamat setoran: saat deposit.confirmed, tambahkan saldo data.deposit.customer.

Verifikasi tanda tangan setiap peristiwa dan buang duplikat berdasarkan id peristiwa, lihat Webhook.

Jumlah

Semua jumlah berupa string dalam satuan token, seperti "25.00" atau "24.9125", sama di permintaan, respons, dan webhook, jadi tidak perlu konversi per chain. Jumlah mempertahankan presisi penuh on-chain, sehingga banyaknya desimal bisa berbeda. Jangan menghitung dengan floating point.

Pengembalian dana

Dana sudah ada di dompet Anda, jadi kokiwa tidak punya endpoint pengembalian dana dan tidak bisa membatalkan pembayaran. Untuk mengembalikan dana, kirim dari alamat penerimaan Anda ke pengguna. Mintalah alamat pengembalian dari pengguna, jangan memakai transaction.from, karena itu alamat bursa jika pengguna menarik dari bursa. Biaya tidak dikembalikan.

Daftar periksa peluncuran

• API key hanya ada di server, tidak di repositori kode atau log.
• Webhook memverifikasi tanda tangan, dan peristiwa berulang tidak dikreditkan dua kali.
• Pembayaran dibuat dengan Idempotency-Key, sehingga percobaan ulang jaringan tidak membuat dua pembayaran.
• payment_intent.paid_late ditangani, sehingga pembayaran setelah kedaluwarsa tidak hilang.
• Alamat penerimaan sudah terdaftar di mainnet dan Anda beralih ke key yang diawali sk_live_.
• Frasa pemulihan alamat penerimaan sudah dicadangkan.