# Tích hợp bằng AI · blockwallets

> Thêm thanh toán tiền mã hóa blockwallets mà không phải tự viết code: chọn website và công cụ AI của bạn, sao chép prompt được tạo vào Claude Code, Codex, Cursor hoặc ChatGPT, và nó tích hợp theo tài liệu rồi tự kiểm tra kết quả.
>
> HTML: https://blockwallets.io/docs/ai?lang=vi · English: https://blockwallets.io/docs/ai.md?lang=en

## Prompt chung

```text
Hãy giúp tôi nhận thanh toán tiền mã hóa trên website bằng blockwallets (khách trả bằng USDT, USDC, BTC và nhiều coin khác; tôi được ghi có theo đô la Mỹ).

1. Đọc tài liệu trước thay vì đoán API: https://blockwallets.io/llms-full.txt (tài liệu đầy đủ) và https://blockwallets.io/agents.md (quy tắc tích hợp, lỗi thường gặp, danh sách nghiệm thu). Hãy báo cho tôi nếu bạn không mở được.
2. Xem dự án của tôi, cho tôi biết nó được xây bằng gì và bạn dự định tích hợp thế nào, rồi chờ tôi đồng ý.
3. Mặc định là “tạo hóa đơn và chuyển đến trang thanh toán + webhook”. Luôn xác minh chữ ký webhook, và loại trùng webhook vì cùng một webhook có thể đến hai lần.
4. Để merchant ID và API key trong biến môi trường, và làm cho nó chạy được trước bằng thông tin xác thực Test trên testnet.
5. Khi xong, hãy đi qua từng mục trong danh sách nghiệm thu ở agents.md và báo từng kết quả cho tôi.

Tôi không phải lập trình viên: ở mỗi bước, hãy cho tôi biết bạn đã sửa gì và tôi cần làm gì.
```

## Cho chúng tôi biết về website của bạn.

Chưa chắc? Chọn “Khác / chưa chắc” và AI sẽ xem dự án của bạn trước.

- Website của bạn được xây bằng gì: WordPress / WooCommerce · PHP · Node.js / Next.js · Python · Go · Java · Khác / chưa chắc
- Bạn muốn nhận tiền thế nào:
  - Chuyển đến trang thanh toán: Tạo hóa đơn khi thanh toán, chúng tôi báo cho máy chủ của bạn khi đã trả. Đơn hàng tự giao.
  - Mỗi người dùng một địa chỉ nạp cố định: Mỗi người dùng có một địa chỉ cố định và nạp bất kỳ số tiền nào, bất cứ lúc nào.
  - Liên kết thanh toán (không cần code): Tạo liên kết trong trang quản trị rồi chia sẻ. AI chỉ thêm một nút.

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 số tiền → tạo, rồi chia sẻ liên kết. AI chỉ đặt một nút lên website của bạn.

## Bạn dùng AI nào?

- **Claude Code / Codex**: AI sửa code và chạy lệnh giúp bạn. Dễ nhất.
  - Mở terminal trong thư mục dự án website của bạn và lưu các quy tắc tích hợp thành AGENTS.md:
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Codex tự đọc AGENTS.md. Với Claude Code, hãy chạy thêm:
  - `echo '@AGENTS.md' >> CLAUDE.md`
  - Sau đó dán prompt ở bước 3.
  - Bạn cũng có thể cài MCP server của blockwallets để AI tra cứu tài liệu và tạo hóa đơn thử trực tiếp. https://blockwallets.io/docs/mcp?lang=vi
- **Cursor / Windsurf / Copilot**: AI ngay trong trình soạn code.
  - Cũng đặt AGENTS.md ở thư mục gốc dự án (Cursor tự nhận):
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Chuyển sang chế độ Agent và dán prompt.
  - Bạn cũng có thể cài MCP server của blockwallets để AI tra cứu tài liệu và tạo hóa đơn thử trực tiếp. https://blockwallets.io/docs/mcp?lang=vi
