Hướng dẫn · PayStars

PayStars API dành cho nhà phát triển: toàn bộ quy trình bán Stars và Premium trong bot của bạn

Cách REST API của PayStars hoạt động từ đầu đến cuối: X-API-Key, kiểm tra tên người dùng, báo giá USD với max_usd, đơn hàng chống tính trùng, lỗi 409 price_changed và xác minh TxId, dưới dạng kế hoạch tích hợp.

Đã đăng: · Đã cập nhật:

PayStars API dành cho nhà phát triển: toàn bộ quy trình bán Stars và Premium trong bot của bạn

Muốn bán Telegram Stars và Premium ngay trong bot, cửa hàng hoặc ứng dụng của bạn? PayStars API cho bạn một giao diện HTTPS và số dư USD dùng chung với trang web. Thay vì nhắc lại tài liệu tham chiếu API, bài viết này cho thấy cách xây dựng phần tích hợp từ đầu đến cuối.

Kiến trúc trong nháy mắt

Hệ thống của bạn làm ba việc: nạp số dư bằng USDT, hỏi giá và tạo đơn hàng. Mọi thứ còn lại, kể cả việc giao qua luồng mua chính thức của Telegram, diễn ra ở phía PayStars.

PhầnChức năng
Truy cậpTiêu đề X-API-Key; khóa được tạo trong bảng điều khiển
Số dưUSD, nạp bằng USDT (TON, BEP20 hoặc TRC20)
GiáGiá Fragment × 1.05, làm tròn lên đến xu
Giới hạn10 yêu cầu mỗi giây cho mỗi khóa
Minh bạchMột TxId công khai cho mỗi đơn hàng đã hoàn tất

Giai đoạn 1: nạp số dư

POST /usd/invoice với một số tiền và một chuỗi ("ton", "bsc" hoặc "trc20") trả về số tiền chính xác có hiệu lực trong 30 phút. Mức tối thiểu là 0.1 USDT.

Giai đoạn 2: xác minh người nhận

POST /api/v1/check-username kiểm tra người nhận và trả về mã xác minh ngắn hạn. Việc này ngăn thanh toán tới tên người dùng không tồn tại: nếu khách hàng gõ sai, bạn biết trước khi có bất kỳ khoản nào bị tính.

Giai đoạn 3: lấy và giới hạn giá

POST /api/v1/usd/quote trả về giá hiện tại (usd) và mức phụ phí (markup_percent: 5). Giá theo thị trường, nên:

  • yêu cầu một báo giá mới trước mỗi đơn hàng;
  • truyền max_usd bằng đúng số đã báo;
  • luôn gửi currency: "USD", nếu không hệ thống sẽ dùng tùy chọn đã lưu của tài khoản.

Giai đoạn 4: tạo đơn hàng

POST /api/v1/stars/buy hoặc /api/v1/premium/buy. Mỗi yêu cầu phải mang một Idempotency-Key, nên nếu kết nối bị đứt và bạn thử lại, bạn không bị tính phí hai lần. Lưu khóa này cùng mã đơn hàng trong cơ sở dữ liệu của bạn.

Giai đoạn 5: theo dõi trạng thái

GET /api/v1/order/{id} và /api/v1/orders cho bạn trạng thái và lịch sử. Hầu hết đơn hàng được giao trong vài phút. Đơn hàng đã hoàn tất nhận một TxId mà cả bạn và khách hàng đều có thể kiểm tra trên sổ cái công khai của PayStars.

Xử lý lỗi đúng cách

  • 409 price_changed nghĩa là giá đã vượt max_usd và không có gì bị tính phí. Hãy lấy báo giá mới và cho khách hàng thấy giá đã cập nhật.
  • Giới hạn tần suất: đừng vượt quá 10 yêu cầu mỗi giây; hãy thêm hàng đợi hoặc cơ chế lùi dần.
  • Thử lại: luôn dùng lại cùng một Idempotency-Key.

Trước khi vận hành chính thức

  1. Giữ khóa API trong biến môi trường của máy chủ, không để trong mã nguồn.
  2. Chạy toàn bộ quy trình với một đơn hàng thật nhỏ gồm 50 Stars.
  3. Cho khách hàng thấy TxId của họ, điều này tạo niềm tin.

Tài liệu đầy đủ và hướng dẫn nhanh: PayStars Stars API và giá USD cho API. Với thanh toán trong bot, xem hàng hóa số trong bot chỉ được thanh toán bằng Stars.

Câu hỏi thường gặp

Có môi trường thử nghiệm không?

Không có môi trường thử nghiệm riêng; hãy thử bằng đơn hàng thật nhỏ (50 Stars) khi tích hợp.

Những ngôn ngữ lập trình nào dùng được?

Bất kỳ ngôn ngữ nào có thể gửi yêu cầu HTTPS. Có hướng dẫn nhanh cho Python, Node.js và PHP.

Làm thế nào để nạp số dư?

Bằng USDT trên TON, BEP20 hoặc TRC20, tối thiểu 0.1 USDT; mỗi hóa đơn có số tiền chính xác, có hiệu lực trong 30 phút.

Nguồn

Mua Stars và Premium bằng USD (USDT)

Qua khóa API: giá Fragment, 0% (trang web: 5%).

Bắt đầu