REST API native

API native adalah antarmuka REST milik blockwallets sendiri: invoice berharga sen AS, ref idempoten untuk setiap pesanan, akun deposit statis yang mencakup semua jaringan, dan webhook bertanda tangan HMAC-SHA256. API ini membuat tagihan yang sama di halaman pembayaran yang sama dengan API kompatibel Cryptomus, dengan biaya dan saldo yang sama.

Buat kunci Anda sendiri di dasbor pada “Developer › Integrasi & kunci”: satu kunci Live dan satu kunci Test beserta webhook signing secret-nya. Masing-masing hanya ditampilkan sekali; daftar hanya menampilkan awalannya. Jika akun Anda mengaktifkan verifikasi dua langkah, membuat atau merotasi kunci Live akan meminta kode. Belum punya akun merchant? Minta akses. Sudah memakai Cryptomus? Lihat API kompatibel Cryptomus (cara memilih).

Kunci dan permintaan

Base URL https://blockwallets.io. Permintaan dan respons berupa JSON. Setiap permintaan membawa:

• Authorization: Bearer bw_live_… atau Bearer bw_test_…: awalan menentukan mode, jadi kunci Test hanya melihat invoice Test dan berjalan di testnet
• Content-Type: application/json pada permintaan POST
• Simpan kunci hanya di server Anda, jangan pernah di halaman web atau aplikasi; kami hanya menyimpan hash-nya

Error mengembalikan status HTTP dan {"error": {"code": "…", "message": "…"}}: 400 invalid_request (field hilang atau formatnya salah), 401 unauthorized (kunci tidak ada, tidak dikenal, atau dinonaktifkan), 404 not_found, 409 conflict (permintaan bertentangan dengan status invoice saat ini), 422 currency_unsupported.

Endpoint

Tambahkan ?probe=1 pada pencarian invoice atau akun deposit untuk memeriksa chain saat itu juga (paling banyak sekali per 10 detik); jika tidak, Anda mendapat status terbaru dari pemindai kami, yang memeriksa setiap menit.

Membuat invoice POST /v1/invoices

Panggil POST /v1/invoices saat pelanggan checkout dan arahkan mereka ke pay_url dalam respons.

curl -X POST https://blockwallets.io/v1/invoices \
  -H "Authorization: Bearer $BW_KEY" -H "Content-Type: application/json" \
  -d '{"ref":"order_1042","amount":4200,"title":"Order #1042",
       "return_url":"https://shop.example/cart","success_url":"https://shop.example/thanks?order=1042",
       "meta":{"user_id":42}}'

Setiap URL harus berada di salah satu domain situs Anda (dasbor → “Developer › Integrasi & kunci”). Responsnya adalah objek invoice di bawah; network, address, dan pay_amount terisi setelah jaringan dipilih.

Objek invoice

Id diawali inv_. amount dalam sen AS; pay_amount dan paid_amount adalah jumlah koin sebagai string desimal pada jaringan yang dipilih.

{
  "id": "inv_01J8…",
  "ref": "order_1042",
  "mode": "live",
  "status": "pending",
  "amount": 4200,
  "currency": "USD",
  "title": "Order #1042",
  "meta": { "user_id": 42 },
  "network": null,
  "address": null,
  "pay_amount": null,
  "paid_amount": null,
  "payments": [],
  "pay_url": "https://blockwallets.io/pay/inv_01J8…",
  "return_url": "https://shop.example/cart",
  "success_url": "https://shop.example/thanks?order=1042",
  "created_at": "2026-11-03T08:00:00.000Z",
  "expires_at": "2026-11-03T09:00:00.000Z",
  "paid_at": null,
  "closed_at": null
}

Field lain: pay_url (halaman pembayaran), payments (setiap transfer dengan txid, amount, confirmations, dan confirmed), expires_at, paid_at, closed_at; BTC, LTC, DOGE, BCH, dan koin native juga membawa rate (dolar AS per koin, dikunci 30 menit), rate_locked_until, dan paid_cents (yang sudah masuk, dalam sen AS).

Jaringan

Berikan id sebagai network. GET /v1/networks mengembalikan jaringan yang terbuka saat ini pada mode Anda; jaringan bisa dijeda, jadi lebih baik membacanya daripada menulis nilai secara permanen di kode.

