REST API gốc

API gốc là giao diện REST riêng của blockwallets: hóa đơn tính bằng cent Mỹ, một ref idempotent cho mỗi đơn hàng, tài khoản nạp tiền tĩnh bao phủ mọi mạng, và webhook ký bằng HMAC-SHA256. Nó tạo cùng loại hóa đơn trên cùng trang thanh toán như API tương thích Cryptomus, với cùng phí và số dư.

Bạn tự tạo khóa trong trang quản trị tại “Nhà phát triển › Tích hợp & khóa”: một khóa Live và một khóa Test cùng webhook signing secret của chúng. Mỗi khóa chỉ hiển thị một lần; danh sách chỉ hiện tiền tố. Nếu tài khoản bật xác minh hai bước, việc tạo hoặc xoay khóa Live sẽ yêu cầu nhập mã. Chưa có tài khoản người bán? Đăng ký dùng. Đã dùng Cryptomus? Xem API tương thích Cryptomus (cách chọn).

Khóa và yêu cầu

URL gốc https://blockwallets.io. Yêu cầu và phản hồi đều là JSON. Mọi yêu cầu đều mang:

• Authorization: Bearer bw_live_… hoặc Bearer bw_test_…: tiền tố quyết định chế độ, nên khóa Test chỉ thấy hóa đơn Test và chạy trên testnet
• Content-Type: application/json với các yêu cầu POST
• Chỉ giữ khóa trên máy chủ của bạn, không bao giờ đặt trong trang web hay ứng dụng; chúng tôi chỉ lưu giá trị băm của khóa

Lỗi trả về mã HTTP và {"error": {"code": "…", "message": "…"}}: 400 invalid_request (thiếu hoặc sai định dạng một trường), 401 unauthorized (khóa thiếu, không tồn tại hoặc đã bị tắt), 404 not_found, 409 conflict (yêu cầu xung đột với trạng thái hiện tại của hóa đơn), 422 currency_unsupported.

Endpoint

Thêm ?probe=1 vào lệnh tra cứu hóa đơn hoặc tài khoản nạp tiền để kiểm tra chuỗi ngay lúc đó (tối đa 10 giây một lần); nếu không, bạn nhận trạng thái mới nhất từ trình quét của chúng tôi, quét mỗi phút một lần.

Tạo hóa đơn POST /v1/invoices

Gọi POST /v1/invoices khi khách thanh toán và chuyển hướng họ đến pay_url trong phản hồi.

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}}'

Mọi URL phải thuộc một trong các tên miền website của bạn (trang quản trị → “Nhà phát triển › Tích hợp & khóa”). Phản hồi là đối tượng hóa đơn bên dưới; network, address và pay_amount được điền khi đã chọn mạng.

Đối tượng hóa đơn

Id bắt đầu bằng inv_. amount tính bằng cent Mỹ; pay_amount và paid_amount là số lượng coin dạng chuỗi thập phân trên mạng đã chọn.

{
  "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
}

Các trường khác: pay_url (trang thanh toán), payments (mọi khoản chuyển cùng txid, amount, confirmations và confirmed), expires_at, paid_at, closed_at; BTC, LTC, DOGE, BCH và các coin gốc còn có rate (đô la Mỹ trên mỗi coin, chốt trong 30 phút), rate_locked_until và paid_cents (phần đã đến, tính bằng cent Mỹ).

Mạng

Truyền id vào network. GET /v1/networks trả về các mạng đang mở ngay lúc này trong chế độ của bạn; một mạng có thể bị tạm dừng, nên hãy đọc từ đó thay vì mã hóa cứng.

Tài khoản nạp tiền (địa chỉ tĩnh) POST /v1/deposit-accounts

POST /v1/deposit-accounts với {"customer_ref": "user_42"} cấp cho khách đó một địa chỉ cố định trên mọi mạng (tất cả chuỗi EVM dùng chung một địa chỉ). Mọi khoản họ gửi đều được ghi có theo đô la Mỹ, mỗi lần chuyển có một webhook deposit.credited.

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 ký tự gồm chữ cái, chữ số và _ . : @ -; cùng một giá trị luôn trả về cùng một tài khoản. return_url tùy chọn thuộc các tên miền của bạn
• Phản hồi có deposit_url (trang lưu trữ sẵn với các địa chỉ, mã QR và các khoản nạp gần đây) và networks (mỗi mạng có id, address, min_amount, confirmations)
• Id khoản nạp bắt đầu bằng dep_; amount tính bằng cent Mỹ, amount_token là số lượng coin, và coin có giá kèm rate đã dùng

Các khoản chuyển dưới mức tối thiểu (thường là $1, BTC $5) được ghi nhận là below_min và không được ghi có tự động; hãy liên hệ để chúng tôi ghi có.

Webhook

Chúng tôi POST JSON đến URL webhook trong trang quản trị (“Nhà phát triển › Tích hợp & khóa”; Live và Test mỗi bên có URL và secret riêng). Nội dung là sự kiện:

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>, trong đó v1 = HMAC-SHA256(webhook secret của chế độ đó, t + . + nội dung thô)
• X-BW-Event: id sự kiện (ev_…); hãy loại trùng theo nó
• X-BW-Delivery: số lần gửi, bắt đầu từ 1

Hãy xác minh trên nội dung thô trước khi phân tích, từ chối t lệch quá 300 giây so với đồng hồ của bạn, và so sánh trong thời gian không đổi. invoice / deposit trong nội dung là cùng đối tượng mà một lệnh tra cứu trả về.

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));
}

Phản hồi 2xx được tính là đã gửi; 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ờ (tổng cộng 8 lần).

Events và gửi lại

GET /v1/events?invoice_id=inv_… (hoặc deposit_id=dep_…) liệt kê các webhook của một hóa đơn hoặc khoản nạp cùng state, attempts, last_status và last_error. POST /v1/events/ev_…/redeliver xếp hàng gửi lại ngay, ví dụ sau khi bạn đã sửa endpoint. “Nhà phát triển › Nhật ký webhook” trong trang quản trị hiển thị mọi lần thử kèm yêu cầu và phản hồi.

Chế độ thử nghiệm

Hóa đơn tạo bằng khóa bw_test_ chạy trên testnet và không bao giờ động đến 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 và webhook mà không cần có coin testnet.