Developer

API pembayaran kripto yang dibangun untuk penyelesaian langsung

Buat invoice dengan satu permintaan terautentikasi dan Unheld mengembalikan alamat yang harus dibayar, nominal persisnya, dan kedalaman konfirmasi yang akan ditunggunya. Pembayaran masuk langsung ke dompet yang Anda kendalikan — API ini tidak pernah menjadi kustodian atas apa yang dilaporkannya.

Mulai gratis Harga

Membuat invoice

Satu POST. Nominal ditulis seperti orang menuliskannya dan diskalakan di sisi server sesuai desimal asetnya, jadi Anda tidak pernah mengonversi ke unit dasar secara manual.

curl -X POST https://api.unheld.io/api/v1/invoices \
  -H "Authorization: Bearer $UNHELD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "11155111",
    "assetType": "native",
    "amountDecimal": "0.05",
    "expiresInSeconds": 900,
    "metadata": { "orderId": "A-1043" }
  }'

Respons

{
  "id": "e2b0…",
  "status": "CREATED",
  "receiveAddress": "0x…",
  "expectedAmount": "50000000000000000",
  "minConfirmations": 3,
  "expiresAt": "2026-08-10T14:15:00.000Z",
  "instructions": {
    "chainId": "11155111",
    "to": "0x…",
    "amount": "50000000000000000",
    "assetType": "native"
  }
}

receiveAddress diturunkan dari dompet Anda dan dikunci ke invoice ini. expectedAmount dalam unit dasar. minConfirmations adalah ambang milik jaringan itu sendiri, bukan setelan yang kami karang.

Autentikasi dan scope

Kunci berupa token bearer, dibuat di dasbor dan ditampilkan sekali saja. Setiap kunci membawa daftar scope eksplisit dan permintaan ditolak bila kunci tidak punya scope untuk rute tersebut.

Scope yang tersedia

invoices:write
invoices:read
webhooks:write
webhooks:read
balances:read
customers:write
customers:read
subscriptions:write
subscriptions:read

Berikan himpunan tersempit yang cukup. Kunci yang hanya membuat invoice tidak bisa membaca pelanggan Anda, dan kunci baca yang bocor tidak bisa memindahkan apa pun — karena tidak ada di API ini yang bisa.

Webhook yang bisa Anda verifikasi

Setiap pengiriman ditandatangani. Tanda tangannya adalah HMAC-SHA256 dari timestamp dan body mentah yang disatukan dengan titik, memakai secret webhook Anda, dikirim sebagai digest heksadesimal.

Memverifikasi pengiriman

const signature = crypto
  .createHmac("sha256", webhookSecret)
  .update(`${req.headers["x-timestamp"]}.${rawBody}`)
  .digest("hex");

crypto.timingSafeEqual(
  Buffer.from(signature),
  Buffer.from(req.headers["x-signature"])
);

Bandingkan digest dalam waktu konstan, tolak timestamp di luar jendela toleransi Anda, dan perlakukan X-Request-Id sebagai kunci idempotensi: percobaan ulang memakai nilai yang sama, jadi event yang sama datang dua kali itu wajar dan tidak boleh diproses dua kali.

Event invoice

Pembayaran bergerak melalui beberapa status, bukan sekadar berbalik dari belum dibayar menjadi dibayar, dan setiap transisi adalah webhook. Kurang bayar dan lebih bayar adalah event tersendiri, bukan galat.

Event	Apa yang terjadi
invoice.created	Invoice ada dan alamat penerimaannya diawasi.
invoice.receiving	Transaksi pembayaran terlihat di jaringan tetapi belum terkonfirmasi.
invoice.confirming	Pembayaran sedang dikonfirmasi dan belum mencapai ambang jaringan.
invoice.paid	Terkonfirmasi penuh pada kedalaman yang diwajibkan jaringan. Aman untuk dipenuhi.
invoice.underpaid	Yang masuk lebih sedikit dari yang diharapkan. Pembayaran sebagian terakumulasi, jadi transfer kedua bisa melengkapinya.
invoice.overpaid	Yang masuk lebih banyak dari yang diharapkan, dicatat persis alih-alih dibulatkan.
invoice.expired	Jendelanya tertutup tanpa pembayaran penuh.

Uji seluruh alurnya gratis

Uji invoice, deteksi, konfirmasi, dan webhook tanpa memakai dana produksi. Token testnet tidak memiliki nilai uang. Aktivitas testnet bukan pembayaran produksi.

Cakupan

Ia tidak pernah menyimpan dana. Tidak ada endpoint saldo untuk ditarik, karena pembayaran mendarat di alamat Anda dan tetap di sana.
Ia tidak mengonversi atau menyelesaikan dalam fiat. Pembayaran tiba dalam aset dan di jaringan tempat ia dikirim.
Belum ada SDK resmi. Semua di sini HTTP biasa, dan kami menerbitkan contoh alih-alih paket yang akan kami rawat dengan buruk.

Pertanyaan developer

Apakah ada sandbox?

Uji invoice, deteksi, konfirmasi, dan webhook tanpa memakai dana produksi. Token testnet tidak memiliki nilai uang. Aktivitas testnet bukan pembayaran produksi.

Bagaimana menghindari memproses webhook yang sama dua kali?

Gunakan X-Request-Id sebagai kunci idempotensi. Percobaan ulang memakai nilai yang sama, jadi catat dan abaikan pengulangannya. Percobaan ulang memang diharapkan: pengiriman yang gagal diulang sesuai jadwal, bukan dibuang.

Apakah saya harus mengonversi nominal ke unit dasar sendiri?

Tidak. Kirim amountDecimal seperti orang menuliskannya dan API menskalakannya sesuai desimal aset. Responsnya mengembalikan expectedAmount dalam unit dasar, sehingga kedua representasi eksplisit dan tidak bisa menyimpang.

Contoh diverifikasi terhadap API langsung pada 21 September 2026.

Bangun dulu di testnet

Buat kunci, arahkan ke jaringan testnet, dan jalankan seluruh alurnya sebelum ada apa pun yang nyata bergerak.

Mulai gratis

Harga · Yang bisa Anda terima hari ini. · Uang Anda tidak melewati kami.