API kompatibel Cryptomus

blockwallets memungkinkan Anda menerima USDT dan USDC, plus BTC, LTC, DOGE, BCH, dan koin native (dikreditkan dalam dolar AS dengan kurs yang dikunci): pelanggan membayar, kami mengonfirmasinya di chain, lalu memberi tahu Anda. API, tanda tangan, dan webhook-nya sama dengan Cryptomus — jika Anda sudah mengintegrasikan Cryptomus, cukup ganti domain. Cara kerjanya dijelaskan dulu, baru API.

Dua cara menerima pembayaran

Keduanya menerima jumlah berapa pun: pesanan berharga tetap maupun top-up yang jumlahnya diketik pelanggan. Setelah dibayar, Anda mengirim barang atau menambah saldo pelanggan. Satu-satunya beda adalah apakah setiap pembayaran mendapat alamat baru.

Jika ragu, pakai tagihan. Tanpa kode, tautan pembayaran di dasbor adalah tagihan yang dibuatkan untuk Anda. Belum jadi merchant? Minta akses di beranda; setelah disetujui, masuk ke dasbor merchant dan mulai dari “Coba satu pembayaran” di beranda dasbor dengan jumlah kecil dulu (dananya masuk ke saldo Anda sendiri).

Alur sebuah tagihan

Pembayaran melibatkan empat pihak: pelanggan, situs Anda, blockwallets, dan blockchain. Diagram berjalan dari atas ke bawah menurut waktu; kolom kanan adalah status tagihan di setiap langkah.

Singkatnya, lima langkah:

1. Anda membuat tagihan (tautan pembayaran melakukannya untuk Anda, atau server Anda memanggil /v1/payment), mendapat url halaman pembayaran, lalu mengarahkan pelanggan ke sana.
2. Di halaman pembayaran, pelanggan memilih koin dan jaringan, mendapat alamat dan jumlah khusus, lalu membayar dari dompet atau exchange.
3. Kami melihat transfer di chain, menunggu cukup konfirmasi, lalu memeriksanya silang dengan penyedia node kedua (sehingga satu node tidak bisa memalsukannya).
4. Tagihan menjadi paid dan kami langsung mengirim POST webhook bertanda tangan ke url_callback Anda; beberapa detik kemudian halaman pembayaran mengembalikan pelanggan ke url_success Anda.
5. Dana dikreditkan ke saldo Anda; tarik ke dompet sendiri dari dasbor merchant.

Status tagihan

Saat is_final bernilai true, status tidak akan berubah lagi (kecuali pembayaran terlambat).

Tautan pembayaran (tanpa kode)

Dasbor merchant → “Pembayaran › Tautan pembayaran” → isi keterangan dan jumlah (tentukan jaringan atau biarkan pelanggan memilih) → buat. Setiap tautan punya URL dan kode QR.

• Setiap kali seseorang membuka tautan, tagihan baru dibuat, jadi satu tautan bisa dipakai berulang (misalnya “Keanggotaan $99”).
• Setiap pembayaran muncul di “Pembayaran › Pembayaran masuk”; tarik ke dompet Anda dari “Dana › Saldo & penarikan”.
• Jika Anda sudah membuat kredensial dan URL webhook di “Developer › Integrasi & kunci”, pembayaran lewat tautan juga diberitahukan dalam format di bawah.
• Untuk berhenti menerima, klik “Nonaktifkan” dan tautan langsung tidak berfungsi.

Integrasi API

1. Kredensial dan tanda tangan

Dasbor merchant → “Developer › Integrasi & kunci” → buat merchant (UUID) dan API key. Ada satu set untuk Live dan satu untuk Test: Live memakai uang sungguhan, Test berjalan di testnet. Tambahkan juga domain situs web Anda: url_callback, url_return, dan url_success harus berada di domain itu. API key hanya ditampilkan sekali — simpan dengan aman dan hanya di server Anda.

Base URL https://blockwallets.io. Setiap endpoint memakai POST + JSON, dengan header berikut:

• merchant: UUID merchant Anda (ini menentukan Live atau Test)
• sign: md5(base64(request body) + API key), dengan body berupa string JSON persis seperti yang Anda kirim

