Tài liệu API: chuyển tiền và Lì xì

Các phương thức chi trả. Một lệnh chuyển đưa tiền từ số dư ứng dụng của bạn thẳng vào ví của một người dùng Telegram; một Lì xì là liên kết nhận tiền mà bạn nạp sẵn tiền vào. Các quy ước chung (xác thực, envelope, số tiền, spend_id) nằm ở trang tài liệu Merchant API.

transfer

POST /pay/api/transfer — scope payouts, giới hạn 30 lần mỗi phút. Hoàn tất tức thì và trọn vẹn; không có trạng thái chờ.

Tham số	Kiểu	Bắt buộc	Ý nghĩa
user_id	integer	có	Telegram user id của người nhận. Người nhận phải đã là người dùng của ứng dụng — chi trả tới một id lạ sẽ báo lỗi thay vì để tiền mắc kẹt
asset	string	có	mã tài sản
amount	string	có	chuỗi thập phân dương; ngoài ra còn phải nằm trong mức tối thiểu và tối đa cho mỗi lệnh của nền tảng (ước lượng theo giá trị quy đổi ra USD tại tỷ giá hiện hành)
spend_id	string	có	khóa idempotency, 1–64 ký tự, không trùng giữa các khoản chi
comment	string	không	tối đa 1024 ký tự, hiện cho người nhận
disable_send_notification	boolean	không	true = không báo cho người nhận trong Telegram

Kết quả là đối tượng transfer: transfer_id, hash, user_id, asset, amount, amount_minor, spend_id, comment, status (luôn là completed), created_at, completed_at.

Lỗi: 404 user_not_found (người nhận chưa từng dùng ứng dụng), 409 recipient_blocked, 400 amount_too_small / 400 amount_too_big (nằm ngoài khoảng cho phép của mỗi lệnh), 409 insufficient_funds, 404 unknown_asset, 400 invalid_amount, và cặp lỗi của spend_id: 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

POST /pay/api/transferBatch — scope payouts, giới hạn 10 lần mỗi phút. Một phần mở rộng dành cho chi trả hàng loạt: tối đa 100 lệnh chuyển trong một lần gọi.

Một tham số: items — một mảng mà mỗi phần tử là trọn bộ tham số của transfer (user_id, asset, amount, spend_id, kèm comment và disable_send_notification tùy chọn). Các spend_id phải khác nhau trong cùng một lô, nếu không cả lần gọi thất bại với 400 duplicate_spend_id trước khi bất cứ gì được thực thi.

Các phần tử được xử lý độc lập, theo thứ tự — một phần tử thất bại không bao giờ làm hoàn tác các phần tử khác. Lần gọi vẫn trả về HTTP 200 với ok: true ngay cả khi có phần tử thất bại, nên hãy luôn kiểm tra từng phần tử:

• thành công: {"ok": true, "spend_id": "…", "result": <transfer object>}
• thất bại: {"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}} với đúng bộ tên lỗi của một transfer đơn lẻ.

Các phần tử trong lô dùng chung không gian idempotency với lệnh chuyển đơn lẻ: thử lại cả lô — hoặc gửi lại một phần tử dưới dạng một transfer đơn lẻ với cùng spend_id — sẽ phát lại thay vì trả tiền hai lần.

getTransfers

GET /pay/api/getTransfers — scope read. Bộ lọc: asset, transfer_ids (phân tách bằng dấu phẩy), spend_id (khớp chính xác — tra một khoản chi theo khóa của riêng bạn), cùng offset / count. Trả về {"items": [transfer, …]}, mới nhất trước.

createCheck

POST /pay/api/createCheck — scope checks, giới hạn 60 lần mỗi phút. Tạo một Lì xì dùng một lần, lấy tiền từ số dư ứng dụng của bạn; ai có liên kết — hoặc chỉ người được gán sẵn — đều nhận được về ví của mình. Số tiền được tạm giữ ngay lúc Lì xì được tạo (nó chuyển từ available sang onhold trong getBalance).

Tham số	Kiểu	Bắt buộc	Ý nghĩa
asset	string	có	mã tài sản
amount	string	có	chuỗi thập phân dương
pin_to_user_id	integer	không	chỉ Telegram user id này được nhận
pin_to_username	string	không	chỉ @username này được nhận (dấu @ là tùy chọn; bị bỏ qua khi đã đặt cả pin_to_user_id). Username phải thuộc về một người dùng đang có của ứng dụng
spend_id	string	không	khóa idempotency (phần mở rộng) — hãy dùng nó

Kết quả là đối tượng check: check_id, hash, asset, amount, amount_minor, bot_check_url (liên kết t.me để nhận), status (active / activated), pin_to_user_id, created_at, activated_at. Mỗi lần có người nhận đều bắn webhook check_activated — loại cần bật thủ công.

Lỗi: 404 unknown_asset, 400 invalid_amount, 404 user_not_found (username được gán không khớp với ai), 409 insufficient_funds, và cặp lỗi của spend_id.

deleteCheck

POST /pay/api/deleteCheck — scope checks. Một tham số: check_id. Hủy một Lì xì chưa ai nhận và trả số tiền đang tạm giữ về số dư ứng dụng của bạn; trả về true. Lỗi: 404 check_not_found, 409 check_not_active (đã có người nhận hoặc đã bị xóa).

getChecks

GET /pay/api/getChecks — scope read. Bộ lọc: asset, check_ids (phân tách bằng dấu phẩy), status (active / activated), cùng offset / count. Trả về {"items": [check, …]}, mới nhất trước; các Lì xì đã xóa không bao giờ được trả về.