# Tài liệu blockwallets: các cách tích hợp

> Chọn cách tích hợp: liên kết thanh toán, POS và nút nhúng không cần code; API tương thích Cryptomus hoặc REST API gốc; API tương thích Cryptomus, NOWPayments và Coinbase Commerce; prompt AI, AGENTS.md và MCP.
>
> HTML: https://blockwallets.io/docs?lang=vi · English: https://blockwallets.io/docs.md?lang=en

## Tài liệu

blockwallets giúp bạn nhận USDT và USDC, cùng BTC, LTC và các coin gốc (ghi có theo đô la Mỹ với tỷ giá đã chốt). Mọi cách tích hợp bên dưới đều tạo cùng một loại hóa đơn trên cùng một trang thanh toán, với cùng số xác nhận, phí và số dư; chúng chỉ khác nhau ở cách hệ thống của bạn giao tiếp với chúng tôi. Hãy chọn cách phù hợp rồi làm theo trang hướng dẫn của nó.

### Chọn cách tích hợp

Được nhóm theo điểm xuất phát của bạn. Mỗi thẻ mở ra hướng dẫn đầy đủ.

#### Không cần code

Nhận tiền từ trang quản trị người bán; không cần cài gì.

- [Liên kết thanh toán](https://blockwallets.io/docs?lang=vi#links): Nhập số tiền (hoặc để người trả tự nhập) rồi chia sẻ liên kết hoặc mã QR. Mỗi lượt truy cập tạo một hóa đơn mới.

- [POS cho cửa hàng](https://blockwallets.io/docs?lang=vi#pos): Nhân viên mở liên kết POS trên điện thoại hoặc máy tính bảng, nhập số tiền và khách quét mã QR.

- [Nút nhúng](https://blockwallets.io/docs?lang=vi#embed): Dán nút “Thanh toán” hoặc “Ủng hộ” vào bất kỳ website nào: HTML thuần, hoặc HTML kèm một thẻ script.

#### Tích hợp API mới

Bạn tự viết phần tích hợp từ đầu.

- [REST API gốc](https://blockwallets.io/docs/api?lang=vi): Khóa Bearer, số tiền tính bằng cent, `ref` idempotent, webhook HMAC-SHA256 và events API. Khóa tự tạo trong trang quản trị.

- [API tương thích Cryptomus](https://blockwallets.io/docs/cryptomus?lang=vi): POST + JSON với chữ ký md5. Thông tin xác thực tự tạo trong trang quản trị, mọi endpoint chính đều có bảng “Thử ngay”.

#### Chuyển từ cổng thanh toán khác

Giữ nguyên code: API tương thích, bạn chỉ đổi URL gốc và khóa.

- [Từ Cryptomus](https://blockwallets.io/docs/cryptomus?lang=vi#cryptomus): Đổi `https://api.cryptomus.com` thành `https://blockwallets.io` và dùng merchant cùng API key mới. Đường dẫn, tham số, `sign` và webhook giữ nguyên.

- [Từ NOWPayments](https://blockwallets.io/docs/nowpayments?lang=vi): Đổi `https://api.nowpayments.io/v1` thành `https://blockwallets.io/nowpayments/v1` và dùng API key cùng IPN secret mới. `x-nowpayments-sig` giữ nguyên.

- [Từ Coinbase Commerce](https://blockwallets.io/docs/coinbase-commerce?lang=vi): Truyền `https://blockwallets.io/coinbase/` làm URL gốc của SDK và dùng API key cùng webhook shared secret mới. `X-CC-Webhook-Signature` giữ nguyên.

#### Để AI tích hợp giúp

Dành cho người không viết code nhưng dùng công cụ lập trình AI.

- [Trình tạo prompt](https://blockwallets.io/docs/ai?lang=vi): Chọn website, kiểu thanh toán và công cụ AI; sao chép prompt được tạo cho Claude Code, Codex, Cursor hoặc ChatGPT.

- [AGENTS.md](https://blockwallets.io/agents.md): Quy tắc tích hợp, các lỗi thường gặp và danh sách nghiệm thu; lưu vào thư mục gốc dự án cho các coding agent.

- [MCP server](https://blockwallets.io/docs/mcp?lang=vi): Cho công cụ AI tra cứu các tài liệu này và tạo hóa đơn thử trực tiếp.

#### Công cụ

Hỗ trợ gỡ lỗi chạy ngay trong trình duyệt của bạn.

- [Kiểm tra chữ ký](https://blockwallets.io/docs/sign?lang=vi): Dán nội dung yêu cầu hoặc webhook để xem từng bước ký và chỗ chữ ký của bạn khác. API key không bao giờ rời khỏi trình duyệt của bạn.

### Tương thích Cryptomus hay API gốc?

Cả hai đều tạo cùng một loại hóa đơn trên cùng trang thanh toán, với cùng phí và số dư. Khác biệt nằm ở kiểu yêu cầu, định dạng webhook và cách bạn nhận thông tin xác thực.

|  | Tương thích Cryptomus | REST gốc |
| --- | --- | --- |
| Thông tin xác thực | Tự tạo trong trang quản trị tại “Nhà phát triển › Tích hợp & khóa” (một bộ cho Live, một bộ cho Test) | Cũng tự tạo 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 (`bw_live_…` / `bw_test_…`) cùng webhook signing secret của chúng |
| Yêu cầu | Mọi lệnh gọi đều là `POST` + JSON, với header `merchant` và `sign` = `md5(base64(nội dung yêu cầu) + API key)` | REST (`GET` / `POST`) với `Authorization: Bearer`; tiền tố của khóa quyết định Live hay Test |
| Số tiền | Chuỗi thập phân như `"42.00"`, tính bằng USD, USDT hoặc USDC (đều quy đổi 1:1) | Số nguyên tính bằng cent Mỹ, như `4200`; chỉ USD |
| Gửi lại | Cùng `order_id` trả về hóa đơn đã có | Cùng `ref` với cùng tham số trả về hóa đơn đã có; tham số khác thì trả về 409 |
| Webhook | Gửi đến `url_callback` của từng hóa đơn; chữ ký là trường `sign` trong nội dung | Gửi đến URL webhook đặt trong trang quản trị; `X-BW-Signature` = HMAC-SHA256 kèm dấu thời gian; xem danh sách và gửi lại qua `/v1/events` |
| Địa chỉ tĩnh | `/v1/wallet`: mỗi lần gọi một mạng | `/v1/deposit-accounts`: tất cả mạng cùng lúc cho một khách |
| Công cụ | Bảng “Thử ngay”, kiểm tra chữ ký, prompt AI và MCP server; các SDK và plugin Cryptomus hiện có đều dùng được | Tài liệu tham khảo này và các mẫu code đi kèm |

Mới bắt đầu? Hãy dùng REST API gốc: số tiền tính bằng cent, `ref` idempotent, chữ ký webhook có dấu thời gian, và khóa bạn tự tạo trong trang quản trị. Đã dùng Cryptomus, hoặc muốn dùng SDK hay plugin Cryptomus có sẵn? Hãy dùng API tương thích Cryptomus.

### Bắt đầu nhanh

Từ con số không đến một khoản thanh toán thử trong năm bước (API tương thích Cryptomus; các API khác làm theo cùng các bước với thông tin xác thực riêng).

- Đăng ký dùng ở [trang chủ](https://blockwallets.io/?lang=vi#join). Sau khi được duyệt, đăng nhập vào [trang quản trị người bán](https://blockwallets.io/dashboard).

- Mở “Nhà phát triển › Tích hợp & khóa” trong trang quản trị, tạo merchant và API key ở cột Test rồi thêm các tên miền website của bạn.

- Máy chủ của bạn tạo hóa đơn bằng `POST /v1/payment` và chuyển hướng khách đến `result.url`.

- Thanh toán bằng “Mô phỏng thanh toán” trên trang thanh toán, rồi kiểm tra trình xử lý webhook của bạn xác minh `sign` và ghi có theo `payment_amount_usd`.

- Chuyển sang thông tin xác thực ở cột Live và trả thử một khoản nhỏ thật một lần (“Thử thanh toán” ở trang chủ của trang quản trị).

```http
POST https://blockwallets.io/v1/payment
merchant: <merchant>
sign: md5(base64(body) + API key)
Content-Type: application/json

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

Code Node.js, PHP và Python cho từng bước có trong tài liệu [API tương thích Cryptomus](https://blockwallets.io/docs/cryptomus?lang=vi#api); nếu muốn nhờ AI làm, hãy bắt đầu với [trình tạo prompt](https://blockwallets.io/docs/ai?lang=vi).

### 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 tại “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 webhook tương thích Cryptomus](https://blockwallets.io/docs/cryptomus?lang=vi#webhooks).

- 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.

### POS cho cửa hàng

Dành cho quầy và gian hàng: trang quản trị người bán → “Thanh toán › Thu ngân POS” → mở một thiết bị đầu cuối và lấy liên kết POS. Nhân viên mở nó trên điện thoại hoặc máy tính bảng, nhập số tiền và mã QR thanh toán sẽ hiện ra; khi khách thanh toán, màn hình hiển thị “Paid”.

- Hóa đơn POS có hiệu lực 30 phút. Tiền vào số dư của bạn và hiện trong “Thanh toán › Giao dịch”, đồng thời bạn được thông báo tại URL webhook giống như liên kết thanh toán.

- Liên kết POS chỉ nhận được thanh toán: nó không xem được số dư, các lệnh rút, đơn hàng khác, cài đặt hay thông tin xác thực của bạn.

- Mất thiết bị, hoặc nhân viên đã nghỉ? Hãy thu hồi thiết bị đầu cuối đó trong trang quản trị và liên kết của nó ngừng hoạt động ngay lập tức.

### Nút nhúng

Trang quản trị người bán → “Thanh toán › Liên kết thanh toán” → “Nút nhúng”: chọn chữ, màu, kích thước và hình dạng rồi sao chép đoạn mã. Nhấp vào nút sẽ mở trang thanh toán của liên kết thanh toán đó.

- HTML thuần: một liên kết đã tạo kiểu, không có script, nên dùng được ở bất cứ đâu cho phép dán HTML (trình tạo website, diễn đàn, chữ ký email).

- Kèm script: thêm `data-blockwallets` và một thẻ `/embed.js`; trên máy tính, trang thanh toán mở trong một cửa sổ nhỏ ở giữa màn hình, trên điện thoại thì mở bình thường.

- Script không gửi yêu cầu nào, không đặt cookie và không thêm iframe. Nếu trang chặn nó, nút vẫn là một liên kết bình thường và vẫn hoạt động.

Trong các đoạn mã bên dưới, hãy thay `/l/pl_…` bằng địa chỉ liên kết thanh toán của chính bạn.

#### HTML thuần

```html
<a href="https://blockwallets.io/l/pl_…" target="_blank" rel="noopener nofollow"
   style="display:inline-flex;align-items:center;height:44px;padding:0 22px;border-radius:999px;background:#1f5a3d;color:#ffffff;font:600 16px/1 sans-serif;text-decoration:none">Pay with crypto</a>
```

#### HTML + script

```html
<a href="https://blockwallets.io/l/pl_…" target="_blank" rel="noopener nofollow"
   data-blockwallets data-color="green" data-size="m" data-shape="pill">Pay with crypto</a>
<script src="https://blockwallets.io/embed.js" async></script>
```