- **ChatGPT / Claude (web)**: Chỉ trò chuyện. Bạn tự dán code vào website.
  - Dán prompt vào một cuộc trò chuyện mới, hoặc dùng “Mở trong ChatGPT / Claude” bên dưới.
  - Nếu nó nói không mở được liên kết, hãy mở https://blockwallets.io/llms-full.txt, chọn tất cả, sao chép và dán thêm vào.
  - Nó sẽ đưa bạn code hoàn chỉnh và chỗ để code; làm theo từng bước. Một công cụ sửa code giúp bạn (Claude Code, Codex, Cursor) đỡ phải sao chép dán rất nhiều.
- **AI khác**: Gemini, Copilot chat và các AI khác.
  - Dán prompt. Nếu nó không mở được trang web, hãy dán thêm nội dung của llms-full.txt.

## Sao chép prompt.

Nó cập nhật theo lựa chọn của bạn ở trên và kèm liên kết tài liệu, các lỗi thường gặp và danh sách nghiệm thu.

Ví dụ: Khác / chưa chắc + chuyển đến trang thanh toán + Claude Code / Codex

```text
Bạn là lập trình viên của tôi. Hãy giúp tôi nhận thanh toán tiền mã hóa trên website bằng blockwallets (khách trả bằng USDT, USDC, BTC và 14 coin khác; tôi được ghi có theo đô la Mỹ).

## Về tôi
- Website của tôi được xây bằng: Tôi không chắc. Hãy xem dự án của tôi trước, cho tôi biết nó được xây bằng gì, rồi hãy bắt đầu.
- Cách tôi muốn nhận tiền: Tạo hóa đơn khi khách thanh toán và chuyển khách đến trang thanh toán của blockwallets; khi tiền đến, blockwallets gọi máy chủ của tôi và tôi đánh dấu đơn hàng đã thanh toán rồi giao hàng.
- Tôi không phải lập trình viên. Ở mỗi bước, hãy cho tôi biết bạn đã sửa những tệp nào và tôi cần làm gì (ví dụ để biến môi trường ở đâu). Đừng thay đổi quá nhiều cùng lúc.
- AGENTS.md ở thư mục gốc dự án chứa các quy tắc tích hợp blockwallets; hãy đọc nó trước, và đọc https://blockwallets.io/llms-full.txt để biết chi tiết.

## Đọc tài liệu trước; đừng đoán API theo trí nhớ
- Tài liệu tích hợp đầy đủ (Markdown): https://blockwallets.io/llms-full.txt
- Quy tắc tích hợp và các lỗi thường gặp: https://blockwallets.io/agents.md
- Nếu website đã dùng Cryptomus, NOWPayments hoặc Coinbase Commerce, hãy chuyển sang API tương thích tương ứng thay vì viết lại: https://blockwallets.io/docs/migrate.md?lang=en
- Nếu bạn không mở được liên kết, hãy nói với tôi và tôi sẽ dán nội dung.

## Các điểm chính (nơi tích hợp thường sai)
1. Mọi endpoint đều là POST + JSON trên https://blockwallets.io. Header: merchant = UUID của merchant, sign = md5(base64(nội dung yêu cầu) + API key). Hãy ký đúng chuỗi JSON bạn gửi; không tuần tự hóa lại sau khi ký.
2. Tạo hóa đơn bằng POST /v1/payment. Bắt buộc: amount (chuỗi có tối đa hai chữ số thập phân, ví dụ "42.00"), currency ("USD"), order_id (mã đơn hàng của tôi: chữ cái, chữ số, - và _, tối đa 100 ký tự). Truyền thêm url_callback (URL webhook) và url_success (nơi khách quay lại sau khi trả). Chuyển hướng khách đến result.url.
3. Gọi lại với cùng order_id sẽ trả về cùng một hóa đơn, nên gửi lại là an toàn và không bao giờ tạo hóa đơn thứ hai.
4. Phải xác minh chữ ký webhook: phân tích JSON của webhook, bỏ trường sign, mã hóa lại phần còn lại theo cách PHP json_encode làm (gọn, giữ nguyên ký tự không phải ASCII, / được thoát thành \/), rồi md5(base64(đã mã hóa) + API key) phải bằng sign. Quên thoát / là lỗi phổ biến nhất.
5. Chỉ đánh dấu đơn đã thanh toán khi status là paid hoặc paid_over, và dùng payment_amount_usd. Cùng một webhook có thể đến nhiều lần: loại trùng theo uuid + status. Sau khi xử lý xong, hãy trả về mã trạng thái 2xx.
6. Để merchant ID và API key trong biến môi trường (ví dụ BW_MERCHANT, BW_API_KEY); không bao giờ viết cứng trong code hay commit chúng. Hãy thêm tên miền của URL webhook vào “Tên miền website” ở trang “Nhà phát triển › Tích hợp & khóa” của trang quản trị trước.
7. Hãy làm cho mọi thứ chạy được bằng thông tin xác thực Test trước (testnet, không có tiền thật); chỉ chuyển sang Live sau khi tôi xác nhận.

## Khi xong, hãy kiểm tra từng mục và báo kết quả cho tôi
- [ ] Tạo một hóa đơn thử bằng thông tin xác thực Test và lấy liên kết trang thanh toán (result.url)
- [ ] Mở trang thanh toán và bấm “Mô phỏng thanh toán” → đủ số tiền
- [ ] Máy chủ của tôi nhận được webhook với status paid và chữ ký xác minh đúng
- [ ] Đơn hàng tương ứng được đánh dấu đã thanh toán
- [ ] Cùng webhook đó đến lần nữa (gửi lại từ “Nhà phát triển › Nhật ký webhook” của trang quản trị, hoặc POST /v1/payment/resend) không giao hàng hai lần

Nếu mục nào không đạt, hãy cho tôi biết nó vướng ở đâu và thông báo lỗi chính xác trước khi sửa thêm bất cứ thứ gì.
```

