API tương thích Cryptomus

blockwallets giúp bạn nhận USDT và USDC, cùng BTC, LTC, DOGE, BCH và các coin gốc (ghi có theo đô la Mỹ với tỷ giá đã chốt): khách thanh toán, chúng tôi xác nhận trên chuỗi, rồi báo cho bạn. API, chữ ký và webhook giống hệt Cryptomus — nếu bạn đã tích hợp Cryptomus, chỉ cần đổi tên miền là xong. Phần giải thích cách hoạt động đứng trước, sau đó mới đến API.

Hai cách nhận tiền

Cả hai đều nhận mọi số tiền: đơn hàng giá cố định và nạp tiền do khách tự nhập số tiền. Khi đã thanh toán, bạn giao hàng hoặc cộng vào số dư của khách. Khác biệt duy nhất là mỗi lần thanh toán có địa chỉ mới hay không.

Phân vân thì cứ dùng hóa đơn. Nếu không viết code, liên kết thanh toán trong trang quản trị chính là hóa đơn được tạo sẵn cho bạn. Chưa là người bán? Đăng ký dùng ở trang chủ; sau khi được duyệt, đăng nhập vào trang quản trị và bắt đầu bằng “Thử thanh toán” ở trang chủ của trang quản trị, trả một số tiền nhỏ trước (tiền vào chính số dư của bạn).

Một hóa đơn đi thế nào

Một khoản thanh toán có bốn bên: khách, website của bạn, blockwallets và blockchain. Sơ đồ chạy từ trên xuống theo thời gian; cột bên phải là trạng thái của hóa đơn ở từng bước.

Tóm lại, năm bước:

1. Bạn tạo hóa đơn (liên kết thanh toán làm việc này giúp bạn, hoặc máy chủ của bạn gọi /v1/payment), nhận url của trang thanh toán và chuyển hướng khách đến đó.
2. Trên trang thanh toán, khách chọn coin và mạng, nhận một địa chỉ và số tiền riêng, rồi trả từ ví hoặc sàn.
3. Chúng tôi thấy giao dịch trên chuỗi, chờ đủ số xác nhận, rồi đối chiếu với một nhà cung cấp node thứ hai (để một node không thể làm giả).
4. Hóa đơn chuyển sang paid và chúng tôi lập tức POST một webhook có chữ ký đến url_callback của bạn; vài giây sau, trang thanh toán đưa khách về url_success của bạn.
5. Tiền được ghi có vào số dư của bạn; rút về ví của bạn từ trang quản trị.

Trạng thái hóa đơn

Khi is_final là true, trạng thái sẽ không đổi nữa (trừ trường hợp thanh toán muộn).

Liên kết thanh toán (không cần code)

Trang quản trị → “Thanh toán › Liên kết thanh toán” → nhập mô tả và số tiền (cố định mạng hoặc để khách chọn) → tạo. Mỗi liên kết có một URL và một mã QR.

• Mỗi lần có người mở liên kết, một hóa đơn mới được tạo, nên một liên kết dùng lại được (ví dụ “Hội viên $99”).
• Mọi khoản thanh toán đều hiện trong “Thanh toán › Giao dịch”; rút về ví của bạn từ “Tiền › Số dư & rút tiền”.
• Nếu bạn đã tạo thông tin xác thực và URL webhook trong “Nhà phát triển › Tích hợp & khóa”, các khoản thanh toán qua liên kết cũng được thông báo theo định dạng bên dưới.
• Muốn ngừng nhận, bấm “Tắt” và liên kết ngừng hoạt động ngay lập tức.

Tích hợp API

1. Thông tin xác thực và chữ ký

Trang quản trị → “Nhà phát triển › Tích hợp & khóa” → tạo một merchant (UUID) và một API key. Có một bộ cho Live và một bộ cho Test: Live nhận tiền thật, Test chạy trên testnet. Hãy thêm cả tên miền website của bạn: url_callback, url_return và url_success phải thuộc các tên miền đó. API key chỉ hiển thị một lần — hãy cất cẩn thận và chỉ để trên máy chủ của bạn.

URL gốc https://blockwallets.io. Mọi endpoint đều là POST + JSON, kèm các header sau:

• merchant: UUID merchant của bạn (giá trị này quyết định Live hay Test)
• sign: md5(base64(request body) + API key), trong đó nội dung gửi đi là chính xác chuỗi JSON bạn gửi