Akun deposit (alamat statis) POST /v1/deposit-accounts

POST /v1/deposit-accounts dengan {"customer_ref": "user_42"} memberi pelanggan itu alamat permanen di setiap jaringan (semua chain EVM memakai satu alamat). Apa pun yang mereka kirim dikreditkan dalam dolar AS, dengan satu webhook deposit.credited per transfer.

curl -X POST https://blockwallets.io/v1/deposit-accounts \
  -H "Authorization: Bearer $BW_KEY" -H "Content-Type: application/json" \
  -d '{"customer_ref":"user_42"}'

{
  "id": "dac_01J8…",
  "mode": "live",
  "customer_ref": "user_42",
  "deposit_url": "https://blockwallets.io/deposit/dac_01J8…",
  "min_amount": 100,
  "currency": "USD",
  "networks": [
    { "id": "USDT_TRC20", "chain": "tron", "token": "USDT", "address": "TXy4…8kQ2", "min_amount": 100, "confirmations": 1, … },
    { "id": "USDC_BASE", "chain": "base", "token": "USDC", "address": "0x5aE1…", "min_amount": 100, "confirmations": 20, … }
  ]
}

• customer_ref: 1–128 karakter berupa huruf, angka, dan _ . : @ -; nilai yang sama selalu mengembalikan akun yang sama. return_url opsional di domain Anda
• Responsnya berisi deposit_url (halaman hosting dengan alamat, kode QR, dan deposit terbaru) dan networks (id, address, min_amount, confirmations untuk tiap jaringan)
• Id deposit diawali dep_; amount dalam sen AS, amount_token jumlah koin, dan koin berharga membawa rate yang dipakai

Transfer di bawah minimum (biasanya $1, BTC $5) dicatat sebagai below_min dan tidak dikreditkan otomatis; hubungi kami agar dikreditkan.

Webhook

Kami mengirim POST JSON ke URL webhook di dasbor (“Developer › Integrasi & kunci”; Live dan Test masing-masing punya URL dan secret sendiri). Body-nya adalah event:

POST /your/webhook
X-BW-Event: ev_01J8…
X-BW-Delivery: 1
X-BW-Signature: t=1793693052,v1=5f0c9b…

{"id":"ev_01J8…","type":"invoice.paid","created_at":"2026-11-03T08:04:12.000Z","invoice":{"id":"inv_01J8…","ref":"order_1042","status":"paid","amount":4200,…}}

• X-BW-Signature: t=<unix seconds>,v1=<hex>, dengan v1 = HMAC-SHA256(webhook secret mode tersebut, t + . + body mentah)
• X-BW-Event: id event (ev_…); hapus duplikat berdasarkan id ini
• X-BW-Delivery: nomor percobaan, mulai dari 1

Verifikasi terhadap body mentah sebelum mem-parse-nya, tolak t yang selisihnya lebih dari 300 detik dari jam Anda, dan bandingkan dalam waktu konstan. invoice / deposit di body adalah objek yang sama dengan hasil pencarian.

import crypto from "node:crypto";

// rawBody: the request body exactly as received (a string), header: X-BW-Signature
function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
  const t = Number(parts.t);
  if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return typeof parts.v1 === "string" && parts.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
}

Respons 2xx dianggap terkirim; jika tidak, kami coba lagi setelah 1 menit, 5 menit, 30 menit, 2 jam, 12 jam, 24 jam, dan 24 jam (total 8 percobaan).

Events dan pengiriman ulang

GET /v1/events?invoice_id=inv_… (atau deposit_id=dep_…) menampilkan webhook satu invoice atau deposit beserta state, attempts, last_status, dan last_error. POST /v1/events/ev_…/redeliver langsung mengantrekannya lagi, misalnya setelah Anda memperbaiki endpoint. “Developer › Log webhook” di dasbor menampilkan setiap percobaan beserta permintaan dan responsnya.

Mode uji

Invoice yang dibuat dengan kunci bw_test_ berjalan di testnet dan tidak pernah menyentuh uang sungguhan. Halaman pembayaran menampilkan tombol “Simulasikan pembayaran” (penuh / setengah / lebih), sehingga Anda bisa melihat status dan webhook tanpa koin testnet.