Pembangun

API pembayaran kripto yang dibina untuk penyelesaian terus

Cipta invois dengan satu permintaan yang disahkan dan Unheld memulangkan alamat untuk dibayar, jumlah tepatnya, dan kedalaman pengesahan yang akan ditunggunya. Bayaran masuk terus ke dompet yang anda kawal — API ini tidak pernah memegang apa yang dilaporkannya.

Mula percuma Harga

Cipta invois

Satu POST. Jumlahnya ditulis sebagaimana seseorang menulisnya dan diskalakan di pelayan mengikut perpuluhan aset itu sendiri, jadi anda tidak pernah menukar ke unit asas 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 diterbitkan daripada dompet anda dan dikunci pada invois ini. expectedAmount dalam unit asas. minConfirmations ialah ambang rangkaian itu sendiri, bukan tetapan yang kami reka.

Pengesahan dan skop

Kunci ialah token bearer, dicipta dalam papan pemuka dan dipaparkan sekali sahaja. Setiap kunci membawa senarai skop yang jelas dan permintaan ditolak jika kunci itu tiada skop bagi laluan tersebut.

Skop yang ada

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

Berikan set paling sempit yang berfungsi. Kunci yang hanya mencipta invois tidak boleh membaca pelanggan anda, dan kunci baca yang bocor tidak boleh menggerakkan apa-apa — kerana tiada apa dalam API ini yang boleh.

Webhook yang boleh anda sahkan

Setiap penghantaran ditandatangani. Tandatangannya ialah HMAC-SHA256 bagi cap masa dan badan mentah yang dicantum dengan noktah, menggunakan rahsia webhook anda, dihantar sebagai digest heksadesimal.

Mengesahkan penghantaran

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 masa malar, tolak cap masa di luar tetingkap toleransi anda, dan anggap X-Request-Id sebagai kunci idempotensi: cubaan semula menggunakan semula nilai yang sama, jadi peristiwa sama tiba dua kali adalah normal dan tidak boleh diproses dua kali.

Peristiwa invois

Bayaran bergerak melalui keadaan, bukan sekadar bertukar daripada belum dibayar kepada dibayar, dan setiap peralihan ialah webhook. Kurang bayar dan lebih bayar ialah peristiwa tersendiri, bukan ralat.

Peristiwa	Apa yang berlaku
invoice.created	Invois wujud dan alamat penerimaan sedang diperhatikan.
invoice.receiving	Transaksi bayaran dilihat pada rangkaian tetapi belum disahkan.
invoice.confirming	Bayaran sedang disahkan dan belum mencapai ambang rangkaian.
invoice.paid	Disahkan sepenuhnya pada kedalaman yang dikehendaki rangkaian. Selamat untuk dipenuhi.
invoice.underpaid	Kurang daripada yang dijangka telah tiba. Bayaran separa terkumpul, jadi pindahan kedua boleh melengkapkannya.
invoice.overpaid	Lebih daripada yang dijangka telah tiba, direkod dengan tepat dan bukan dibundarkan.
invoice.expired	Tetingkap ditutup tanpa bayaran penuh.

Uji keseluruhan aliran secara percuma

Uji penciptaan invois, pengesanan, pengesahan dan webhook tanpa menggunakan dana pengeluaran. Token testnet tiada nilai wang. Aktiviti testnet bukan bayaran sebenar.

Skop

Ia tidak pernah memegang dana. Tiada endpoint baki untuk dikeluarkan, kerana bayaran mendarat pada alamat anda dan kekal di situ.
Ia tidak menukar atau menyelesaikan dalam mata wang fiat. Bayaran tiba dalam aset dan pada rangkaian yang digunakan semasa dihantar.
Belum ada SDK rasmi. Semuanya di sini HTTP biasa, dan kami menerbitkan contoh dan bukan pakej yang akan kami selenggara dengan buruk.

Soalan pembangun

Adakah terdapat persekitaran ujian?

Uji penciptaan invois, pengesanan, pengesahan dan webhook tanpa menggunakan dana pengeluaran. Token testnet tiada nilai wang. Aktiviti testnet bukan bayaran sebenar.

Bagaimana saya elak memproses webhook sama dua kali?

Gunakan X-Request-Id sebagai kunci idempotensi. Cubaan semula menggunakan semula nilai yang sama, jadi rekodkannya dan abaikan pengulangan. Cubaan semula memang dijangka: penghantaran yang gagal dicuba semula mengikut jadual dan bukan dibuang.

Perlukah saya menukar jumlah ke unit asas sendiri?

Tidak. Hantar amountDecimal sebagaimana seseorang menulisnya dan API menskalakannya mengikut perpuluhan aset. Responsnya memulangkan expectedAmount dalam unit asas, jadi kedua-dua perwakilan adalah jelas dan tidak boleh menyimpang.

Contoh disahkan terhadap API langsung pada 21 September 2026.

Bina pada testnet dahulu

Cipta kunci, halakan ke rangkaian testnet, dan jalankan keseluruhan aliran sebelum apa-apa yang sebenar bergerak.

Mula percuma

Harga · Apa yang anda boleh terima hari ini. · Wang anda tidak melalui kami.