充值渠道（Deposit Channel）接入文档

一、说明

充值渠道用于配置用户充值时可选的支付渠道。每个「提供商 + 支付方式」组合是一条独立渠道，例如 jaya 的 QRIS、jaya 的 BRI 算两条；有些渠道（如 futurepay）在渠道商侧选择方式，不需要额外参数。

单表 deposit_channels，每行包含：内部名、显示名、提供商（pay_type）、创建参数（params，如 {"method":"QRIS"}）、单笔 min/max 限额、排序、启停。

接入方分两类：

• 用户端（App / H5）：传要购买的硬币数，后端换算成 IDR 金额后，返回当前金额可用的渠道列表，前端展示给用户选择，再按返回的 pay_type 调用对应的下单接口。
• 管理后台：对充值渠道做完整 CRUD。

前端使用流程

1. 调 POST /v1/order/deposit/channel/list，传 {"coins": 购买的硬币数}。
2. 拿到可用渠道列表（已按金额过滤、sort 降序）。每条渠道含 pay_type + display_name + params。
3. 用户选定某渠道后，按 pay_type 映射到对应的下单接口，并把 params 里的参数转发过去：

渠道列表接口与下单是分离的：列表只负责「告诉前端有哪些渠道、用哪个接口、带什么参数」，实际下单仍走各自原有的 create 接口。

通用约定

• 所有接口均为 HTTP POST，请求 / 响应体为 JSON。
• 统一响应外层包裹： json { "code": 200, "message": "success", "data": { ... } } 成功 code=200；空响应（create/update/delete）成功时 data 为 {}。
• 金额单位为 IDR（印尼盾）整数；min_amount / max_amount 为 0 表示不限。
• pay_type 枚举在 JSON 中可传字符串名（"PAY_TYPE_JAYA"）或数字值（15），响应默认返回字符串名。
• params 为字符串字典 map<string,string>，空为 {}。

金额换算（用户端筛选逻辑）

后端取汇率参数 WealthParameter，按下式把硬币数换算成 IDR 再与渠道 min/max 比较：

idr = floor( coins × RateCoinsToUs × RateUsToInd )

只返回 is_disabled=false 且 idr 落在 [min_amount, max_amount]（0=不限）内的渠道，按 sort 降序（越大越靠前）。

鉴权头

二、用户端接口

1. 列出可用充值渠道

• POST /v1/order/deposit/channel/list

请求：

响应 data：

{
  "channels": [
    {
      "pay_type": "PAY_TYPE_JAYA",
      "display_name": "QRIS",
      "params": { "method": "QRIS" },
      "min_amount": 0,
      "max_amount": 5000000
    },
    {
      "pay_type": "PAY_TYPE_UNISPAY",
      "display_name": "E-Wallet",
      "params": { "pay_type": "6211" },
      "min_amount": 0,
      "max_amount": 0
    }
  ]
}

字段说明（DepositChannelOption）：

内部名 name、is_disabled、时间戳等不下发给用户端。

三、管理后台接口

1. 列表 — POST /v1/man/deposit/channel/list

响应 data： { "total": 5, "channels": [ <DepositChannel>, ... ] }，按 sort 降序、再 id 升序。

2. 新增 — POST /v1/man/deposit/channel/create

响应 data：{}

pay_type 白名单（仅这些有对应下单接口，其余拒绝）：PAY_TYPE_JAYA、PAY_TYPE_UNISPAY、PAY_TYPE_FUTUREPAY、PAY_TYPE_HAIPAY、PAY_TYPE_MONETA_PAY、PAY_TYPE_STRIPE。

3. 更新 — POST /v1/man/deposit/channel/update

字段同 create，额外必填 id（int64，>0）。整体覆盖各字段（含 params，传空则覆盖为 {}）。id 不存在返回未找到错误。响应 data：{}

4. 删除 — POST /v1/man/deposit/channel/delete

物理删除。响应 data：{}

四、模型字段说明

DepositChannel（后台列表/详情返回）

pay_type 枚举（复用 Order.PayType，仅充值相关）

PAY_TYPE_UNKNOWN(0) 仅用于后台列表「不按提供商过滤」，不可用于新增 / 更新。

五、初始化数据

迁移在空表时写入以下 5 条（min/max 均为 0=不限，is_disabled=false）：

六、接口一览