REST API ของเรา

API ของเราคืออินเทอร์เฟซ REST ของ blockwallets เอง: ใบแจ้งหนี้กำหนดราคาเป็นเซนต์สหรัฐ ref แบบ idempotent ต่อหนึ่งคำสั่งซื้อ บัญชีฝากเงินคงที่ครอบคลุมทุกเครือข่าย และ Webhook ที่เซ็นด้วย HMAC-SHA256 สร้างใบแจ้งหนี้แบบเดียวกันบนหน้าชำระเงินเดียวกันกับAPI ที่เข้ากันได้กับ Cryptomus ด้วยค่าธรรมเนียมและยอดคงเหลือเหมือนกัน

สร้างคีย์เองได้ในแดชบอร์ดที่ “นักพัฒนา › การเชื่อมต่อและคีย์”: คีย์ Live และ Test อย่างละหนึ่งชุดพร้อม webhook signing secret ของคีย์เหล่านั้น แต่ละรายการแสดงเพียงครั้งเดียว ในรายการจะเห็นเฉพาะคำนำหน้า หากบัญชีเปิดการยืนยันสองขั้นตอน การสร้างหรือเปลี่ยนคีย์ Live จะต้องกรอกรหัส ยังไม่มีบัญชีร้านค้า? ขอใช้งาน ใช้ Cryptomus อยู่แล้ว? ดู API ที่เข้ากันได้กับ Cryptomus (วิธีเลือก)

คีย์และคำขอ

Base URL https://blockwallets.io คำขอและการตอบกลับเป็น JSON ทุกคำขอมี:

• Authorization: Bearer bw_live_… หรือ Bearer bw_test_…: คำนำหน้ากำหนดโหมด คีย์ Test จึงเห็นเฉพาะใบแจ้งหนี้ Test และรันบนเทสต์เน็ต
• Content-Type: application/json ในคำขอ POST
• เก็บคีย์ไว้ที่เซิร์ฟเวอร์ของคุณเท่านั้น ห้ามใส่ในหน้าเว็บหรือแอป เราเก็บเฉพาะค่าแฮชของคีย์

ข้อผิดพลาดตอบกลับเป็นสถานะ HTTP และ {"error": {"code": "…", "message": "…"}}: 400 invalid_request (ฟิลด์หายไปหรือรูปแบบผิด), 401 unauthorized (ไม่มีคีย์ ไม่รู้จักคีย์ หรือคีย์ถูกปิด), 404 not_found, 409 conflict (คำขอขัดกับสถานะปัจจุบันของใบแจ้งหนี้), 422 currency_unsupported

Endpoint

เพิ่ม ?probe=1 ที่การค้นหาใบแจ้งหนี้หรือบัญชีฝากเงินเพื่อตรวจเชนระหว่างทาง (อย่างมากทุก 10 วินาที) มิฉะนั้นคุณจะได้สถานะล่าสุดจากตัวสแกนของเรา ซึ่งตรวจทุกนาที

สร้างใบแจ้งหนี้ POST /v1/invoices

เรียก POST /v1/invoices เมื่อลูกค้าชำระเงิน แล้วส่งลูกค้าไปที่ pay_url ในการตอบกลับ

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

ทุก URL ต้องอยู่ในโดเมนเว็บไซต์ของคุณโดเมนใดโดเมนหนึ่ง (แดชบอร์ด → “นักพัฒนา › การเชื่อมต่อและคีย์”) การตอบกลับคืออ็อบเจกต์ใบแจ้งหนี้ด้านล่าง network, address และ pay_amount จะถูกเติมเมื่อเลือกเครือข่ายแล้ว

อ็อบเจกต์ใบแจ้งหนี้

id ขึ้นต้นด้วย inv_ amount เป็นเซนต์สหรัฐ ส่วน pay_amount และ paid_amount เป็นจำนวนเหรียญแบบสตริงทศนิยมบนเครือข่ายที่เลือก

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

ฟิลด์อื่น ๆ: pay_url (หน้าชำระเงิน), payments (ทุกการโอนพร้อม txid, amount, confirmations และ confirmed), expires_at, paid_at, closed_at ส่วน BTC, LTC, DOGE, BCH และเหรียญประจำเครือข่ายมี rate (ดอลลาร์สหรัฐต่อเหรียญ ล็อก 30 นาที), rate_locked_until และ paid_cents (ยอดที่เข้ามาแล้วเป็นเซนต์สหรัฐ) ด้วย

