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

1. Mở Thêm → Merchant API.
2. 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.
3. Bấm Tạo ứng dụng.
4. 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ó.
5. 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 động tới tiền — createInvoice, transfer, createCheck và các phương thức xóa tương ứng — chỉ nhận POST, và đó là chủ ý: số tiền cùng khóa idempotency không nên nằm trong access log. Tham số có thể gửi dưới dạng JSON body, form-urlencoded hoặc query param.

Quản lý ứng dụng

Mỗi thẻ ứng dụng trong Merchant API hiển thị app ID và số dư của nó, và cho phép bạn:

• Đặt hoặc đổi webhook URL rồi lưu lại.
• Chọn thêm sự kiện webhook — khi đã đặt webhook URL, các nút gạt Sự kiện webhook bổ sung cho phép bạn bật những loại sự kiện ngoài invoice_paid (xem tài liệu webhook).
• Tạo token giới hạn quyền — các token API bổ sung, nằm 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 — 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 — ứng dụng không còn xác thực được nữa, nhưng số dư và lịch sử thanh toán vẫn được giữ lại. Xóa ứng dụng không bao giờ làm tiền biến mất.

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 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 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 luôn được gửi. 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 giới hạn quyền không có scope payouts vẫn tạo được hóa đơn nhưng không bao giờ chuyển được số dư của bạn ra ngoài.