Berhasil mengembalikan {"state": 0, "result": {…}}; gagal mengembalikan {"state": 1, "message": "…"} (lihat Error).

Endpoint utama di bawah punya panel “Coba”: masukkan merchant dan API key Test Anda, lalu halaman menandatangani permintaan di browser Anda, memanggil endpoint, dan menampilkan permintaan serta respons lengkap (kredensial hanya ada di memori halaman). Jika tanda tangan tidak cocok, bandingkan langkah demi langkah dengan pemeriksa tanda tangan.

import crypto from "node:crypto";

async function call(path, data) {
  const body = JSON.stringify(data);
  const sign = crypto.createHash("md5").update(Buffer.from(body).toString("base64") + process.env.BW_API_KEY).digest("hex");
  const res = await fetch("https://blockwallets.io" + path, {
    method: "POST",
    headers: { merchant: process.env.BW_MERCHANT, sign, "Content-Type": "application/json" },
    body,
  });
  return res.json();
}

function bw_call(string $path, array $data): array {
    $body = json_encode($data, JSON_UNESCAPED_UNICODE);
    $sign = md5(base64_encode($body) . getenv('BW_API_KEY'));
    $ch = curl_init('https://blockwallets.io' . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST => true, CURLOPT_POSTFIELDS => $body, CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ['merchant: ' . getenv('BW_MERCHANT'), 'sign: ' . $sign, 'Content-Type: application/json'],
    ]);
    return json_decode(curl_exec($ch), true);
}

import base64, hashlib, json, os, requests

def bw_call(path: str, data: dict) -> dict:
    body = json.dumps(data, separators=(",", ":"), ensure_ascii=False)
    sign = hashlib.md5((base64.b64encode(body.encode()).decode() + os.environ["BW_API_KEY"]).encode()).hexdigest()
    headers = {"merchant": os.environ["BW_MERCHANT"], "sign": sign, "Content-Type": "application/json"}
    return requests.post("https://blockwallets.io" + path, data=body.encode(), headers=headers).json()

2. Membuat tagihan POST /v1/payment

Saat pelanggan memesan, atau mengisi jumlah di halaman top-up Anda, panggil https://blockwallets.io/v1/payment dan arahkan mereka ke result.url yang dikembalikan.

{
  "amount": "42.00",
  "currency": "USD",
  "order_id": "order_1042",
  "url_callback": "https://shop.example/webhooks/crypto",
  "url_return": "https://shop.example/cart",
  "url_success": "https://shop.example/thanks?order=1042"
}

{
  "state": 0,
  "result": {
    "uuid": "6f1c2a7e-…",
    "order_id": "order_1042",
    "amount": "42.00",
    "currency": "USD",
    "network": null,
    "address": null,
    "payer_amount": null,
    "payment_amount": null,
    "url": "https://blockwallets.io/pay/inv_01J8…",
    "expired_at": 1760965200,
    "status": "check",
    "is_final": false
  }
}

network, address, dan payer_amount terisi setelah pelanggan memilih jaringan.

3. Kueri tagihan

• POST /v1/payment/info {"order_id": "…"} atau {"uuid": "…"}: ambil satu tagihan dan sekalian periksa chain (paling sering sekali per 10 detik).
• POST /v1/payment/list: daftar, 15 per halaman, date_from / date_to opsional; halaman berikutnya lewat paginate.nextCursor yang dikembalikan (?cursor=…).
• POST /v1/payment/services: jaringan yang tersedia dan jumlah minimum tiap jaringan.
• POST /v1/payment/resend {"order_id": "…"}: kirim ulang webhook tagihan yang lunas / kurang bayar.

Webhook adalah kanal utama; kueri adalah cadangan (misalnya jika server Anda sedang mati dan melewatkan webhook).

4. Dompet statis POST /v1/wallet

Membuka alamat permanen untuk satu pelanggan di satu jaringan. order_id yang sama (biasanya id pengguna Anda) + jaringan selalu menghasilkan alamat yang sama; semua chain EVM (BNB Chain, Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche, X Layer) berbagi satu alamat, sedangkan TRON, BTC, LTC, DOGE, BCH, Solana, dan TON masing-masing punya alamat sendiri. Apa pun yang dikirim pelanggan dikreditkan, dengan satu webhook per transfer; transfer BTC / LTC / DOGE / BCH / TRX / BNB / ETH / POL / AVAX / OKB / SOL / TON dikonversi ke dolar AS dengan kurs saat masing-masing terlihat (payment_amount_usd).