### Khi AI xong, hãy kiểm tra các mục này

**Chuyển đến trang thanh toán**

1. Tạo một hóa đơn thử bằng thông tin xác thực Test và lấy liên kết trang thanh toán (result.url)
2. Mở trang thanh toán và bấm “Mô phỏng thanh toán” → đủ số tiền
3. Máy chủ của tôi nhận được webhook với status paid và chữ ký xác minh đúng
4. Đơn hàng tương ứng được đánh dấu đã thanh toán
5. Cùng webhook đó đến lần nữa (gửi lại từ “Nhà phát triển › Nhật ký webhook” của trang quản trị, hoặc POST /v1/payment/resend) không giao hàng hai lần

**Mỗi người dùng một địa chỉ nạp cố định**

1. Mở một địa chỉ cho người dùng thử bằng thông tin xác thực Test và lấy địa chỉ cùng liên kết trang nạp tiền
2. Gửi một webhook mẫu bằng POST /v1/test-webhook/wallet
3. Máy chủ của tôi nhận được webhook với type wallet và chữ ký xác minh đúng
4. Số dư của người dùng đó tăng thêm payment_amount_usd
5. Cùng webhook đó đến lần nữa không cộng số dư hai lần

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

1. Nút hiển thị đúng trên máy tính và trên điện thoại
2. Nút mở đúng liên kết thanh toán của tôi (trước hết dùng liên kết tạo ở chế độ Test)
3. Bấm “Mô phỏng thanh toán” trên trang thanh toán thì khoản thanh toán hiện trong “Thanh toán › Giao dịch” ở trang quản trị

## Khi AI bị kẹt.

