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 ở 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. Dù dùng token nào, agent cũng chỉ có thể nhận thanh toán qua máy chủ MCP (xem bên dưới).

Để cung cấp token này cho máy chủ MCP, thêm máy chủ trong phần cài đặt kết nối của client với header TgPayCrypto-API-Token: <token> hoặc Authorization: Bearer <token>. Khi đó không cần bước duyệt. Không phải client nào cũng có ô nhập header tùy chỉnh (connector của claude.ai và ChatGPT không có, và máy chủ không hỗ trợ đăng nhập OAuth); với các client đó, hãy dùng bước duyệt bên dưới. Agent cũng có thể truyền token qua đối số api_token trong một lần gọi công cụ, nếu client cho phép gửi đối số mà công cụ không khai báo.

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.

Ứng dụng và token của agent được tạo khi agent kiểm tra lại yêu cầu sau khi bạn bấm — thường chỉ trong vài giây. Yêu cầu có hiệu lực 10 phút kể từ lúc agent tạo nó: nếu agent không kiểm tra kịp, sẽ không có gì được tạo, dù bot đã xác nhận lựa chọn của bạn, và agent phải làm lại từ đầu. Tài khoản phải đủ điều kiện tạo ứng dụng; nếu cần xác minh, agent sẽ nhận lỗi ở lần kiểm tra đó — hãy hoàn tất xác minh rồi bảo agent kiểm tra lại trong cùng 10 phút đó, hoặc làm lại từ đầu.

Khi duyệt yêu cầu, bạn chấp nhận điều khoản Merchant API cho ứng dụng được tạo ra, giống như khi tự tạo ứng dụng trong Mini App.

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. Khi bạn chưa bấm nút nào, mở lại liên kết sẽ hiện đúng yêu cầu đó; sau khi bạn bấm ✅ Tạo ứng dụng và cấp token hoặc ❌ Từ chối, hoặc sau 10 phút, liên kết ngừng hoạt động. 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.

Không token nào có thể chuyển tiền, tạo Lì xì hay hoàn tiền qua máy chủ MCP, kể cả token được cấp qua bước duyệt này (xem bên dưới). Ứ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 và xóa hóa đơn, tạo và lưu trữ gói đăng ký, hủy gói đăng ký của người đăng ký, đọc số dư, tỷ giá và thống kê của bạn, và đổi webhook URL cùng tên ứng dụng.
Nó không làm được — chuyển tiền, phát hành Lì xì hay hoàn tiền: token không có các quyền payouts, checks hoặc refunds.

Máy chủ MCP còn áp dụng một giới hạn riêng: các công cụ chuyển tiền từ số dư ứng dụng — transfer, transferBatch, createCheck và refundInvoice — hiện đang bị tắt. Agent không thấy các công cụ này và mọi lời gọi đều bị từ chối, kể cả khi dùng token chính có toàn quyền. Vì vậy, dù token của agent bị lộ hay văn bản agent đọc có chứa chỉ dẫn độc hại, chẳng hạn trong ghi chú của người thanh toán, cũng không thể chuyển tiền ra khỏi ứng dụng qua MCP.

Chuyển tiền, tạo Lì xì và hoàn tiền vẫn dùng được trực tiếp qua API: gọi /pay/api từ mã trên máy chủ của bạn bằng token có quyền payouts, checks hoặc refunds tương ứng với thao tác. Để chi trả trong ứng dụng, mở Thêm → Merchant API, chọn ứng dụng của bạn rồi mở Chi trả.

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ý, các lượt đăng ký, webhook URL và tên ứng dụng. 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. Xác nhận đổi token bằng PIN hoặc Face ID. Ứng dụng do agent tạo có thể thuộc tài khoản chưa đặt PIN, nhưng việc đổi token cần PIN đã có hiệu lực. Hãy đặt mã trước trong Bảo mật và chờ mã có hiệu lực.

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.