Kết nối AI agent

Đưa cho AI agent lập trình của bạn một URL — https://crypto.tgpaybot.com/mcp — và nó dựng luôn phần tích hợp thanh toán: đọc tài liệu API, tạo ứng dụng Merchant API, thiết lập webhook và viết code. Bạn chỉ duyệt ứng dụng mới một lần, bằng một nút bấm trong bot. Không cần terminal, cũng không phải tự tay sao chép token API.

URL đó là một MCP server (Model Context Protocol — cách chuẩn để cắm một dịch vụ vào AI agent). Mở nó trong trình duyệt là nó tự giải thích cách 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:

• Chat agent bất kỳ — dán prompt này:

  Connect the tgpay MCP server (https://crypto.tgpaybot.com/mcp) and integrate payments via the TgPay 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://crypto.tgpaybot.com/mcp
• claude.ai và Claude Desktop — Settings → Connectors → Add custom connector → dán URL vào.
• ChatGPT và các MCP client khác — thêm một custom connector với cùng URL đó.

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 bạn đã tạo ứng dụng thủ công rồi, hãy đưa agent chính token đó và bỏ qua thẳng tới phần tích hợp.

Duyệt ứng dụng

1. Bảo agent thiết lập thanh toán. Nó đọc tài liệu rồi hỏi bạn duyệt.
2. 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.
3. Quay lại agent. Nó nhận token trong vài giây và tự hoàn tất phần tích hợp.

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ạn bấm ❌ Từ chối thì cũng không có gì được tạo ra, và yêu cầu đó khép lại — đổi ý nghĩa là agent phải gửi một 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.

Thiệt hại đã bị giới hạn ngay từ thiết kế: token của agent chỉ nhận tiền vào, không bao giờ đưa tiền ra (xem bên dưới). Nhưng một ứng dụng bạn không hề yêu cầu thì chẳng có lý do gì 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ì

Token mà agent nhận được là 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. Mọi thao tác đưa tiền ra khỏi số dư ứng dụng đều cần token toàn quyền, mà token đó nằm lại trong ứng dụng.

Cách chia này là có chủ ý: token của agent nằm trong file cấu hình và trong context của mô hình — những chỗ dễ bị chọc hơn máy chủ của bạn. Một token bị lộ nhiều nhất chỉ khiến webhook URL của bạn bị trỏ sai, chứ không bao giờ mất số dư. 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 hoặc thu hồi token của agent, mở Thêm → Merchant API, tìm ứng dụng đó 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.

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

Agent trỏ được webhook URL về máy chủ của bạn, nhưng không kiểm tra được thứ gửi tới đó: mỗi lần gửi đều ký bằng token chính của ứng dụng, thứ agent không bao giờ thấy. Một agent tử tế sẽ viết sẵn phần code kiểm tra chữ ký và để lại cho bạn một chỗ trống — kiểu 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, bấm Đổi token mới và sao chép thứ hiện ra — 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.

Tiếp theo

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