8. 偶像端 API 8.37 申请提现【未授权拦截通过，待登录态联调】

Table of Contents

8.37 申请提现【未授权拦截通过，待登录态联调】

POST /tieup/api/v1/artist/withdrawals

请求头：

Idempotency-Key: withdraw_10001_20260602143000_x7f9k2

请求体：

{
  "withdraw_amount": "2000.00",
  "withdraw_account_id": 1,
  "preview_token": "preview-token-example"
}

请求参数：

参数 类型 必填 说明
withdraw_amount string 是 最多两位小数
withdraw_account_id integer 是 当前偶像已维护的有效提现账户 ID
preview_token string 是 最近一次云账户订单试算返回的一次性令牌

响应字段：

字段 类型 说明
withdraw_no string 提现单号
withdraw_amount string 用户申请并冻结的提现金额
user_fee object 申请时锁定的平台提现服务费，结构为 {fee,val}
provider_pay_amount string 扣除平台提现服务费后的云账户下单金额
tax_amount string 本次预计预扣税额，单位元
estimated_received_amount string 申请时锁定的云账户预计到账金额，单位元
actual_amount string 云账户最终实际到账金额；支付成功前为 "0.00"
withdraw_status integer 提现状态：1=待审核，2=审核通过，3=审核拒绝，4=打款中，5=已完成，6=打款失败，7=已取消
funds_status integer 资金状态：1=冻结中，2=已完成，3=已退回
funds_status_label string 资金状态中文说明
account_snapshot object 申请提现时写入提现单的账户快照
account_snapshot.account_type integer 账户类型：1=支付宝，2=微信，3=银行卡
account_snapshot.account_name string 收款账户实名姓名
account_snapshot.account_no_masked string 脱敏后的收款账号
account_snapshot.bank_name string/null 开户银行
account_snapshot.bank_branch string/null 开户支行

响应示例：

{
  "code": 200,
  "message": "成功",
  "data": {
    "withdraw_no": "WD202606170001",
    "withdraw_amount": "2000.00",
    "user_fee": {"fee": "10", "val": "200.00"},
    "provider_pay_amount": "1800.00",
    "tax_amount": "90.00",
    "estimated_received_amount": "1710.00",
    "actual_amount": "0.00",
    "withdraw_status": 1,
    "funds_status": 1,
    "funds_status_label": "冻结中",
    "account_snapshot": {
      "account_type": 1,
      "account_type_label": "支付宝",
      "account_name": "李四",
      "account_no_masked": "al**************.com",
      "bank_name": null,
      "bank_branch": null
    }
  }
}

业务规则：

  • 仅个人艺人可提现。
  • 提现窗口、最低提现金额、提现服务费率和预计到账日读取后台基础配置；最低金额按申请金额判断，税费由云账户订单试算提供。
  • 提现申请在事务内锁定 tieup_artist 行和所选提现账户，扣减 withdrawable_amount，写入 tieup_artist_withdraw 和 tieup_artist_transaction.change_type = 2。
  • withdraw_amount 是用户申请并冻结的金额；provider_pay_amount = withdraw_amount - user_fee.val，云账户试算和后台审核通过后的批次 pay/total_pay 始终使用 provider_pay_amount，不能使用预计税后到账金额。
  • 申请时 tax_amount 和完整云账户试算结果写入审计快照，estimated_received_amount 从快照展示；actual_amount 支付成功前固定为 "0.00"，成功后以回调 user_real_amount 更新，失败、取消或退汇时归零。
  • 云账户明确拒绝批次下单时资金继续保持冻结，后台修复云账户配置后可复用原订单号重试；支付失败、取消、银行卡退汇或审核拒绝才按税前 withdraw_amount 全额解冻，资金流水通过 withdraw_no + change_type 幂等。
  • 提现单会保存所选账户的账户类型、实名姓名、账号、开户银行和开户支行快照；账户后续编辑或删除不影响历史提现单。
  • 同一艺人同一 Idempotency-Key 重复提交优先返回既有提现单；即使重试发生在提现窗口关闭、余额变化或账户已编辑/删除之后，也不会重复冻结余额。同一幂等键不可复用于不同金额或不同提现账户。
  • 后台审核通过后异步提交云账户，一笔提现固定映射一个单订单批次；财务在云账户后台人工确认支付，APP 状态由验签回调和主动查单推进。
  • 支付宝/微信成功后进入已完成；银行卡成功先保持打款中，观察 48 小时且主动查单仍成功才完成，退汇则进入失败并全额解冻。
  • 响应不返回账户号明文，仅返回 account_no_masked。