API 参考：转账和红包

本页介绍打款方法。转账将应用余额中的资金发送到 Telegram 用户的钱包，或暂时托管，等待新收款人打开机器人；红包是一条领取链接，创建时会预先锁定金额。通用约定（鉴权、响应结构、金额、spend_id）见 商户 API 参考页面。

三个打款方法都受应用的打款模式约束：新应用默认可向任何人打款；如果所有者收紧了限制，则只能向名单内的收款人打款（403 recipient_not_allowed），或禁止所有打款（403 payouts_disabled）。模式由所有者在 Mini App 中设置，无法通过 API 修改。打款用途须符合商户 API 使用条款。

transfer

POST /pay/api/transfer——权限范围 payouts，每分钟 30。收款人已是应用用户时，资金立即到账。若 username 尚未对应到应用用户，则创建状态为 pending 的转账：资金暂时托管，直到收款人首次以该用户名打开机器人；未领取资金在 30 天到期后退回应用余额（到期时间见 expires_at）。记账前，请通过 status: "returned" 确认资金已退回。请自行将 invite_url 转发给收款人，机器人无法主动联系尚未启动过它的人。最终状态为 completed 或 returned；可订阅 transfer_completed 和 transfer_returned webhook，或轮询 getTransfers 获取结果。

参数	类型	必填	含义
user_id	integer	与 username 二选一，必须且只能填写一项	收款人的 Telegram 用户 ID；收款人必须已经是本应用的用户
username	string	与 user_id 二选一，必须且只能填写一项	收款人的用户名，可带或不带 @；尚未对应到应用用户时，会创建待领取的转账
asset	string	是	币种代码
amount	string	是	表示正数金额的十进制字符串；受平台单笔转账金额上下限约束（按当前汇率估算美元等值）
spend_id	string	是	幂等键，1–64 个字符，每笔打款唯一
comment	string	否	最多 1024 个字符，显示给收款人
disable_send_notification	boolean	否	true 表示立即到账时不通知收款人；待领取转账被领取时仍会发送通知

返回的是转账对象：transfer_id、hash、user_id、recipient_username、asset、amount、amount_minor、spend_id、comment、status（pending / completed / returned）、created_at、completed_at、expires_at、invite_url。等待新收款人领取时，user_id 可以为 null；转账完成前，completed_at 为 null。

错误：403 payouts_disabled / 403 recipient_not_allowed（打款模式）、 404 user_not_found（ID 不存在或收款人不可用）、400 invalid_recipient（收款人用户名格式无效）、 400 amount_too_small / 400 amount_too_big（超出每笔转账的上下限）、 409 insufficient_funds、400 unknown_asset、400 invalid_amount，以及与 spend_id 相关的 409 idempotency_conflict / 409 idempotency_in_progress。

transferBatch

POST /pay/api/transferBatch——权限范围 payouts，每分钟 10。用于批量打款的扩展方法： 一次调用最多 100 笔转账。

一个参数：items——一个数组，每一项都是完整的 transfer 参数（user_id 或 username、asset、 amount、spend_id，以及可选的 comment 和 disable_send_notification）。同一批里的 spend_id 必须互不相同，否则整个调用在执行任何一笔之前就以 400 duplicate_spend_id 失败。项目结构无效、应用打款模式或每日限额也可能使整个请求在任何打款执行前被拒绝。请求被接受后，逐项结果会在 result.items 中返回。

各项按顺序独立执行，某一项失败不会回滚其他项。即使部分项失败，调用仍返回 HTTP 200 和 ok: true，所以请务必逐项检查：

• 成功：{"ok": true, "spend_id": "…", "result": <transfer object>}
• 失败：{"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}}，错误名跟单笔 transfer 是同一套。

批量转账与单笔转账共用同一个幂等命名空间：重试整批请求，或使用相同的 spend_id 将其中一项作为单笔 transfer 重发，都会复用原结果，不会重复付款。

getTransfers

GET /pay/api/getTransfers——权限范围 read。过滤条件：asset、transfer_ids（逗号分隔）、 spend_id（精确匹配，可用自己的键查找打款）、status（pending / completed / returned），以及 offset / count。返回 {"items": [transfer, …]}，按时间倒序。

createCheck

POST /pay/api/createCheck——权限范围 checks，每分钟 60。默认从应用余额创建单次领取红包，可由任何持有链接的人或指定用户领取。recipients 扩展支持指定名单，并为每位收款人设置单独金额。总额在创建时锁定（getBalance 中从 available 转为 onhold）。创建红包与转账适用相同的金额及每日打款限额。

参数	类型	必填	含义
asset	string	是	币种代码
amount	string	未设置 recipients 时必填	正数金额的十进制字符串；设置 recipients 时，总额按名单计算
pin_to_user_id	integer	否	只有这个 Telegram 用户 ID 能领
pin_to_username	string	否	只有这个 @username 能领（@ 可写可不写；同时设了 pin_to_user_id 时忽略它）。这个用户名必须属于本应用已有的用户
spend_id	string	否	幂等键（扩展），建议填写
recipients	array	否	扩展：1–100 项，每项包含 user_id 或 username，以及正数十进制字符串 amount。不能与单独指定收款人组合使用
password	string	否	扩展：领取所需口令，最多 64 个字符
expires_in	integer	否	扩展：有效时长，单位为秒；省略或 0 = 不设到期时间

返回的是红包对象：check_id、hash、asset、amount、amount_minor、 bot_check_url（t.me 领取链接）、status（active / activated）、pin_to_user_id、 created_at、activated_at、expires_at 和 recipients（普通红包为 null；名单红包中，每项包含 user_id、username、amount、amount_minor、claimed_at）。每次领取都会触发需订阅的 check_activated webhook，名单红包的领取还包含 activated_slot。到期会退回未领部分；名单红包到期可发送 check_expired。

当前响应会将未全部领取的红包一律返回为 status: "active"，包括已过期的红包。因此也须检查 expires_at，不能仅凭 active 判断链接仍可领取。

错误：403 payouts_disabled / 403 recipient_not_allowed（打款模式——在 allowlist 模式下， 每位指定或名单中的收款人都须在允许名单内）、400 unknown_asset、400 invalid_amount、 404 user_not_found（指定的用户名未对应到应用用户）、409 insufficient_funds，以及上述两种与 spend_id 相关的错误。

deleteCheck

POST /pay/api/deleteCheck——权限范围 checks。一个参数：check_id。取消进行中的红包，将未领余额退回应用余额；返回 true。错误：404 check_not_found、 409 check_not_active（已全部领取、已过期或已删除）。

getChecks

GET /pay/api/getChecks——权限范围 read。过滤条件：asset、check_ids（逗号分隔）、 status（active / activated），外加 offset / count。返回 {"items": [check, …]}，按时间倒序；已删除的红包永远不返回。