- **Chữ ký không bao giờ xác minh được**: Dán nội dung webhook thô vào [công cụ kiểm tra chữ ký](https://blockwallets.io/docs/sign?lang=vi). Nó hiển thị mọi bước trung gian và đánh dấu điểm khác biệt đầu tiên; hãy nói với AI của bạn chính xác chỗ khác nhau.
- **Một endpoint trả về lỗi**: Dán lại cho AI chính xác yêu cầu và phản hồi (kể cả message). Khi chữ ký sai, debug.body_base64 trong phản hồi 401 là văn bản chúng tôi đã ký; hãy để AI so với kết quả của nó.
- **Không biết vướng ở đâu**: Bảo AI đi qua danh sách nghiệm thu từ mục đầu tiên, từng mục một, báo từng kết quả. “Nhà phát triển › Nhật ký webhook” trong trang quản trị hiển thị mọi yêu cầu webhook và phản hồi của máy chủ bạn.

### Bốn điều bạn cần để mắt đến.

- **Chỉ đưa AI thông tin xác thực Test**: Merchant ID và API key của Test chạy trên testnet; dù bị lộ cũng không thể chuyển được tiền.
- **Đừng để API key Live trong cuộc trò chuyện**: Hãy tự đặt API key Live vào biến môi trường trên máy chủ của bạn. Không bao giờ dán nó vào cuộc trò chuyện hay commit vào kho code.
- **Sao lưu trước khi AI sửa**: Commit (git commit) hoặc sao chép các tệp website của bạn trước khi AI bắt đầu, để có thể quay lại.
- **Tự trả một lần trước khi chạy thật**: Sau khi chuyển sang Live, hãy trả một khoản nhỏ thật qua “Thử thanh toán” ở trang chủ của trang quản trị và kiểm tra đơn đã thanh toán và số dư đã về.

## Một tệp quy tắc cho coding agent.

AGENTS.md chứa những điều cốt lõi của tích hợp, các lỗi thường gặp và danh sách nghiệm thu. Đặt nó ở thư mục gốc dự án: Codex và Cursor tự đọc, Claude Code nạp nó bằng @AGENTS.md.

```sh
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md
echo '@AGENTS.md' >> CLAUDE.md
```

- [Quy tắc tích hợp (AGENTS.md)](https://blockwallets.io/agents.md)
- [Tóm tắt một trang](https://blockwallets.io/llms.txt)
- [Tài liệu đầy đủ](https://blockwallets.io/llms-full.txt)
- [Trang này dạng Markdown](https://blockwallets.io/docs/ai.md?lang=vi)
- [Tài liệu dạng Markdown](https://blockwallets.io/docs.md?lang=vi)
- [MCP server](https://blockwallets.io/docs/mcp?lang=vi)

## Câu hỏi, đã có lời đáp.

### Không biết lập trình thì có thật sự tích hợp bằng AI được không?

Với hầu hết website, được. AI viết code tạo hóa đơn và code chữ ký theo tài liệu; bạn đặt thông tin xác thực vào biến môi trường và đi qua danh sách nghiệm thu ở chế độ thử nghiệm. Nếu bạn không muốn đụng đến code, hãy dùng liên kết thanh toán.

### Nên dùng công cụ AI nào?

Công cụ sửa dự án và chạy lệnh giúp bạn là dễ nhất: Claude Code, Codex hoặc Cursor. ChatGPT hay Claude trên web cũng được, nhưng bạn phải tự dán code vào website.

### Có nên đưa API key cho AI không?

Chỉ thông tin xác thực Test, và đặt trong tệp môi trường chứ không phải trong cuộc trò chuyện. API key Live hãy tự đặt trên máy chủ của bạn.

### Chữ ký webhook không bao giờ xác minh được. Làm sao?

Bỏ sign, mã hóa lại phần còn lại theo cách PHP json_encode làm và thoát / thành \/. Dán nội dung webhook thô vào /docs/sign để so từng bước, rồi nói với AI chỗ khác nhau.

### AI nói đã xong. Kiểm tra thế nào?

Chạy danh sách nghiệm thu: tạo hóa đơn thử, mô phỏng thanh toán, thấy webhook xác minh đúng, thấy đơn được đánh dấu đã thanh toán, và gửi lại cùng webhook đó để xác nhận không giao hàng hai lần. Hãy trả một khoản Live nhỏ trước khi chạy thật.