Thành công trả về {"state": 0, "result": {…}}; thất bại trả về {"state": 1, "message": "…"} (xem Lỗi).

Các endpoint chính bên dưới có bảng “Thử ngay”: nhập merchant và API key của chế độ Test, trang sẽ ký yêu cầu ngay trong trình duyệt của bạn, gọi endpoint và hiển thị đầy đủ yêu cầu lẫn phản hồi (thông tin xác thực chỉ nằm trong bộ nhớ của trang). Khi chữ ký không khớp, hãy so từng bước với công cụ kiểm tra chữ ký.

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. Tạo hóa đơn POST /v1/payment

Khi khách đặt hàng, hoặc nhập số tiền trên trang nạp tiền của bạn, hãy gọi https://blockwallets.io/v1/payment rồi chuyển hướng khách đến result.url trả về.

{
  "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 và payer_amount được điền khi khách chọn mạng.

3. Truy vấn hóa đơn

• POST /v1/payment/info {"order_id": "…"} hoặc {"uuid": "…"}: lấy một hóa đơn và kiểm tra chuỗi ngay lúc đó (tối đa một lần mỗi 10 giây).
• POST /v1/payment/list: liệt kê, 15 mục mỗi trang, tùy chọn date_from / date_to; trang tiếp theo dùng paginate.nextCursor trả về (?cursor=…).
• POST /v1/payment/services: các mạng khả dụng và số tiền tối thiểu của từng mạng.
• POST /v1/payment/resend {"order_id": "…"}: gửi lại webhook của hóa đơn đã thanh toán / trả thiếu.

Webhook là kênh chính; truy vấn là phương án dự phòng (ví dụ khi máy chủ của bạn ngừng hoạt động và lỡ mất một webhook).

4. Ví tĩnh POST /v1/wallet

Mở một địa chỉ cố định cho một khách trên một mạng. Cùng một order_id (thường là id người dùng của bạn) + mạng luôn cho cùng một địa chỉ; mọi chuỗi EVM (BNB Chain, Ethereum, Base, Polygon, Arbitrum, Optimism, Avalanche, X Layer) dùng chung một địa chỉ, còn TRON, BTC, LTC, DOGE, BCH, Solana và TON mỗi mạng một địa chỉ riêng. Khách gửi bao nhiêu thì ghi có bấy nhiêu, mỗi lần chuyển một webhook; khoản chuyển BTC / LTC / DOGE / BCH / TRX / BNB / ETH / POL / AVAX / OKB / SOL / TON được quy đổi sang đô la Mỹ theo tỷ giá lúc thấy giao dịch (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 là trang nạp tiền được lưu trữ sẵn (địa chỉ + mã QR + các khoản nạp gần đây) mà bạn có thể đưa cho khách. Khoản chuyển dưới mức tối thiểu của mạng (thường là $1, BTC $5) không được ghi có tự động; hãy liên hệ để chúng tôi ghi có. Chặn địa chỉ (/v1/wallet/block-address) hiện chưa được hỗ trợ.

Webhook

Khi trạng thái hóa đơn thay đổi (paid, paid_over, wrong_amount_waiting, wrong_amount, cancel) và với mỗi khoản chuyển vào ví tĩnh, chúng tôi POST JSON đến url_callback. Phản hồi 2xx được coi là đã nhận; nếu không, chúng tôi thử lại sau 1 phút, 5 phút, 30 phút, 2 giờ, 12 giờ, 24 giờ và 24 giờ. Bạn cũng có thể gửi lại từ trang quản trị hoặc bằng /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…"
}

Xác minh chữ ký (bắt buộc)

Chữ ký là trường sign trong nội dung webhook: bỏ sign, mã hóa lại phần còn lại theo cách json_encode của PHP (gọn, không khoảng trắng, / được thoát thành \/, ký tự không phải ASCII không thoát), và md5(base64(encoded) + API key) phải bằng sign. Dùng API key của cùng chế độ. Cùng một webhook có thể đến nhiều lần — hãy loại trùng theo uuid + status.

Nếu xác minh thất bại, hãy dán nguyên nội dung webhook thô vào công cụ kiểm tra chữ ký: công cụ hiển thị kết quả từng bước và đánh dấu chỗ khác biệt của bạn (mọi thứ chạy trong trình duyệt của bạn; API key không bao giờ được tải lên). Mọi webhook trong “Nhà phát triển › Nhật ký webhook” của trang quản trị đều mở được trong công cụ này chỉ với một cú nhấp.

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)

