Kết nối AI agent · TgPay Crypto API

Kết nối AI agent lập trình có hỗ trợ máy chủ MCP từ xa với https://app.tgpaycrypto.com/mcp. Agent có thể đọc tài liệu API, yêu cầu tạo ứng dụng Merchant API, cấu hình webhook và hỗ trợ viết phần tích hợp. Bạn duyệt việc tạo ứng dụng trong bot; agent nhận token giới hạn quyền mà bạn không cần sao chép thủ công. Hãy kiểm tra và thử nghiệm phần tích hợp trước khi nhận thanh toán thật.

URL đó là một MCP server (Model Context Protocol — giao thức chuẩn để kết nối dịch vụ với AI agent). Mở URL trong trình duyệt để xem hướng dẫn thiết lập.

Cách kết nối

Dùng dòng phù hợp với công cụ của bạn:

Agent có hỗ trợ MCP từ xa — dán prompt này:
```
Connect the tgpay MCP server (https://app.tgpaycrypto.com/mcp) and integrate payments via the TgPay Crypto Merchant API.
```
Trong ứng dụng cũng có sẵn một prompt tương tự để sao chép, ở Thêm → Merchant API → Kết nối AI agent.
Claude Code — claude mcp add --transport http tgpay https://app.tgpaycrypto.com/mcp
claude.ai và Claude Desktop — thêm URL làm trình kết nối tùy chỉnh theo hướng dẫn của Claude.
ChatGPT và các MCP client khác — thêm URL làm máy chủ MCP tùy chỉnh nếu tài khoản và không gian làm việc cho phép. Với ChatGPT, làm theo hướng dẫn thiết lập hiện tại.

Để dựng trên mạng thử nghiệm trước, hãy dùng https://testnet.tgpaycrypto.com/mcp thay vào đó — khi ấy agent sẽ tạo ứng dụng trong @tgpaycrypto_testnet_bot, và tài liệu nó đọc sẽ nêu base URL của mạng thử nghiệm.

Bạn không cần có token API trước — agent tự lấy token riêng của nó ở bước sau. Nếu đã tạo ứng dụng thủ công, hãy tạo token giới hạn quyền, chỉ cấp những quyền agent cần rồi dùng token đó để tích hợp. Giữ token chính trên máy chủ của bạn. Với token được cấp thủ công, agent làm được gì tùy thuộc vào quyền bạn đã chọn.

Duyệt ứng dụng

Bảo agent thiết lập thanh toán. Nó đọc tài liệu rồi hỏi bạn duyệt.
Agent đưa cho bạn một liên kết t.me. Mở liên kết — bot hiện rõ những gì đang được xin — rồi bấm ✅ Tạo ứng dụng và cấp token.
Quay lại agent để nó lấy token và tiếp tục tích hợp. Tài khoản phải đủ điều kiện tạo ứng dụng; hãy xác minh nếu được yêu cầu.

Liên kết luôn đến từ agent của bạn — bot không bao giờ tự gửi: cho tới khi bạn mở nó, bot còn chưa biết agent đang hỏi về tài khoản của ai. Mỗi liên kết chỉ dùng được một lần. Nếu nó hết hiệu lực trước khi bạn kịp bấm, hãy bảo agent làm lại từ đầu — chưa có gì được tạo ra cho tới khi bạn duyệt.

Nếu bấm ❌ Từ chối, không có gì được tạo ra và yêu cầu kết thúc. Nếu đổi ý, hãy yêu cầu agent gửi yêu cầu mới.

⚠️ Chỉ duyệt yêu cầu do chính bạn khởi đầu

Một yêu cầu kết nối là yêu cầu tạo ứng dụng trên tài khoản của bạn. Chỉ duyệt nếu bạn vừa tự bảo agent của mình thiết lập thanh toán. Nếu liên kết đến bằng bất kỳ đường nào khác — một đoạn chat, một tin nhắn chuyển tiếp, một “bộ phận hỗ trợ” lạ mặt — hãy từ chối.

Token được cấp qua bước duyệt này không thể chuyển tiền, tạo Lì xì hay hoàn tiền (xem bên dưới). Token được cấp thủ công có thể có quyền khác. Ứng dụng mà bạn không yêu cầu không nên tồn tại trên tài khoản của bạn.

Agent làm được gì và không làm được gì

Qua bước duyệt trên, agent nhận được một token giới hạn quyền:

Nó làm được — tạo hóa đơn và gói đăng ký, đọc số dư, tỷ giá và thống kê của bạn, và đặt webhook URL.
Nó không làm được — chuyển tiền, phát hành Lì xì hay hoàn tiền. Những thao tác này cần quyền tương ứng payouts, checks hoặc refunds, hoặc token chính có toàn quyền. Token được cấp qua bước duyệt này không có các quyền đó.

Giữ kín token này: các quyền đã cấp vẫn cho phép thay đổi hóa đơn, gói đăng ký và webhook URL. Bot nhắn cho bạn mỗi khi có token được cấp cho agent và mỗi khi webhook URL của một ứng dụng thay đổi.

Để xem quyền hoặc thu hồi token của agent, mở Thêm → Merchant API, tìm ứng dụng đó rồi mở Quyền truy cập và token và xem mục Token giới hạn quyền — Thu hồi vô hiệu hóa token ngay lập tức. Bản thân ứng dụng, số dư và lịch sử thanh toán vẫn còn nguyên. Không thể xem lại giá trị token. Token có hạn sử dụng cũng ngừng hoạt động khi hết hạn.

Chữ ký webhook cần token chính của bạn

Agent có thể đặt webhook URL trỏ về máy chủ của bạn, nhưng không thể xác minh dữ liệu gửi tới đó: webhook được ký bằng token chính của ứng dụng mà agent không được cấp. Agent nên viết sẵn mã kiểm tra chữ ký và để trống một biến, chẳng hạn TGPAY_WEBHOOK_TOKEN, để bạn tự điền.

Cách điền: mở Thêm → Merchant API, tìm ứng dụng mà agent đã tạo, mở Quyền truy cập và token, bấm Đổi token mới và sao chép token mới — nó chỉ hiện một lần. Đặt nó vào biến môi trường của máy chủ, đừng bao giờ để trong cấu hình của agent hay trong repository. Việc đổi token không đụng tới token giới hạn quyền của agent, nên phần tích hợp vẫn chạy tiếp.

Chữ ký chuyển sang token mới ngay lúc bạn đổi, nên hãy đổi trước khi đưa vào chạy thật chứ đừng đổi sau khoản thanh toán thật đầu tiên.

Bắt đầu dành cho lập trình viên — cách làm thủ công, và cách quản lý ứng dụng sau khi nó đã tồn tại.
Tài liệu API: webhook — cấu trúc payload, cơ chế thử lại và bước kiểm tra chữ ký.
Tài liệu Merchant API — mọi phương thức, kể cả những phương thức agent không gọi được.