Bắt đầu dành cho lập trình viên
Tạo một ứng dụng trong Mini App, sao chép token API của nó một lần, rồi bắt đầu gọi API. Toàn bộ phần thiết lập nằm ở Thêm → Merchant API.
Các bước
- Mở Thêm → Merchant API rồi chọn Tạo ứng dụng.
- Nhập Tên ứng dụng (ví dụ “Cửa hàng của tôi”) và, nếu muốn, một Webhook URL (không bắt buộc).
- Chấp nhận điều khoản trên biểu mẫu rồi bấm Tạo ứng dụng. Xác nhận bằng mã PIN hoặc sinh trắc học nếu được yêu cầu. Tạo ứng dụng nghĩa là chấp nhận điều khoản Merchant API — những gì bạn được và không được dùng API vào.
- Sao chép token API ngay lập tức. Token chỉ hiện đúng một lần và không bao giờ hiện lại — ứng dụng chỉ lưu bản băm của nó.
- Gửi yêu cầu đầu tiên với token đặt trong header
TgPayCrypto-API-Token.
Lệnh gọi đầu tiên
Trỏ client của bạn tới base API https://app.tgpaycrypto.com/pay/api và gọi
getMe để xác nhận token hoạt động. getBalance trả về số dư của ứng dụng,
getCurrencies trả về các tài sản bạn dùng được.
Các phương thức đọc dùng GET. Các phương thức ghi như createInvoice,
transfer, createCheck, deleteInvoice và deleteCheck chỉ nhận POST.
Tham số có thể gửi dưới dạng JSON body, form-urlencoded hoặc query param.
Nên gửi trong body để số tiền và khóa idempotency không xuất hiện trong nhật ký
truy cập URL.
Mạng thử nghiệm
Hãy dựng phần tích hợp trên mạng thử nghiệm (testnet) trước — cùng API, cùng Mini App, coin không có giá trị:
| Mạng chính | Mạng thử nghiệm | |
|---|---|---|
| Bot | @tgpaycryptobot | @tgpaycrypto_testnet_bot |
| Base API | https://app.tgpaycrypto.com/pay/api | https://testnet.tgpaycrypto.com/pay/api |
| MCP server | https://app.tgpaycrypto.com/mcp | https://testnet.tgpaycrypto.com/mcp |
Ứng dụng và token là riêng biệt: token của mạng thử nghiệm không dùng được trên mạng chính, và ngược lại. Để có tiền, mở Mini App của mạng thử nghiệm và bấm Nhận coin thử nghiệm trên màn hình chính. Gói tiền thử được ghi có như khoản nạp thông thường; tài sản trên mạng bị tắt sẽ được bỏ qua. Ứng dụng cho biết đã nhận gì và khi nào có thể yêu cầu tiếp. Bạn có thể dùng tài khoản Telegram thứ hai làm khách hàng thanh toán hóa đơn thử.
Nạp và rút dùng hệ thống lưu ký mô phỏng, không có giao dịch blockchain thật. Không bao giờ nạp tiền thật vào địa chỉ testnet. API dùng cùng quy ước, nhưng tính năng, tỷ giá và hạn mức có thể khác mạng chính. Khi xong, hãy tạo ứng dụng chính thức trong @tgpaycryptobot và đổi base URL.
Quản lý ứng dụng
Mở một ứng dụng trong Merchant API để xem app ID và số dư. Tại đây, bạn có thể:
- Đặt hoặc đổi webhook URL trong Webhook rồi lưu lại.
- Chọn thêm sự kiện webhook — các nút gạt Sự kiện
webhook bổ sung trong mục Webhook cho phép bạn bật những loại sự kiện ngoài
invoice_paid(xem tài liệu webhook). - Giới hạn người nhận mà API được chi trả — trong Cài đặt chi trả, Chi trả qua API mặc định là Mọi người dùng với ứng dụng mới; hãy chuyển sang Chỉ người dùng trong danh sách (và thêm người nhận vào) hoặc Tắt nếu phần tích hợp của bạn không bao giờ chi trả cho ai — một lớp chắn phòng khi token bị lộ (xem chế độ chi trả).
- Tạo token giới hạn quyền — mở Quyền truy cập và token để tạo token API bổ sung trong mục Token giới hạn quyền, mỗi token chỉ gồm các scope bạn chọn (xem tài liệu API).
- Đổi token mới — trong Quyền truy cập và token, cấp một token mới và vô hiệu hóa token cũ ngay lập tức. Dùng khi token bị lộ; token mới cũng chỉ hiện một lần, như lúc tạo.
- Xóa — trước tiên chuyển hết số dư khả dụng ra; nếu còn, việc xóa bị từ chối với
app_has_balance. Cũng cần xử lý Lì xì chưa nhận hết và khoản chi trả đang chờ trước khi xóa. Ứng dụng biến mất khỏi danh sách, các token ngừng hoạt động; lịch sử thanh toán vẫn được giữ.
Webhook
Nếu bạn đặt webhook URL, ứng dụng sẽ POST một JSON body có chữ ký tới đó:
{ "update_id": …, "update_type": "invoice_paid", "request_date": …, "payload": { … } }Chữ ký nằm ở header TgPayCrypto-API-Signature (với
TgCryptoPay-API-Signature và Crypto-Pay-API-Signature là tên gọi thay thế
để tương thích):
HMAC-SHA256 trên nội dung thô của body, dùng khóa là SHA-256 của token API chính
của bạn. Hãy kiểm tra chữ ký trước khi tin bất cứ thứ gì trong payload.
Mỗi lần gửi thất bại đều được thử lại nhiều lần, với khoảng cách giãn dần theo
cấp số nhân trong một khoảng thời gian dài, và update_id giữ nguyên qua các
lần thử lại — hãy chống trùng theo trường này và viết handler idempotent.
invoice_paid không cần bật riêng khi đã cấu hình webhook URL. Các loại sự kiện khác — hóa đơn hết hạn, Lì xì đã
được nhận, hoàn tiền, sự kiện gói đăng ký — cần bật thủ công qua các nút gạt
Sự kiện webhook bổ sung. Danh sách đầy đủ, cấu trúc payload và lịch thử lại
nằm trong tài liệu webhook.
⚠️ Giữ token như giữ khóa riêng tư
Token cho phép chi tiền từ số dư ứng dụng của bạn. Hãy giữ nó trên máy chủ,
đừng bao giờ để trong ứng dụng di động, bundle front-end hay file cấu hình đã
commit. Nếu không chắc nó có bị lộ hay không, cứ đổi token mới — việc đổi diễn
ra tức thì và không mất phí. Và hãy cấp cho mỗi máy chủ đúng phần nó cần: một
token chỉ có scope invoices có thể tạo và xóa hóa đơn, nhưng không thể chuyển
tiền, tạo Lì xì hoặc hoàn tiền.
Bài viết này có giúp được bạn không?
Cảm ơn phản hồi của bạn.