Chế độ thử nghiệm

Hóa đơn tạo bằng merchant và API key của Test chạy trên testnet, không có tiền thật. Trang thanh toán hiển thị nút “Mô phỏng thanh toán” (đủ / một nửa / trả dư), để bạn xem trạng thái thay đổi và webhook mà không cần có coin testnet.

• POST /v1/test-webhook/payment, /v1/test-webhook/wallet: gửi một webhook mẫu có chữ ký đến url_callback (truyền url_callback — bắt buộc, thuộc tên miền website đã đăng ký — cùng currency, network, tùy chọn status, order_id) để gỡ lỗi code xác minh của bạn.
• Trang quản trị “Nhà phát triển › Tích hợp & khóa” → “Gửi thông báo thử”: gửi một thông báo mẫu đến URL webhook của bạn.
• Trang quản trị “Nhà phát triển › Nhật ký webhook”: mọi lần gửi kèm thời gian, URL đích, trạng thái HTTP, thời lượng, nội dung yêu cầu và phản hồi của máy chủ bạn (4 KB đầu); lọc theo đơn hoặc trạng thái và gửi lại chỉ với một cú nhấp. Lưu trong 30 ngày.

Chuyển từ Cryptomus

1. Trang quản trị “Nhà phát triển › Tích hợp & khóa” → tạo merchant và API key.
2. Thay https://api.cryptomus.com trong code của bạn bằng https://blockwallets.io, và dùng merchant và API key mới.
3. Thêm tên miền của bạn trong “Tên miền website” (url_callback / url_return / url_success chỉ chấp nhận các tên miền này).

Được hỗ trợ: /v1/payment, /v1/payment/info, /v1/payment/list, /v1/payment/services, /v1/payment/resend, /v1/wallet, /v1/test-webhook/payment, /v1/test-webhook/wallet. Khác biệt: hóa đơn chỉ định giá bằng USD / USDT / USDC (đều 1:1, không chênh lệch tỷ giá); commission là phí nền tảng của chúng tôi (số tiền đã nhận × mức phí của người bán lúc tạo hóa đơn — 1% tiêu chuẩn, giảm tới 0.5% theo doanh số; phần khách đã chịu không bị tính hai lần) và merchant_amount = đã nhận − commission; khi khách trả bằng BTC / LTC / DOGE / BCH / TRX / BNB / ETH / POL / AVAX / OKB / SOL / TON, chúng tôi báo giá theo trung vị của nhiều sàn, chốt trong 30 phút — payer_amount là số coin cần gửi, payer_amount_exchange_rate là giá trị USD của một coin, và khoản thanh toán được quy đổi sang payment_amount_usd theo tỷ giá đã chốt (coin vẫn nằm ở chúng tôi, không đổi sang coin khác); các mạng tron / bsc / eth / base / polygon / arbitrum / optimism / avalanche / xlayer / btc / ltc / doge / bch / sol / ton; thời hạn hóa đơn tối thiểu 10 phút; không có is_refresh và không chặn được ví tĩnh; mặc định webhook đến từ các IP thay đổi; nếu bạn dùng danh sách cho phép theo IP, hãy bật “Webhook từ IP cố định” trong trang quản trị tại “Nhà phát triển › Tích hợp & khóa” và webhook sẽ chỉ đến từ 18.163.145.41 — danh sách cho phép chỉ là một lớp bổ sung, hãy tiếp tục xác minh sign.

Đến từ NOWPayments hoặc Coinbase Commerce? Chúng tôi có API tương thích cho cả hai — chỉ cần đổi URL gốc và khóa; xem hướng dẫn chuyển đổi.

Mạng và số tiền