{
  "order_id": "user_42",
  "currency": "USDT",
  "network": "tron",
  "url_callback": "https://shop.example/webhooks/crypto"
}

{
  "state": 0,
  "result": {
    "wallet_uuid": "0b9d…",
    "uuid": "5e2f…",
    "order_id": "user_42",
    "currency": "USDT",
    "network": "tron",
    "address": "TXy4…8kQ2",
    "url": "https://blockwallets.io/deposit/dac_01J8…"
  }
}

result.url adalah halaman setoran yang kami host (alamat + kode QR + setoran terbaru) yang bisa Anda berikan ke pelanggan. Transfer di bawah minimum jaringan (biasanya $1, BTC $5) tidak dikreditkan otomatis; hubungi kami agar dikreditkan. Pemblokiran alamat (/v1/wallet/block-address) belum didukung.

Webhook

Saat status tagihan berubah (paid, paid_over, wrong_amount_waiting, wrong_amount, cancel) dan untuk setiap transfer ke dompet statis, kami mengirim POST JSON ke url_callback. Respons 2xx dianggap terkirim; jika tidak, kami mencoba lagi setelah 1 menit, 5 menit, 30 menit, 2 jam, 12 jam, 24 jam, dan 24 jam. Anda juga bisa mengirim ulang dari dasbor atau dengan /v1/payment/resend.

{
  "type": "payment",
  "uuid": "6f1c2a7e-…",
  "order_id": "order_1042",
  "amount": "42.00",
  "payment_amount": "42",
  "payment_amount_usd": "42.00",
  "merchant_amount": "41.58",
  "commission": "0.42",
  "is_final": true,
  "status": "paid",
  "from": "TQ8m…",
  "wallet_address_uuid": null,
  "network": "tron",
  "currency": "USD",
  "payer_currency": "USDT",
  "payer_amount": "42",
  "payer_amount_exchange_rate": "1",
  "additional_data": null,
  "txid": "9c1e…",
  "sign": "5f0c9b…"
}

Verifikasi tanda tangan (wajib)

Tanda tangan adalah field sign di body webhook: hapus sign, encode ulang sisanya seperti json_encode PHP (ringkas, / di-escape menjadi \/, karakter non-ASCII tidak di-escape), lalu md5(base64(encoded) + API key) harus sama dengan sign. Pakai API key dari mode yang sama. Webhook yang sama bisa datang lebih dari sekali — hindari duplikat berdasarkan uuid + status.

Jika verifikasi gagal, tempel body webhook mentah ke pemeriksa tanda tangan: ia menampilkan hasil setiap langkah dan menandai di mana hasil Anda berbeda (semuanya berjalan di browser Anda; API key tidak pernah diunggah). Setiap webhook di “Developer › Log webhook” dasbor terbuka di pemeriksa dengan sekali klik.

import crypto from "node:crypto";

function verify(rawBody, apiKey) {
  const { sign, ...data } = JSON.parse(rawBody);
  const json = JSON.stringify(data).replaceAll("/", "\\/");
  const expected = crypto.createHash("md5").update(Buffer.from(json).toString("base64") + apiKey).digest("hex");
  return typeof sign === "string" && sign.length === expected.length && crypto.timingSafeEqual(Buffer.from(sign), Buffer.from(expected));
}

$data = json_decode(file_get_contents('php://input'), true);
$sign = $data['sign'] ?? '';
unset($data['sign']);
$expected = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiKey);
if (!hash_equals($expected, $sign)) {
    http_response_code(401); exit;
}

import base64, hashlib, hmac, json

def verify(raw_body: bytes, api_key: str) -> bool:
    data = json.loads(raw_body)
    sign = data.pop("sign", "")
    encoded = json.dumps(data, separators=(",", ":"), ensure_ascii=False).replace("/", "\\/")
    expected = hashlib.md5((base64.b64encode(encoded.encode()).decode() + api_key).encode()).hexdigest()
    return hmac.compare_digest(expected, sign)

