API 参考：转账和红包

打款相关的方法。转账把资金从您的应用余额直接送进某位 Telegram 用户的钱包；红包是一条 您先出钱、别人来领的链接。通用约定（鉴权、外层结构、金额、spend_id）见 商户 API 参考页面。

transfer

POST /pay/api/transfer——权限范围 payouts，每分钟 30 次。瞬间原子结清；没有中间态。

参数	类型	必填	含义
user_id	integer	是	收款人的 Telegram 用户 ID。收款人必须已经是本应用的用户——打给一个不存在的 ID 会报错，而不是让资金卡在中途
asset	string	是	币种代码
amount	string	是	正的小数字符串；同时受平台每笔转账的上下限约束（按当前行情折算成美元等值来估）
spend_id	string	是	幂等键，1–64 个字符，每笔打款唯一
comment	string	否	最多 1024 个字符，显示给收款人
disable_send_notification	boolean	否	true = 不在 Telegram 里通知收款人

返回的是转账对象：transfer_id、hash、user_id、asset、amount、amount_minor、 spend_id、comment、status（永远是 completed）、created_at、completed_at。

错误：404 user_not_found（收款人从没用过这个应用）、409 recipient_blocked、 400 amount_too_small / 400 amount_too_big（超出每笔转账的上下限）、 409 insufficient_funds、404 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、asset、 amount、spend_id，以及可选的 comment 和 disable_send_notification）。同一批里的 spend_id 必须互不相同，否则整个调用在执行任何一笔之前就以 400 duplicate_spend_id 失败。

各项按顺序独立结清——某一项失败绝不会把其他的回滚掉。即使有几项失败了，这个调用照样返回 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（精确匹配——用您自己的键去查一笔打款），外加 offset / count。返回 {"items": [transfer, …]}，按时间倒序。

createCheck

POST /pay/api/createCheck——权限范围 checks，每分钟 60 次。开一个一次性红包，资金从您的 应用余额出；拿到链接的人——或只有被指定的那位用户——可以把它领进自己的钱包。金额在红包 创建的那一刻就锁住（在 getBalance 里从 available 挪到 onhold）。

参数	类型	必填	含义
asset	string	是	币种代码
amount	string	是	正的小数字符串
pin_to_user_id	integer	否	只有这个 Telegram 用户 ID 能领
pin_to_username	string	否	只有这个 @username 能领（@ 可写可不写；同时设了 pin_to_user_id 时忽略它）。这个用户名必须属于本应用已有的用户
spend_id	string	否	幂等键（扩展）——请用上它

返回的是红包对象：check_id、hash、asset、amount、amount_minor、 bot_check_url（t.me 领取链接）、status（active / activated）、pin_to_user_id、 created_at、activated_at。被领取时会触发需要订阅的 check_activated webhook。

错误：404 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, …]}，按时间倒序；已删除的红包永远不返回。