{ "components": { "schemas": { "Balance": { "additionalProperties": false, "properties": { "code": { "description": "业务码：0 成功，1000 起为失败", "enum": [ 0 ], "type": "integer" }, "data": { "additionalProperties": false, "properties": { "app_id": { "description": "商户 APPID，由鉴权请求头确定", "type": "string" }, "balance": { "description": "账户余额，十进制字符串，最多 6 位小数；省略小数末尾无意义的 0", "type": "string" }, "currency": { "description": "币种，固定为 USDT", "type": "string" } }, "required": [ "app_id", "currency", "balance" ], "type": "object" }, "message": { "description": "结果描述", "type": "string" }, "request_id": { "description": "请求标识，可用于问题排查", "type": "string" } }, "required": [ "request_id", "code", "message", "data" ], "type": "object" }, "CreatePaymentOrder": { "additionalProperties": false, "properties": { "callback_url": { "description": "本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知", "maxLength": 2048, "pattern": "^(https://[^\\s#]+)?$", "type": "string" }, "custom_params": { "description": "自定义参数，最多 500 字符；原样返回，默认空字符串", "maxLength": 500, "type": "string" }, "expires_at": { "description": "过期时间，秒级 RFC 3339，须包含时区；须晚于当前时间且不超过 30 分钟。未传或空字符串默认 10 分钟", "example": "2026-10-22T00:20:00Z", "pattern": "^([0-9]{4}-[0-9]{2}-[0-9]{2}T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](Z|[+-]([01][0-9]|2[0-3]):[0-5][0-9]))?$", "type": "string" }, "payment_amount": { "description": "收款金额，USDT，正数；最多 24 位整数、2 位小数", "example": "10.00", "pattern": "^(?!0(?:\\.0{1,2})?$)(0|[1-9][0-9]{0,23})(\\.[0-9]{1,2})?$", "type": "string" }, "third_order_no": { "description": "三方订单号，1–32 个字符，同一 APPID 下唯一；重复返回 1019", "maxLength": 32, "minLength": 1, "type": "string" } }, "required": [ "third_order_no", "payment_amount" ], "type": "object" }, "CreatePayoutOrder": { "additionalProperties": false, "properties": { "callback_url": { "description": "本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知", "maxLength": 2048, "pattern": "^(https://[^\\s#]+)?$", "type": "string" }, "custom_params": { "description": "自定义参数，最多 500 字符；原样返回，默认空字符串", "maxLength": 500, "type": "string" }, "payout_amount": { "description": "出款金额，USDT；不收手续费，商户扣款与会员到账均等于此金额", "pattern": "^(?!0(?:\\.0{1,2})?$)(0|[1-9][0-9]{0,23})(\\.[0-9]{1,2})?$", "type": "string" }, "third_order_no": { "description": "三方订单号，1–32 个字符，同一 APPID 下唯一；重复返回 1019", "maxLength": 32, "minLength": 1, "type": "string" }, "user_id": { "description": "收款会员的10位用户ID，首位非0；不是Telegram ID", "pattern": "^[1-9][0-9]{9}$", "type": "string" } }, "required": [ "third_order_no", "user_id", "payout_amount" ], "type": "object" }, "CreateRefundOrder": { "additionalProperties": false, "properties": { "callback_url": { "description": "本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知", "maxLength": 2048, "pattern": "^(https://[^\\s#]+)?$", "type": "string" }, "refund_amount": { "description": "退款金额，USDT，正数金额字符串，最多 24 位整数、2 位小数", "pattern": "^(?!0(?:\\.0{1,2})?$)(0|[1-9][0-9]{0,23})(\\.[0-9]{1,2})?$", "type": "string" }, "third_order_no": { "description": "原收款订单的三方订单号", "maxLength": 32, "minLength": 1, "type": "string" }, "third_refund_no": { "description": "三方退款单号，1–32 个字符，同一 APPID 下唯一", "maxLength": 32, "minLength": 1, "type": "string" } }, "required": [ "third_order_no", "third_refund_no", "refund_amount" ], "type": "object" }, "Error": { "additionalProperties": false, "properties": { "code": { "description": "业务码：0 成功，1000 起为失败", "enum": [ 1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009, 1010, 1011, 1012, 1013, 1014, 1015, 1016, 1017, 1018, 1019, 1020, 1021, 1022, 1023, 1024, 1025, 1026, 1027, 1028, 1029, 1030, 1031, 1032, 1033, 1034 ], "type": "integer" }, "data": { "description": "无业务数据，固定为 null", "enum": [ null ], "nullable": true, "type": "object" }, "message": { "description": "结果描述", "type": "string" }, "request_id": { "description": "请求标识，可用于问题排查", "type": "string" } }, "required": [ "request_id", "code", "message", "data" ], "type": "object" }, "Merchant": { "additionalProperties": false, "properties": { "code": { "description": "业务码：0 成功，1000 起为失败", "enum": [ 0 ], "type": "integer" }, "data": { "additionalProperties": false, "properties": { "app_id": { "description": "商户 APPID，由鉴权请求头确定", "type": "string" }, "create_time": { "description": "创建时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" }, "ip_whitelist": { "description": "IPv4 白名单", "items": { "format": "ipv4", "type": "string" }, "type": "array" }, "name": { "description": "商户名称", "type": "string" }, "rate": { "description": "费率，基点整数字符串，0–10000；636 表示 6.36%", "example": "636", "pattern": "^(0|[1-9][0-9]{0,3}|10000)$", "type": "string" }, "status": { "description": "商户状态；成功应答为 ENABLED", "type": "string" }, "update_time": { "description": "更新时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" } }, "required": [ "app_id", "name", "status", "rate", "ip_whitelist", "create_time", "update_time" ], "type": "object" }, "message": { "description": "结果描述", "type": "string" }, "request_id": { "description": "请求标识，可用于问题排查", "type": "string" } }, "required": [ "request_id", "code", "message", "data" ], "type": "object" }, "NotificationAcknowledgement": { "properties": { "code": { "enum": [ "SUCCESS" ], "type": "string" } }, "required": [ "code" ], "type": "object" }, "NotificationContent": { "properties": { "create_time": { "format": "date-time", "type": "string" }, "data": { "oneOf": [ { "additionalProperties": false, "properties": { "actual_amount": { "description": "收款金额 − 手续费；待支付时为预计到账金额", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "app_id": { "description": "商户 APPID，由鉴权请求头确定", "type": "string" }, "callback_url": { "description": "本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知", "maxLength": 2048, "pattern": "^(https://[^\\s#]+)?$", "type": "string" }, "close_time": { "description": "关闭时间，RFC 3339 / UTC；未关闭时为空字符串", "type": "string" }, "create_time": { "description": "创建时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" }, "currency": { "description": "币种，固定为 USDT", "type": "string" }, "custom_params": { "description": "自定义参数，最多 500 字符；原样返回，默认空字符串", "type": "string" }, "expires_at": { "description": "订单到期时间，RFC 3339 / UTC", "format": "date-time", "type": "string" }, "fee_amount": { "description": "手续费 = 收款金额 × 费率基点 ÷ 10000；截断至 2 位小数，不四舍五入", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "fee_rate": { "description": "订单费率，基点整数 0–10000；636 表示 6.36%", "example": "636", "pattern": "^(0|[1-9][0-9]{0,3}|10000)$", "type": "string" }, "order_id": { "description": "平台订单ID，YYYYMMDD + 10位随机数字，表内唯一", "example": "202610220000000042", "pattern": "^[0-9]{18}$", "type": "string" }, "pay_time": { "description": "付款时间，RFC 3339 / UTC；未支付时为空字符串", "type": "string" }, "pay_url": { "description": "Telegram 付款链接，打开后由付款人确认支付", "type": "string" }, "payment_amount": { "description": "收款金额，USDT，正数；最多 24 位整数、2 位小数", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "refund_status": { "description": "退款状态：NONE 无退款，PARTIAL 部分退款，FULL 全额退款", "enum": [ "NONE", "PARTIAL", "FULL" ], "type": "string" }, "status": { "description": "订单状态：PENDING 待支付，TIMEOUT 已超时，PAID 已支付，CLOSED 已关闭", "enum": [ "PENDING", "TIMEOUT", "PAID", "CLOSED" ], "type": "string" }, "third_order_no": { "description": "三方订单号，1–32 个字符，同一 APPID 下唯一；重复返回 1019", "type": "string" }, "update_time": { "description": "更新时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" } }, "required": [ "pay_url", "expires_at", "callback_url", "order_id", "app_id", "third_order_no", "currency", "payment_amount", "fee_amount", "fee_rate", "actual_amount", "status", "refund_status", "custom_params", "create_time", "close_time", "pay_time", "update_time" ], "type": "object" }, { "additionalProperties": false, "properties": { "app_id": { "description": "商户 APPID，由鉴权请求头确定", "type": "string" }, "callback_url": { "description": "本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知", "maxLength": 2048, "pattern": "^(https://[^\\s#]+)?$", "type": "string" }, "create_time": { "description": "创建时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" }, "currency": { "description": "币种，固定为 USDT", "type": "string" }, "failure_reason": { "description": "退款失败原因；非失败状态为空字符串", "type": "string" }, "fee_refund_amount": { "description": "本次实际退还手续费；仅成功时结算，处理及失败时为 0.00", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "merchant_debit_amount": { "description": "本次商户实际扣款 = 退款金额 − 退还手续费；仅成功时结算，处理及失败时为 0.00", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "order_id": { "description": "平台订单ID，YYYYMMDD + 10位随机数字，表内唯一", "example": "202610220000000042", "pattern": "^[0-9]{18}$", "type": "string" }, "refund_amount": { "description": "退款金额，USDT，正数金额字符串，最多 24 位整数、2 位小数", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "refund_id": { "description": "平台退款ID，YYYYMMDD + 10位随机数字，表内唯一", "example": "202610220000000042", "pattern": "^[0-9]{18}$", "type": "string" }, "status": { "description": "退款状态：PROCESSING 处理中，SUCCESS 成功，FAILED 失败", "enum": [ "PROCESSING", "SUCCESS", "FAILED" ], "type": "string" }, "success_time": { "description": "退款成功时间，RFC 3339 / UTC；未成功时为空字符串", "type": "string" }, "third_order_no": { "description": "原收款订单的三方订单号", "type": "string" }, "third_refund_no": { "description": "三方退款单号，1–32 个字符，同一 APPID 下唯一", "type": "string" }, "update_time": { "description": "更新时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" } }, "required": [ "callback_url", "refund_id", "order_id", "app_id", "third_order_no", "third_refund_no", "currency", "refund_amount", "fee_refund_amount", "merchant_debit_amount", "status", "failure_reason", "create_time", "success_time", "update_time" ], "type": "object" }, { "additionalProperties": false, "properties": { "app_id": { "description": "商户 APPID，由鉴权请求头确定", "type": "string" }, "callback_url": { "description": "本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知", "maxLength": 2048, "pattern": "^(https://[^\\s#]+)?$", "type": "string" }, "create_time": { "description": "创建时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" }, "currency": { "description": "币种，固定为 USDT", "type": "string" }, "custom_params": { "description": "自定义参数，最多 500 字符；原样返回，默认空字符串", "type": "string" }, "failure_reason": { "description": "出款失败原因；非失败状态为空字符串", "type": "string" }, "finish_time": { "description": "处理完成时间，RFC 3339 / UTC；处理中为空字符串", "type": "string" }, "payout_amount": { "description": "出款金额，USDT；不收手续费，商户扣款与会员到账均等于此金额", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "payout_id": { "description": "平台出款ID，YYYYMMDD + 10位随机数字，表内唯一", "example": "202610220000000042", "pattern": "^[0-9]{18}$", "type": "string" }, "status": { "description": "出款状态：PROCESSING 处理中，SUCCESS 成功，FAILED 失败", "enum": [ "PROCESSING", "SUCCESS", "FAILED" ], "type": "string" }, "third_order_no": { "description": "三方订单号，1–32 个字符，同一 APPID 下唯一；重复返回 1019", "type": "string" }, "update_time": { "description": "更新时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" }, "user_id": { "description": "收款会员的10位用户ID，首位非0；不是Telegram ID", "pattern": "^[1-9][0-9]{9}$", "type": "string" } }, "required": [ "payout_id", "app_id", "third_order_no", "user_id", "currency", "payout_amount", "status", "failure_reason", "custom_params", "callback_url", "create_time", "finish_time", "update_time" ], "type": "object" } ] }, "event": { "enum": [ "PAYMENT.SUCCESS", "REFUND.SUCCESS", "REFUND.FAILED", "PAYOUT.SUCCESS", "PAYOUT.FAILED" ], "type": "string" }, "notification_id": { "description": "通知唯一ID；自动及手动重试均不变，用于幂等处理", "type": "string" } }, "required": [ "notification_id", "event", "create_time", "data" ], "type": "object" }, "NotificationEnvelope": { "additionalProperties": false, "properties": { "algorithm": { "enum": [ "AEAD_AES_256_GCM" ], "type": "string" }, "ciphertext": { "description": "密文与16字节GCM认证标签拼接后，标准Base64编码", "type": "string" }, "nonce": { "description": "12字节随机数，标准Base64编码", "type": "string" } }, "required": [ "algorithm", "nonce", "ciphertext" ], "type": "object" }, "PaymentOrder": { "additionalProperties": false, "properties": { "code": { "description": "业务码：0 成功，1000 起为失败", "enum": [ 0 ], "type": "integer" }, "data": { "additionalProperties": false, "properties": { "actual_amount": { "description": "收款金额 − 手续费；待支付时为预计到账金额", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "app_id": { "description": "商户 APPID，由鉴权请求头确定", "type": "string" }, "callback_url": { "description": "本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知", "maxLength": 2048, "pattern": "^(https://[^\\s#]+)?$", "type": "string" }, "close_time": { "description": "关闭时间，RFC 3339 / UTC；未关闭时为空字符串", "type": "string" }, "create_time": { "description": "创建时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" }, "currency": { "description": "币种，固定为 USDT", "type": "string" }, "custom_params": { "description": "自定义参数，最多 500 字符；原样返回，默认空字符串", "type": "string" }, "expires_at": { "description": "订单到期时间，RFC 3339 / UTC", "format": "date-time", "type": "string" }, "fee_amount": { "description": "手续费 = 收款金额 × 费率基点 ÷ 10000；截断至 2 位小数，不四舍五入", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "fee_rate": { "description": "订单费率，基点整数 0–10000；636 表示 6.36%", "example": "636", "pattern": "^(0|[1-9][0-9]{0,3}|10000)$", "type": "string" }, "order_id": { "description": "平台订单ID，YYYYMMDD + 10位随机数字，表内唯一", "example": "202610220000000042", "pattern": "^[0-9]{18}$", "type": "string" }, "pay_time": { "description": "付款时间，RFC 3339 / UTC；未支付时为空字符串", "type": "string" }, "pay_url": { "description": "Telegram 付款链接，打开后由付款人确认支付", "type": "string" }, "payment_amount": { "description": "收款金额，USDT，正数；最多 24 位整数、2 位小数", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "refund_status": { "description": "退款状态：NONE 无退款，PARTIAL 部分退款，FULL 全额退款", "enum": [ "NONE", "PARTIAL", "FULL" ], "type": "string" }, "status": { "description": "订单状态：PENDING 待支付，TIMEOUT 已超时，PAID 已支付，CLOSED 已关闭", "enum": [ "PENDING", "TIMEOUT", "PAID", "CLOSED" ], "type": "string" }, "third_order_no": { "description": "三方订单号，1–32 个字符，同一 APPID 下唯一；重复返回 1019", "type": "string" }, "update_time": { "description": "更新时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" } }, "required": [ "pay_url", "expires_at", "callback_url", "order_id", "app_id", "third_order_no", "currency", "payment_amount", "fee_amount", "fee_rate", "actual_amount", "status", "refund_status", "custom_params", "create_time", "close_time", "pay_time", "update_time" ], "type": "object" }, "message": { "description": "结果描述", "type": "string" }, "request_id": { "description": "请求标识，可用于问题排查", "type": "string" } }, "required": [ "request_id", "code", "message", "data" ], "type": "object" }, "PayoutOrder": { "additionalProperties": false, "properties": { "code": { "description": "业务码：0 成功，1000 起为失败", "enum": [ 0 ], "type": "integer" }, "data": { "additionalProperties": false, "properties": { "app_id": { "description": "商户 APPID，由鉴权请求头确定", "type": "string" }, "callback_url": { "description": "本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知", "maxLength": 2048, "pattern": "^(https://[^\\s#]+)?$", "type": "string" }, "create_time": { "description": "创建时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" }, "currency": { "description": "币种，固定为 USDT", "type": "string" }, "custom_params": { "description": "自定义参数，最多 500 字符；原样返回，默认空字符串", "type": "string" }, "failure_reason": { "description": "出款失败原因；非失败状态为空字符串", "type": "string" }, "finish_time": { "description": "处理完成时间，RFC 3339 / UTC；处理中为空字符串", "type": "string" }, "payout_amount": { "description": "出款金额，USDT；不收手续费，商户扣款与会员到账均等于此金额", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "payout_id": { "description": "平台出款ID，YYYYMMDD + 10位随机数字，表内唯一", "example": "202610220000000042", "pattern": "^[0-9]{18}$", "type": "string" }, "status": { "description": "出款状态：PROCESSING 处理中，SUCCESS 成功，FAILED 失败", "enum": [ "PROCESSING", "SUCCESS", "FAILED" ], "type": "string" }, "third_order_no": { "description": "三方订单号，1–32 个字符，同一 APPID 下唯一；重复返回 1019", "type": "string" }, "update_time": { "description": "更新时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" }, "user_id": { "description": "收款会员的10位用户ID，首位非0；不是Telegram ID", "pattern": "^[1-9][0-9]{9}$", "type": "string" } }, "required": [ "payout_id", "app_id", "third_order_no", "user_id", "currency", "payout_amount", "status", "failure_reason", "custom_params", "callback_url", "create_time", "finish_time", "update_time" ], "type": "object" }, "message": { "description": "结果描述", "type": "string" }, "request_id": { "description": "请求标识，可用于问题排查", "type": "string" } }, "required": [ "request_id", "code", "message", "data" ], "type": "object" }, "RefundOrder": { "additionalProperties": false, "properties": { "code": { "description": "业务码：0 成功，1000 起为失败", "enum": [ 0 ], "type": "integer" }, "data": { "additionalProperties": false, "properties": { "app_id": { "description": "商户 APPID，由鉴权请求头确定", "type": "string" }, "callback_url": { "description": "本订单回调地址，非必填；填写时必须为 HTTPS，最多 2048 字节，须为公网地址；未传或空字符串表示不通知", "maxLength": 2048, "pattern": "^(https://[^\\s#]+)?$", "type": "string" }, "create_time": { "description": "创建时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" }, "currency": { "description": "币种，固定为 USDT", "type": "string" }, "failure_reason": { "description": "退款失败原因；非失败状态为空字符串", "type": "string" }, "fee_refund_amount": { "description": "本次实际退还手续费；仅成功时结算，处理及失败时为 0.00", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "merchant_debit_amount": { "description": "本次商户实际扣款 = 退款金额 − 退还手续费；仅成功时结算，处理及失败时为 0.00", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "order_id": { "description": "平台订单ID，YYYYMMDD + 10位随机数字，表内唯一", "example": "202610220000000042", "pattern": "^[0-9]{18}$", "type": "string" }, "refund_amount": { "description": "退款金额，USDT，正数金额字符串，最多 24 位整数、2 位小数", "pattern": "^(0|[1-9][0-9]{0,23})\\.[0-9]{2}$", "type": "string" }, "refund_id": { "description": "平台退款ID，YYYYMMDD + 10位随机数字，表内唯一", "example": "202610220000000042", "pattern": "^[0-9]{18}$", "type": "string" }, "status": { "description": "退款状态：PROCESSING 处理中，SUCCESS 成功，FAILED 失败", "enum": [ "PROCESSING", "SUCCESS", "FAILED" ], "type": "string" }, "success_time": { "description": "退款成功时间，RFC 3339 / UTC；未成功时为空字符串", "type": "string" }, "third_order_no": { "description": "原收款订单的三方订单号", "type": "string" }, "third_refund_no": { "description": "三方退款单号，1–32 个字符，同一 APPID 下唯一", "type": "string" }, "update_time": { "description": "更新时间，RFC 3339 格式，UTC 时区", "format": "date-time", "type": "string" } }, "required": [ "callback_url", "refund_id", "order_id", "app_id", "third_order_no", "third_refund_no", "currency", "refund_amount", "fee_refund_amount", "merchant_debit_amount", "status", "failure_reason", "create_time", "success_time", "update_time" ], "type": "object" }, "message": { "description": "结果描述", "type": "string" }, "request_id": { "description": "请求标识，可用于问题排查", "type": "string" } }, "required": [ "request_id", "code", "message", "data" ], "type": "object" } }, "securitySchemes": { "MerchantSignature": { "description": "HMAC-SHA256 签名，64 位小写十六进制", "in": "header", "name": "X-Signature", "type": "apiKey" } } }, "info": { "description": "商户信息、账户余额、收款订单、退款订单及出款订单。请求使用 HTTPS 与 HMAC-SHA256 签名。", "title": "TGPay 商户 API", "version": "1.9.0" }, "openapi": "3.0.3", "paths": { "/v1/account/balance": { "get": { "description": "无请求参数。", "operationId": "getBalance", "parameters": [ { "description": "商户 APPID，10 位数字，首位非 0", "in": "header", "name": "X-App-Id", "required": true, "schema": { "pattern": "^[1-9][0-9]{9}$", "type": "string" } }, { "description": "Unix 秒级时间戳，10 位数字；允许前后 300 秒偏差", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "pattern": "^[0-9]{10}$", "type": "string" } }, { "description": "32 位小写十六进制随机串；每次请求重新生成", "in": "header", "name": "X-Nonce", "required": true, "schema": { "pattern": "^[0-9a-f]{32}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Balance" }, { "$ref": "#/components/schemas/Error" } ] } } }, "description": "HTTP 固定 200；code=0 成功，非 0 为业务失败", "headers": { "Retry-After": { "description": "code=1015 时返回，重试前等待秒数", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "请求标识", "schema": { "type": "string" } } }, "x-error-codes": [ 1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009, 1010, 1011, 1012, 1013, 1014, 1015, 1016, 1017 ] } }, "security": [ { "MerchantSignature": [] } ], "summary": "查询账户余额" } }, "/v1/merchant": { "get": { "description": "无请求参数。", "operationId": "getMerchant", "parameters": [ { "description": "商户 APPID，10 位数字，首位非 0", "in": "header", "name": "X-App-Id", "required": true, "schema": { "pattern": "^[1-9][0-9]{9}$", "type": "string" } }, { "description": "Unix 秒级时间戳，10 位数字；允许前后 300 秒偏差", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "pattern": "^[0-9]{10}$", "type": "string" } }, { "description": "32 位小写十六进制随机串；每次请求重新生成", "in": "header", "name": "X-Nonce", "required": true, "schema": { "pattern": "^[0-9a-f]{32}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Merchant" }, { "$ref": "#/components/schemas/Error" } ] } } }, "description": "HTTP 固定 200；code=0 成功，非 0 为业务失败", "headers": { "Retry-After": { "description": "code=1015 时返回，重试前等待秒数", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "请求标识", "schema": { "type": "string" } } }, "x-error-codes": [ 1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009, 1010, 1012, 1013, 1014, 1015, 1016, 1017 ] } }, "security": [ { "MerchantSignature": [] } ], "summary": "查询商户信息" } }, "/v1/payment-orders": { "get": { "description": "按三方订单号查询当前 APPID 下的收款订单。", "operationId": "getPaymentOrder", "parameters": [ { "description": "商户 APPID，10 位数字，首位非 0", "in": "header", "name": "X-App-Id", "required": true, "schema": { "pattern": "^[1-9][0-9]{9}$", "type": "string" } }, { "description": "Unix 秒级时间戳，10 位数字；允许前后 300 秒偏差", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "pattern": "^[0-9]{10}$", "type": "string" } }, { "description": "32 位小写十六进制随机串；每次请求重新生成", "in": "header", "name": "X-Nonce", "required": true, "schema": { "pattern": "^[0-9a-f]{32}$", "type": "string" } }, { "description": "三方订单号，1–32 个字符，同一 APPID 下唯一；重复返回 1019", "in": "query", "name": "third_order_no", "required": true, "schema": { "maxLength": 32, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentOrder" }, { "$ref": "#/components/schemas/Error" } ] } } }, "description": "HTTP 固定 200；code=0 成功，非 0 为业务失败", "headers": { "Retry-After": { "description": "code=1015 时返回，重试前等待秒数", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "请求标识", "schema": { "type": "string" } } }, "x-error-codes": [ 1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009, 1010, 1012, 1013, 1014, 1015, 1016, 1017, 1020 ] } }, "security": [ { "MerchantSignature": [] } ], "summary": "查询收款订单" }, "post": { "callbacks": { "orderResult": { "{$request.body#/callback_url}": { "post": { "description": "仅填写回调地址时发送，完整业务数据使用商户密钥AES-256-GCM加密。接收方须在10秒内返回HTTP 200和JSON code=SUCCESS。", "parameters": [ { "description": "用于选择商户密钥；须与解密后的data.app_id一致", "in": "header", "name": "X-App-Id", "required": true, "schema": { "pattern": "^[1-9][0-9]{9}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationEnvelope" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationAcknowledgement" } } }, "description": "通知已可靠接收" } }, "summary": "订单结果通知" } } } }, "description": "创建 USDT 收款订单。", "operationId": "createPaymentOrder", "parameters": [ { "description": "商户 APPID，10 位数字，首位非 0", "in": "header", "name": "X-App-Id", "required": true, "schema": { "pattern": "^[1-9][0-9]{9}$", "type": "string" } }, { "description": "Unix 秒级时间戳，10 位数字；允许前后 300 秒偏差", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "pattern": "^[0-9]{10}$", "type": "string" } }, { "description": "32 位小写十六进制随机串；每次请求重新生成", "in": "header", "name": "X-Nonce", "required": true, "schema": { "pattern": "^[0-9a-f]{32}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentOrder" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PaymentOrder" }, { "$ref": "#/components/schemas/Error" } ] } } }, "description": "HTTP 固定 200；code=0 成功，非 0 为业务失败", "headers": { "Retry-After": { "description": "code=1015 时返回，重试前等待秒数", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "请求标识", "schema": { "type": "string" } } }, "x-error-codes": [ 1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009, 1010, 1012, 1013, 1014, 1015, 1016, 1017, 1018, 1019, 1027, 1033, 1034 ] } }, "security": [ { "MerchantSignature": [] } ], "summary": "创建收款订单" } }, "/v1/payout-orders": { "get": { "description": "按三方订单号查询当前APPID下的出款订单。", "operationId": "getPayoutOrder", "parameters": [ { "description": "商户 APPID，10 位数字，首位非 0", "in": "header", "name": "X-App-Id", "required": true, "schema": { "pattern": "^[1-9][0-9]{9}$", "type": "string" } }, { "description": "Unix 秒级时间戳，10 位数字；允许前后 300 秒偏差", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "pattern": "^[0-9]{10}$", "type": "string" } }, { "description": "32 位小写十六进制随机串；每次请求重新生成", "in": "header", "name": "X-Nonce", "required": true, "schema": { "pattern": "^[0-9a-f]{32}$", "type": "string" } }, { "description": "三方订单号，1–32 个字符，同一 APPID 下唯一；重复返回 1019", "in": "query", "name": "third_order_no", "required": true, "schema": { "maxLength": 32, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PayoutOrder" }, { "$ref": "#/components/schemas/Error" } ] } } }, "description": "HTTP 固定 200；code=0 成功，非 0 为业务失败", "headers": { "Retry-After": { "description": "code=1015 时返回，重试前等待秒数", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "请求标识", "schema": { "type": "string" } } }, "x-error-codes": [ 1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009, 1010, 1012, 1013, 1014, 1015, 1016, 1017, 1029 ] } }, "security": [ { "MerchantSignature": [] } ], "summary": "查询出款" }, "post": { "callbacks": { "orderResult": { "{$request.body#/callback_url}": { "post": { "description": "仅填写回调地址时发送，完整业务数据使用商户密钥AES-256-GCM加密。接收方须在10秒内返回HTTP 200和JSON code=SUCCESS。", "parameters": [ { "description": "用于选择商户密钥；须与解密后的data.app_id一致", "in": "header", "name": "X-App-Id", "required": true, "schema": { "pattern": "^[1-9][0-9]{9}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationEnvelope" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationAcknowledgement" } } }, "description": "通知已可靠接收" } }, "summary": "订单结果通知" } } } }, "description": "商户向会员账户转款，不收手续费；受理后通过通知或查询确认结果。同一APPID下三方订单号重复返回1019。", "operationId": "createPayoutOrder", "parameters": [ { "description": "商户 APPID，10 位数字，首位非 0", "in": "header", "name": "X-App-Id", "required": true, "schema": { "pattern": "^[1-9][0-9]{9}$", "type": "string" } }, { "description": "Unix 秒级时间戳，10 位数字；允许前后 300 秒偏差", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "pattern": "^[0-9]{10}$", "type": "string" } }, { "description": "32 位小写十六进制随机串；每次请求重新生成", "in": "header", "name": "X-Nonce", "required": true, "schema": { "pattern": "^[0-9a-f]{32}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayoutOrder" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/PayoutOrder" }, { "$ref": "#/components/schemas/Error" } ] } } }, "description": "HTTP 固定 200；code=0 成功，非 0 为业务失败", "headers": { "Retry-After": { "description": "code=1015 时返回，重试前等待秒数", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "请求标识", "schema": { "type": "string" } } }, "x-error-codes": [ 1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009, 1010, 1011, 1012, 1013, 1014, 1015, 1016, 1017, 1019, 1027, 1028, 1030, 1031, 1032 ] } }, "security": [ { "MerchantSignature": [] } ], "summary": "申请出款" } }, "/v1/refund-orders": { "get": { "description": "按三方退款单号查询当前 APPID 下的退款订单。", "operationId": "getRefundOrder", "parameters": [ { "description": "商户 APPID，10 位数字，首位非 0", "in": "header", "name": "X-App-Id", "required": true, "schema": { "pattern": "^[1-9][0-9]{9}$", "type": "string" } }, { "description": "Unix 秒级时间戳，10 位数字；允许前后 300 秒偏差", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "pattern": "^[0-9]{10}$", "type": "string" } }, { "description": "32 位小写十六进制随机串；每次请求重新生成", "in": "header", "name": "X-Nonce", "required": true, "schema": { "pattern": "^[0-9a-f]{32}$", "type": "string" } }, { "description": "三方退款单号，1–32 个字符，同一 APPID 下唯一", "in": "query", "name": "third_refund_no", "required": true, "schema": { "maxLength": 32, "minLength": 1, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RefundOrder" }, { "$ref": "#/components/schemas/Error" } ] } } }, "description": "HTTP 固定 200；code=0 成功，非 0 为业务失败", "headers": { "Retry-After": { "description": "code=1015 时返回，重试前等待秒数", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "请求标识", "schema": { "type": "string" } } }, "x-error-codes": [ 1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009, 1010, 1012, 1013, 1014, 1015, 1016, 1017, 1025 ] } }, "security": [ { "MerchantSignature": [] } ], "summary": "查询退款" }, "post": { "callbacks": { "orderResult": { "{$request.body#/callback_url}": { "post": { "description": "仅填写回调地址时发送，完整业务数据使用商户密钥AES-256-GCM加密。接收方须在10秒内返回HTTP 200和JSON code=SUCCESS。", "parameters": [ { "description": "用于选择商户密钥；须与解密后的data.app_id一致", "in": "header", "name": "X-App-Id", "required": true, "schema": { "pattern": "^[1-9][0-9]{9}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationEnvelope" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationAcknowledgement" } } }, "description": "通知已可靠接收" } }, "summary": "订单结果通知" } } } }, "description": "提交已支付订单退款；以查询退款的 SUCCESS 状态为完成依据。同一退款单号与相同参数重试返回原退款单，参数不同返回 1023。", "operationId": "createRefundOrder", "parameters": [ { "description": "商户 APPID，10 位数字，首位非 0", "in": "header", "name": "X-App-Id", "required": true, "schema": { "pattern": "^[1-9][0-9]{9}$", "type": "string" } }, { "description": "Unix 秒级时间戳，10 位数字；允许前后 300 秒偏差", "in": "header", "name": "X-Timestamp", "required": true, "schema": { "pattern": "^[0-9]{10}$", "type": "string" } }, { "description": "32 位小写十六进制随机串；每次请求重新生成", "in": "header", "name": "X-Nonce", "required": true, "schema": { "pattern": "^[0-9a-f]{32}$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundOrder" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RefundOrder" }, { "$ref": "#/components/schemas/Error" } ] } } }, "description": "HTTP 固定 200；code=0 成功，非 0 为业务失败", "headers": { "Retry-After": { "description": "code=1015 时返回，重试前等待秒数", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "请求标识", "schema": { "type": "string" } } }, "x-error-codes": [ 1000, 1001, 1002, 1003, 1004, 1005, 1006, 1007, 1008, 1009, 1010, 1012, 1013, 1014, 1015, 1016, 1017, 1020, 1021, 1022, 1023, 1024, 1026, 1027 ] } }, "security": [ { "MerchantSignature": [] } ], "summary": "申请退款" } } }, "servers": [ { "url": "https://{host}", "variables": { "host": { "default": "api.example.com", "description": "替换为服务方提供的 API 域名" } } } ], "x-auth-headers": [ { "name": "X-App-Id", "type": "string", "description": "商户 APPID，10 位数字，首位非 0", "pattern": "^[1-9][0-9]{9}$" }, { "name": "X-Timestamp", "type": "string", "description": "Unix 秒级时间戳，10 位数字；允许前后 300 秒偏差", "pattern": "^[0-9]{10}$" }, { "name": "X-Nonce", "type": "string", "description": "32 位小写十六进制随机串；每次请求重新生成", "pattern": "^[0-9a-f]{32}$" }, { "name": "X-Signature", "type": "string", "description": "HMAC-SHA256 签名，64 位小写十六进制", "pattern": "^[0-9a-f]{64}$" } ], "x-error-catalog": [ { "code": 1000, "name": "INVALID_REQUEST", "message": "请求格式不正确", "resolution": "请按接口说明检查方法、路径、JSON 请求体和查询参数。" }, { "code": 1001, "name": "PARAM_ERROR", "message": "请求参数格式不正确", "resolution": "检查鉴权参数、订单号及字段类型、长度。" }, { "code": 1002, "name": "AUTH_REQUIRED", "message": "缺少鉴权参数", "resolution": "补齐四个鉴权请求头，每个请求头只允许一个值。" }, { "code": 1003, "name": "INVALID_CREDENTIALS", "message": "商户凭证无效", "resolution": "检查 APPID 是否正确。" }, { "code": 1004, "name": "TIMESTAMP_EXPIRED", "message": "请求时间戳已过期", "resolution": "同步服务器时间，使用当前 Unix 秒级时间戳重新签名。允许偏差为前后 300 秒。" }, { "code": 1005, "name": "SIGN_ERROR", "message": "签名验证失败", "resolution": "检查密钥、原始路径和换行规则；密钥刷新后须使用新密钥。" }, { "code": 1006, "name": "MERCHANT_DISABLED", "message": "商户已禁用", "resolution": "启用商户后重新请求。" }, { "code": 1007, "name": "ACCOUNT_DISABLED", "message": "账户不可用", "resolution": "联系服务方核实账户状态。" }, { "code": 1008, "name": "IP_WHITELIST_EMPTY", "message": "未配置IP白名单", "resolution": "将调用服务器的出口 IPv4 加入商户白名单。" }, { "code": 1009, "name": "IP_NOT_ALLOWED", "message": "请求IP不在白名单中", "resolution": "检查调用服务器的出口 IPv4 与白名单配置。" }, { "code": 1010, "name": "NOT_FOUND", "message": "接口不存在", "resolution": "检查请求路径和 API 版本。" }, { "code": 1011, "name": "ACCOUNT_NOT_FOUND", "message": "账户不存在", "resolution": "联系服务方核实账户是否已开通。" }, { "code": 1012, "name": "METHOD_NOT_ALLOWED", "message": "请求方法不支持", "resolution": "使用接口指定的 GET 或 POST 方法。" }, { "code": 1013, "name": "NONCE_REUSED", "message": "请求随机串已使用", "resolution": "每次请求（包括重试）生成新的随机串并重新签名。" }, { "code": 1014, "name": "PAYLOAD_TOO_LARGE", "message": "请求体过大", "resolution": "请求体不得超过 16384 字节；GET 接口不接受请求体。" }, { "code": 1015, "name": "RATE_LIMITED", "message": "请求频率超限", "resolution": "每个 APPID 所有接口合计每自然分钟最多 60 次；按 Retry-After 响应头等待后重新签名请求。" }, { "code": 1016, "name": "SYSTEM_ERROR", "message": "服务内部异常", "resolution": "创建订单或申请退款应先查询原单；查询请求可稍后重新签名重试。仍失败时提供 request_id 排查。" }, { "code": 1017, "name": "SERVICE_UNAVAILABLE", "message": "服务暂不可用", "resolution": "创建订单或申请退款应先查询原单；查询请求可稍后重新签名重试。仍失败时提供 request_id 排查。" }, { "code": 1018, "name": "AMOUNT_INVALID", "message": "收款金额格式不正确", "resolution": "payment_amount 必须是大于 0 的十进制字符串，最多 24 位整数、2 位小数；不接受科学计数法。" }, { "code": 1019, "name": "ORDER_EXISTS", "message": "订单号已存在", "resolution": "同一 APPID 下三方订单号不可重复；请查询原订单或使用新的订单号创建。" }, { "code": 1020, "name": "ORDER_NOT_FOUND", "message": "收款订单不存在", "resolution": "检查当前 APPID 下的 third_order_no；不能查询其他 APPID 的订单。" }, { "code": 1021, "name": "REFUND_AMOUNT_INVALID", "message": "退款金额格式不正确", "resolution": "refund_amount 必须为正数金额字符串，最多 24 位整数、2 位小数。" }, { "code": 1022, "name": "ORDER_NOT_PAID", "message": "收款订单尚未支付", "resolution": "仅已支付订单支持退款。" }, { "code": 1023, "name": "REFUND_CONFLICT", "message": "退款单号已存在且参数不一致", "resolution": "同一 APPID 下退款单号唯一；重试须使用原订单号、退款金额及回调地址。" }, { "code": 1024, "name": "REFUND_AMOUNT_EXCEEDED", "message": "退款金额超过可退金额", "resolution": "原收款金额减去成功及处理中的退款金额，为当前可退金额。" }, { "code": 1025, "name": "REFUND_NOT_FOUND", "message": "退款订单不存在", "resolution": "检查当前 APPID 下的 third_refund_no。" }, { "code": 1026, "name": "REFUND_PAYER_INVALID", "message": "收款订单付款人信息不完整", "resolution": "联系服务方核实原收款订单。" }, { "code": 1027, "name": "CALLBACK_URL_INVALID", "message": "回调地址格式不正确", "resolution": "callback_url 可不传或为空字符串；填写时须为有效 HTTPS 地址，最多 2048 字节，不允许账号密码、片段或空白字符。" }, { "code": 1028, "name": "PAYOUT_AMOUNT_INVALID", "message": "出款金额格式不正确", "resolution": "payout_amount 必须为大于0的十进制字符串，最多24位整数、2位小数。" }, { "code": 1029, "name": "PAYOUT_NOT_FOUND", "message": "出款订单不存在", "resolution": "检查当前 APPID 下的 third_order_no。" }, { "code": 1030, "name": "PAYOUT_RECIPIENT_NOT_FOUND", "message": "收款会员不存在", "resolution": "user_id 使用收款会员的10位用户ID，不能使用 Telegram ID。" }, { "code": 1031, "name": "PAYOUT_RECIPIENT_DISABLED", "message": "收款会员不可用", "resolution": "核实收款会员账户状态。" }, { "code": 1032, "name": "PAYOUT_SELF_TRANSFER", "message": "不能向商户所属账户出款", "resolution": "收款会员不能是当前商户所属会员。" }, { "code": 1033, "name": "PAYMENT_BOT_UNAVAILABLE", "message": "收款机器人暂不可用", "resolution": "联系服务方核实收款机器人状态后重试。" }, { "code": 1034, "name": "PAYMENT_EXPIRY_INVALID", "message": "收款订单过期时间不正确", "resolution": "expires_at 须为秒级 RFC 3339 时间，晚于当前时间且不超过 30 分钟；未传或空字符串默认 10 分钟。" } ], "x-notification": { "acknowledgement": { "code": "SUCCESS" }, "algorithm": "AEAD_AES_256_GCM", "associated_data": "TGPay-Merchant-Notify-v1", "max_attempts": 10, "retry_interval_seconds": 60, "timeout_seconds": 10 } }