Mode uji

Tagihan yang dibuat dengan merchant dan API key Test berjalan di testnet, tanpa uang sungguhan. Halaman pembayaran menampilkan tombol “Simulasikan pembayaran” (penuh / setengah / lebih), sehingga Anda bisa melihat perubahan status dan webhook tanpa perlu koin testnet.

• POST /v1/test-webhook/payment, /v1/test-webhook/wallet: kirim contoh webhook bertanda tangan ke url_callback (sertakan url_callback — wajib, di domain situs terdaftar Anda — serta currency, network, opsional status, order_id) untuk men-debug kode verifikasi Anda.
• Dasbor “Developer › Integrasi & kunci” → “Kirim notifikasi uji”: mengirim contoh ke URL webhook Anda.
• Dasbor “Developer › Log webhook”: setiap percobaan pengiriman dengan waktu, URL tujuan, status HTTP, durasi, body permintaan, dan respons server Anda (4 KB pertama); filter berdasarkan pesanan atau status dan kirim ulang dengan satu klik. Disimpan 30 hari.

Pindah dari Cryptomus

1. Dasbor “Developer › Integrasi & kunci” → buat merchant dan API key.
2. Ganti https://api.cryptomus.com di kode Anda dengan https://blockwallets.io, lalu pakai merchant dan API key yang baru.
3. Tambahkan domain Anda di “Domain situs web” (url_callback / url_return / url_success hanya menerima domain ini).

Didukung: /v1/payment, /v1/payment/info, /v1/payment/list, /v1/payment/services, /v1/payment/resend, /v1/wallet, /v1/test-webhook/payment, /v1/test-webhook/wallet. Perbedaan: tagihan hanya dihargai dalam USD / USDT / USDC (semuanya 1:1, tanpa selisih kurs); commission adalah biaya platform kami (jumlah yang diterima × tarif merchant saat tagihan dibuat — 1% standar, turun hingga 0.5% sesuai volume; tidak ada yang ditagih dua kali pada bagian yang ditanggung pelanggan) dan merchant_amount = diterima − commission; saat pelanggan membayar dengan BTC / LTC / DOGE / BCH / TRX / BNB / ETH / POL / AVAX / OKB / SOL / TON kami memberi kutipan median beberapa exchange, dikunci selama 30 menit — payer_amount adalah jumlah koin yang harus dikirim, payer_amount_exchange_rate adalah nilai USD satu koin, dan pembayaran dikonversi ke payment_amount_usd dengan kurs terkunci (koin tetap pada kami, tidak ada yang ditukar); jaringan tron / bsc / eth / base / polygon / arbitrum / optimism / avalanche / xlayer / btc / ltc / doge / bch / sol / ton; masa berlaku tagihan minimum 10 menit; tidak ada is_refresh dan tidak ada pemblokiran dompet statis; webhook default-nya datang dari IP yang berubah-ubah; jika Anda memakai allow-list IP, aktifkan “Webhook dari IP tetap” di dasbor pada “Developer › Integrasi & kunci” dan webhook hanya datang dari 18.163.145.41 — allow-list adalah lapisan tambahan, tetap verifikasi sign.

Datang dari NOWPayments atau Coinbase Commerce? Kami punya API yang kompatibel untuk keduanya — ganti base URL dan kunci; lihat panduan migrasi.

Jaringan dan jumlah

Biaya ERC-20 tinggi, jadi minimumnya $5; biaya Bitcoin juga tidak rendah, minimum $5; sisanya $1. Pelanggan harus mengirim lewat jaringan yang tertera di halaman pembayaran — dana yang dikirim lewat jaringan lain tidak dikreditkan otomatis. BTC / LTC / DOGE / BCH tampil “terdeteksi” begitu masuk mempool dan dihitung setelah cukup konfirmasi; transaksi yang diganti (RBF) atau dibuang tidak dihitung. Koin native (TRX, BNB, ETH, POL, AVAX, OKB, SOL, TON) dikutip dengan kurs terkunci dan dikreditkan dalam dolar AS seperti BTC / LTC / DOGE / BCH; tentukan jaringan dan koin: tagihan network: "bsc", to_currency: "BNB", dompet statis network: "bsc", currency: "BNB". Jaringan saja berarti USDT di chain itu (USDC di Base). Transfer yang dilakukan kontrak (multisig, pembayaran massal) juga diterima; di beberapa chain hash transaksinya tidak tersedia dan txid di webhook bernilai null.