เครือข่าย

ส่ง id เป็น network GET /v1/networks คืนเครือข่ายที่เปิดอยู่ในขณะนี้ตามโหมดของคุณ เครือข่ายอาจถูกพัก จึงควรอ่านจากที่นี่แทนการฝังค่าไว้ในโค้ด

บัญชีฝากเงิน (ที่อยู่คงที่) POST /v1/deposit-accounts

POST /v1/deposit-accounts พร้อม {"customer_ref": "user_42"} ให้ลูกค้ารายนั้นมีที่อยู่ถาวรบนทุกเครือข่าย (เชน EVM ทั้งหมดใช้ที่อยู่เดียวกัน) สิ่งที่ลูกค้าส่งมาจะถูกบันทึกเป็นดอลลาร์สหรัฐ พร้อม 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 ตัวอักษร เป็นตัวอักษร ตัวเลข และ _ . : @ - ค่าเดิมได้บัญชีเดิมเสมอ return_url ไม่บังคับ ต้องอยู่ในโดเมนของคุณ
• การตอบกลับมี deposit_url (หน้าที่เราโฮสต์ แสดงที่อยู่ คิวอาร์โค้ด และรายการฝากล่าสุด) และ networks (แต่ละเครือข่ายมี id, address, min_amount, confirmations)
• id รายการฝากขึ้นต้นด้วย dep_ amount เป็นเซนต์สหรัฐ amount_token คือจำนวนเหรียญ และเหรียญที่มีราคาจะมี rate ที่ใช้มาด้วย

การโอนที่ต่ำกว่าขั้นต่ำ (ปกติ $1, BTC $5) จะถูกบันทึกเป็น below_min และไม่ถูกบันทึกยอดให้อัตโนมัติ ติดต่อเราเพื่อให้บันทึกยอดให้

Webhook

เรา POST JSON ไปที่ URL webhook ในแดชบอร์ด (“นักพัฒนา › การเชื่อมต่อและคีย์” Live และ Test มี URL และ secret ของตัวเอง) เนื้อหาคืออีเวนต์:

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> โดย v1 = HMAC-SHA256(webhook secret ของโหมดนั้น, t + . + เนื้อหาดิบ)
• X-BW-Event: id ของอีเวนต์ (ev_…) ใช้ตัดรายการซ้ำ
• X-BW-Delivery: ครั้งที่ส่ง เริ่มที่ 1

ตรวจกับเนื้อหาดิบก่อนแยกวิเคราะห์ ปฏิเสธ t ที่ห่างจากนาฬิกาของคุณเกิน 300 วินาที และเปรียบเทียบด้วยเวลาคงที่ invoice / deposit ในเนื้อหาเป็นอ็อบเจกต์เดียวกับที่การค้นหาคืนมา

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

การตอบ 2xx นับว่าส่งถึงแล้ว มิฉะนั้นเราลองใหม่หลัง 1 นาที, 5 นาที, 30 นาที, 2 ชั่วโมง, 12 ชั่วโมง, 24 ชั่วโมง และ 24 ชั่วโมง (รวม 8 ครั้ง)

Events และการส่งซ้ำ

GET /v1/events?invoice_id=inv_… (หรือ deposit_id=dep_…) แสดงรายการ webhook ของใบแจ้งหนี้หรือรายการฝากหนึ่งรายการ พร้อม state, attempts, last_status และ last_error POST /v1/events/ev_…/redeliver จัดคิวส่งอีกครั้งทันที เช่นหลังจากคุณแก้ endpoint แล้ว “นักพัฒนา › บันทึก Webhook” ในแดชบอร์ดแสดงทุกครั้งที่ลองส่ง พร้อมคำขอและการตอบกลับ

โหมดทดสอบ

ใบแจ้งหนี้ที่สร้างด้วยคีย์ bw_test_ รันบนเทสต์เน็ตและไม่แตะเงินจริง หน้าชำระเงินแสดงปุ่ม “จำลองการชำระเงิน” (เต็มจำนวน / ครึ่งหนึ่ง / จ่ายเกิน) คุณจึงดูสถานะและ webhook ได้โดยไม่ต้องมีเหรียญเทสต์เน็ต