Phí ERC-20 cao nên mức tối thiểu là $5; phí Bitcoin cũng không thấp, tối thiểu $5; còn lại là $1. Khách phải gửi trên đúng mạng hiển thị ở trang thanh toán — tiền gửi trên mạng khác sẽ không được ghi có tự động. BTC / LTC / DOGE / BCH hiện “đã phát hiện” ngay khi vào mempool và chỉ được tính khi đủ số xác nhận; giao dịch bị thay thế (RBF) hoặc bị loại bỏ thì không được tính. Coin gốc (TRX, BNB, ETH, POL, AVAX, OKB, SOL, TON) được báo giá theo tỷ giá đã chốt và ghi có theo đô la Mỹ như BTC / LTC / DOGE / BCH; hãy chỉ rõ cả mạng và coin: hóa đơn network: "bsc", to_currency: "BNB", ví tĩnh network: "bsc", currency: "BNB". Chỉ ghi mạng thì mặc định là USDT trên chuỗi đó (USDC trên Base). Khoản chuyển do hợp đồng thông minh thực hiện (multisig, chi trả hàng loạt) cũng được nhận; trên một số chuỗi không có mã băm giao dịch của chúng, và txid trong webhook là null.

Lỗi

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

Khi chữ ký sai (Invalid Sign.), phản hồi kèm một đối tượng debug: body_base64 là base64 của nội dung yêu cầu chúng tôi nhận được (là nội dung của chính bạn, không bao giờ chứa API key) và body_bytes là độ dài của nó. Hãy so với base64 bạn đã ký: nếu khác nhau, nội dung bạn gửi không phải chuỗi bạn đã ký (framework của bạn tuần tự hóa lại, proxy đổi mã hóa, thừa ký tự xuống dòng ở cuối); nếu giống nhau thì API key sai. Dán vào công cụ kiểm tra chữ ký để thấy điểm khác biệt đầu tiên.

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

Hỏi đáp

Khách nạp số tiền tùy ý — dùng chế độ nào?

Hóa đơn. Để khách nhập số tiền trên trang nạp tiền của bạn, tạo hóa đơn cho số đó, và ghi có payment_amount_usd khi tiền đến. Chỉ dùng ví tĩnh nếu khách nên lưu một địa chỉ và chuyển vào đó nhiều lần.

Nếu khách trả thiếu thì sao?

Trước khi hết hạn, khách có thể chuyển phần chênh lệch ngay trên trang thanh toán (trang hiển thị còn thiếu bao nhiêu; trạng thái wrong_amount_waiting, và nếu lúc nhận khoản thiếu đầu tiên còn dưới 30 phút thì hạn chót được dời đến 30 phút sau đó). Nếu đến hạn vẫn thiếu, hóa đơn chuyển thành wrong_amount và payment_amount_usd trong webhook là số tiền đã nhận; dịch vụ nạp tiền có thể ghi có đúng số đó.

Nếu khách trả muộn, hoặc trả hai lần thì sao?

Tiền đến sau khi hết hạn vẫn được ghi có và thông báo; tiền đến sau khi hóa đơn đã thanh toán đủ cũng được ghi lại và xem được trong trang quản trị.

Nếu khách gửi nhầm mạng thì sao?

Ví dụ hóa đơn trên TRON mà họ gửi từ BNB Chain: khoản đó không được ghi có tự động — hãy liên hệ chúng tôi để xử lý thủ công.

Chi phí bao nhiêu?

1% trên mỗi khoản thanh toán nhận được, tự giảm theo doanh số tháng trước (0.9% từ $50,000, 0.8% từ $100,000, 0.7% từ $250,000, 0.6% từ $500,000 và 0.5% từ $1,000,000), không phí hằng tháng hay phí mở tài khoản. Khách trả phí mạng khi chuyển; muốn chuyển phí này sang khách, hãy đặt subtract khi tạo hóa đơn hoặc đặt mặc định trong trang quản trị. Rút tiền không mất thêm phí. Xem bảng giá.

Khi nào tiền về tay tôi?

Tiền được ghi có vào số dư của bạn ngay khi thanh toán được xác nhận. Hãy yêu cầu rút về ví của bạn trong “Tiền › Số dư & rút tiền”; khi chúng tôi duyệt thì chi trả, và giao dịch trên chuỗi sẽ hiện trong lịch sử rút tiền của bạn.

Bạn cũng có thể bật rút tự động: khi số dư khả dụng đạt mức bạn đặt, hoặc mỗi ngày một lần lúc 00:00 UTC, toàn bộ số dư khả dụng sẽ được rút. Rút tự động cũng được kiểm duyệt như vậy, và mỗi lần đổi cài đặt đều có thông báo gửi đến email của bạn.