Error

{ "state": 1, "message": "amount must be a number like 10.28" }

Saat tanda tangan salah (Invalid Sign.), respons memuat objek debug: body_base64 adalah base64 dari body permintaan yang kami terima (isi milik Anda sendiri, bukan API key) dan body_bytes panjangnya. Bandingkan dengan base64 yang Anda tandatangani: jika berbeda, body yang Anda kirim bukan string yang Anda tandatangani (framework Anda men-serialisasi ulang, proxy mengubah encoding, ada baris baru di akhir); jika sama, API key salah. Tempel ke pemeriksa tanda tangan untuk melihat perbedaan pertama.

{
  "state": 1,
  "message": "Invalid Sign.",
  "debug": {
    "body_base64": "eyJhbW91bnQiOiI0Mi4wMCIsImN1cnJlbmN5IjoiVVNEIiwi…",
    "body_bytes": 158,
    "sign_formula": "md5(body_base64 + API key)"
  }
}

Tanya jawab

Pelanggan top-up dengan jumlah bebas — pakai mode apa?

Tagihan. Biarkan pelanggan mengisi jumlah di halaman top-up Anda, buat tagihan untuk jumlah itu, lalu kreditkan payment_amount_usd saat dana masuk. Pakai dompet statis hanya jika pelanggan sebaiknya menyimpan satu alamat dan berulang kali mengirim ke sana.

Bagaimana jika pelanggan kurang bayar?

Sebelum kedaluwarsa pelanggan bisa mengirim selisihnya di halaman pembayaran (halaman menampilkan sisa yang masih harus dibayar; status wrong_amount_waiting, dan jika sisa waktu kurang dari 30 menit saat pembayaran kurang pertama, batas waktu diundur menjadi 30 menit kemudian). Jika masih kurang saat kedaluwarsa, tagihan menjadi wrong_amount dan payment_amount_usd di webhook adalah jumlah yang diterima; bisnis top-up cukup mengkreditkan jumlah itu.

Bagaimana jika pelanggan membayar terlambat, atau dua kali?

Dana yang masuk setelah kedaluwarsa tetap dikreditkan dan diberitahukan; dana yang masuk setelah tagihan lunas penuh juga dicatat dan terlihat di dasbor.

Bagaimana jika pelanggan mengirim lewat jaringan yang salah?

Misalnya tagihan di TRON dan mereka mengirim dari BNB Chain: dana tidak dikreditkan otomatis — hubungi kami dan kami tangani secara manual.

Berapa biayanya?

1% dari setiap pembayaran yang diterima, turun otomatis sesuai volume bulan lalu (0.9% mulai $50,000, 0.8% mulai $100,000, 0.7% mulai $250,000, 0.6% mulai $500,000, dan 0.5% mulai $1,000,000), tanpa biaya bulanan atau pendaftaran. Pelanggan membayar biaya jaringan saat mengirim; untuk meneruskan biaya ke pelanggan, atur subtract saat membuat tagihan atau sebagai default di dasbor. Penarikan tidak dikenai biaya tambahan. Lihat harga.

Kapan dana sampai ke saya?

Dana dikreditkan ke saldo Anda begitu pembayaran terkonfirmasi. Ajukan penarikan ke dompet Anda sendiri di “Dana › Saldo & penarikan”; setelah kami setujui, kami membayarkan, dan transaksi on-chain muncul di riwayat penarikan Anda.

Anda juga bisa mengaktifkan penarikan otomatis: saat saldo tersedia mencapai jumlah yang Anda tentukan, atau sekali sehari pukul 00:00 UTC, seluruh saldo tersedia ditarik. Penarikan otomatis ditinjau dengan cara yang sama, dan setiap perubahan pengaturan mengirim pemberitahuan ke email Anda.