0.使用模拟数据进行充值和提现
1.优化提现接口/api/finance/withdrawCreate 2.优化充值接口/api/finance/depositCreate
This commit is contained in:
@@ -452,19 +452,25 @@
|
||||
- `Content-Type: application/json`（推荐）、`application/x-www-form-urlencoded` 或 **`multipart/form-data`**（如 Apifox 的 form-data）；字段名与下表一致即可，服务端通过统一参数名读取，**不限制**为某一种 body 类型。
|
||||
|
||||
说明：
|
||||
- **仅支持 DDPay**：`channel_code` 必须为 **`ddpay`**，否则返回 `code=2004`。
|
||||
- `depositCreate` 先创建 `status=pending` 的充值单，再调用 DDPay「入金发起」；若成功返回 `payment_url`，则 `pay_url=payment_url`。
|
||||
- 入账由 **`POST /api/finance/ddpayDepositNotify`** 验签后结算，或网关同步返回 `transaction_status=completed` 时结算。
|
||||
- 档位与渠道取自 `depositTierList`：`channels` 中仅会出现 `ddpay`（与后台「支付/收款配置」一致）。
|
||||
- 同一用户最多 3 笔待支付充值单；创建后 60 秒未支付会超时失败。
|
||||
- **模拟支付（推荐联调）**：`channel_code=mock`，无需 DDPay 商户配置；创建后返回 `pay_url`（**模拟收银台页面** `GET /api/finance/mockDepositPage`，浏览器打开；**链接有效期 3 分钟**，过期未支付则订单自动失败）。用户在收银台点击「确认支付」后，订单进入 **`pending_review`（待后台审核）**，不会立即入账；管理员在后台「充值订单」审核通过后才入账。
|
||||
- 可选 **`GET/POST /api/finance/mockDepositPay`**（需登录，与创建订单同一 `auth-token`）：用于 App 内二次确认（与收银台确认二选一，幂等）。
|
||||
- **DDPay**：`channel_code=ddpay`；先创建待支付单，再调用 DDPay「入金发起」；若成功返回 `payment_url`，则 `pay_url=payment_url`。
|
||||
- 开关：`FINANCE_MOCK_PAY_ENABLED`（默认开发环境开启）；关闭后 `mock` 渠道不可用。
|
||||
- 入账由 **`POST /api/finance/ddpayDepositNotify`** 验签后结算，或网关同步返回 `transaction_status=completed` 时结算；**`mock` 渠道**在用户确认支付后需 **后台审核通过** 才调用入账结算。
|
||||
- 档位与渠道取自 `depositTierList`：`channels` 中会出现后台已启用的渠道（包含 `mock` / `ddpay` 等）。
|
||||
- 同一用户最多 3 笔待支付充值单；**待支付**订单创建后，超过 `DEPOSIT_PENDING_EXPIRE_SECONDS`（默认 **60 秒**，见 `.env`）未支付会自动失败；支付链接倒计时与此一致。
|
||||
|
||||
请求参数：
|
||||
|
||||
**A. 通用必填参数**
|
||||
- `tier_id`：string，必填（充值档位 ID；同义字段：`tier_key`）
|
||||
- `channel_code`：string，必填，固定传 **`ddpay`**
|
||||
- `channel_code`：string，必填，`mock`（模拟）或 `ddpay`（真实网关）
|
||||
- `idempotency_key`：string，必填，≤64（客户端幂等键，建议 UUID）
|
||||
|
||||
**A.1 模拟支付（`channel_code=mock`）**
|
||||
|
||||
- 无需 `payment_type` / `payer_name` / `payer_bank_name`
|
||||
|
||||
**B. DDPay 渠道必填参数（`channel_code=ddpay`）**
|
||||
|
||||
> **依据**：DDPay 官方《Payment Gateway》接口说明（与仓库内 `docs/DDPay Payment Gateway_v1.1.3_zh.md` / `docs/DDPay Payment Gateway_v1.1.3.pdf` 一致；以下「官方」均指该文档）。
|
||||
@@ -507,9 +513,13 @@
|
||||
- `bonus_amount`：string（2 位小数，含义：本次赠送金额，与所选档位 `bonus_amount` 一致，无赠送为 `0.00`）
|
||||
- `total_amount`：string（2 位小数，含义：实际入账总额 = amount + bonus_amount）
|
||||
- `pay_channel`：string（含义：支付通道标识，与请求中选择的 `channel_code` 一致，落库在订单上）
|
||||
- `paid`：bool（含义：当前单据是否已到账；`true` 表示钱包已入账、`status=paid`；`false` 表示待玩家在第三方支付页面完成支付）
|
||||
- `pay_url`：string（含义：DDPay 返回的收银台地址；**`paid=false`（待支付）** 时为三方 **`payment_url`（完整 URL）**；`paid=true` 时为空串）
|
||||
- `status`：string（`pending`/`paid`/`failed`，含义：本接口创建成功时为 `pending`，入账完成后为 `paid`）
|
||||
- `paid`：bool（含义：当前单据是否已到账；`true` 表示钱包已入账、`status=paid`；`false` 表示尚未入账；**`mock` 待审核**也为 `false`）
|
||||
- `pay_url`：string（含义：收银台地址；**`pending`（待支付）** 时：`ddpay` 为三方 **`payment_url`（完整 URL）**；**`mock` 为模拟收银台**（`GET /api/finance/mockDepositPage`）；**`paid=true` 或已进入待审核**时可能为空串）
|
||||
- `review_required`：bool（含义：是否需要后台审核入账；**仅 `mock` 在用户确认支付后**为 `true`）
|
||||
- `reject_reason`：string 或 null（含义：审核驳回原因；仅失败且存在驳回原因时有值）
|
||||
- `expire_at`：int 或 null（含义：`pay_url` 过期时间戳（秒）；主要用于 `mock` 待支付）
|
||||
- `expire_seconds`：int 或 null（含义：与 `expire_at` 配套，待支付时返回，值同 `DEPOSIT_PENDING_EXPIRE_SECONDS`）
|
||||
- `status`：string（`pending` / `pending_review` / `paid` / `failed`，含义：`pending`=待支付；`pending_review`（仅 mock）=用户已确认，等待后台审核；`paid`=已入账；`failed`=失败/超时/驳回）
|
||||
- `create_time`：int（含义：订单创建时间，秒级时间戳）
|
||||
- `pay_time`：int（含义：订单到账时间，未到账为 0）
|
||||
|
||||
@@ -539,9 +549,17 @@
|
||||
- `1002`：`idempotency_key` 过长，或与其他玩家的订单冲突
|
||||
- `2000`：**通用**：订单落库或入账失败（事务回滚等，可能带原始错误描述）；**DDPay**：调用「入金发起」失败（网络/HTTP/JSON/验签/`status_code≠0` 等），对外文案为「DDPay 充值发起失败」，**具体原因可查看该笔 `deposit_order.remark`（前缀 `[ddpay]`）或服务端日志**
|
||||
- `2003`：所选 `tier_id` 不存在、已停用或不在启用列表中
|
||||
- `2004`：`channel_code` 非 `ddpay`；或 `ddpay` 未启用；或当前档位币种与该渠道不允许的组合
|
||||
- `2004`：不支持的 `channel_code`；`mock` 已关闭；或 `ddpay` 未启用；或当前档位币种与该渠道不允许的组合
|
||||
- `2005`：待支付充值单超过上限（`data.max_pending`、`data.pending_count`、`data.expire_seconds`）
|
||||
|
||||
### 5.4A 模拟支付（浏览器收银台 + 可选 App 确认）
|
||||
|
||||
- **GET/POST** `/api/finance/mockDepositPage`：模拟收银台 HTML 页面（**无需登录**；`order_no` 必填；仅 `pay_channel=mock` 且 `status=pending` 且未过期可展示支付按钮）
|
||||
- **GET/POST** `/api/finance/mockDepositConfirm`：收银台内确认支付（**无需登录**；将订单标记为 **`pending_review`**，不入账）
|
||||
- **GET/POST** `/api/finance/mockDepositPay`：App 内确认（**需登录**；与上一接口二选一、幂等）
|
||||
|
||||
说明：后台管理员在 **「充值订单」** 对待审核单执行审核通过/驳回后，`mock` 订单才会最终成功入账或失败（未接入真实商户前的模拟流程）。
|
||||
|
||||
### 5.5 查看充值订单详情
|
||||
- **POST** `/api/finance/depositDetail`
|
||||
|
||||
@@ -555,8 +573,12 @@
|
||||
- `total_amount`：string（2 位小数，含义：入账总额）
|
||||
- `pay_channel`：string（含义：支付通道标识）
|
||||
- `paid`：bool（含义：是否已到账）
|
||||
- `pay_url`：string（含义：第三方支付页面地址，已到账为空串）
|
||||
- `status`：string（`pending`/`paid`/`failed`）
|
||||
- `pay_url`：string（含义：收银台地址；已到账或无需再支付时可能为空串）
|
||||
- `review_required`：bool（含义：是否等待后台审核入账）
|
||||
- `reject_reason`：string 或 null（含义：驳回原因）
|
||||
- `expire_at`：int 或 null（含义：`pay_url` 过期时间戳（秒））
|
||||
- `expire_seconds`：int 或 null（含义：与 `expire_at` 配套）
|
||||
- `status`：string（`pending` / `pending_review` / `paid` / `failed`）
|
||||
- `create_time`：int（含义：订单创建时间）
|
||||
- `pay_time`：int（含义：订单到账时间，未到账为 0）
|
||||
|
||||
@@ -574,7 +596,7 @@
|
||||
- `order_no`：string（含义：充值订单号）
|
||||
- `amount`：string（2 位小数，含义：本单充值金额）
|
||||
- `bonus_amount`：string（2 位小数，含义：本单赠送金额，无赠送为 `0.00`）
|
||||
- `status`：string（含义：订单状态，与 `depositDetail` 一致：`pending`/`paid`/`failed`）
|
||||
- `status`：string（含义：订单状态，与 `depositDetail` 一致：`pending` / `pending_review` / `paid` / `failed`）
|
||||
- `pagination`：object（含义：分页信息）
|
||||
- `page`：int（含义：当前页码）
|
||||
- `page_size`：int（含义：每页数量）
|
||||
|
||||
Reference in New Issue
Block a user