> For the complete documentation index, see [llms.txt](https://apidoc.xc-wallet.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://apidoc.xc-wallet.com/xcwallet-shang-hu-jie-kou-wen-dang.md).

# XCWallet商户接口文档

## 商户后台登录与 API 接入指南

### 一、登录商户后台

1. 联系运营人员获取以下信息（仅供测试使用）：
   * 商户后台链接
   * 登录账号
   * 登录密码
2. 登录后，点击右上角 **「API介面设置」** 进入接口配置页面。

<figure><img src="https://3105475244-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFzc4c8WUADwPZvmAsY55%2Fuploads%2FhN62lZZpSiZkgSmY9neX%2Fimage.png?alt=media&amp;token=0d202e60-bc67-4d79-ab77-97258581b3cf" alt=""><figcaption></figcaption></figure>

***

### 二、配置回调地址

1. 点击 **「获取 AccessKey」**。
2. 填写 **授权 IP 白名单**。
3. 输入 **谷歌验证码**。
4. 点击 **「提交」** 后生效。

<figure><img src="https://3105475244-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FFzc4c8WUADwPZvmAsY55%2Fuploads%2FEbakpzw3HG980vbjcwf6%2Fimage.png?alt=media&amp;token=3d605c4c-0454-4881-b446-a74469017ee9" alt=""><figcaption></figcaption></figure>

***

### 三、接口调用说明

#### 请求头设置

在请求 Header 中加入以下字段：

```
Authorization: Bearer {商户ID}
```

**示例：**

```
Authorization: Bearer 854498852339712
```

***

### 四、请求说明

* **强烈建议** 接入 **V2 接口**（V1 将逐步停用）。
* 已接入 V1 的商户可继续正常使用。
* V2 在 V1 基础上增加了 **加密传输机制**，加密方式详见 六、AES 加密说明。

**请求规范：**

* 请求方法：`POST`
* 字符编码：`UTF-8`
* 请求格式：`application/json`

***

### 五、回调说明

1. 仅 **成功订单** 会触发回调。
2. 回调地址以商户后台配置为准。
3. 回调失败将自动重试 **3 次**。
4. 回调请求方式：`POST`
5. 回调内容为 **AES 加密的 JSON 字符串**。

#### 示例：渠道代收回调

```json
{
  "sourceNo": "商户订单号",
  "data": "加密后的代收订单详情(具体参数参考 get 返回值)"
}
```

#### 示例：解密后的代收订单详情

```json
{
  "channelCreditOrderSimpleInfo": {
    "id": 1,
    "merchantId": 1,
    "merchantSourceNo": "text",
    "fiatAmount": 1,
    "tokenAmount": 1,
    "processCode": 0,
    "createdTime": 1,
    "updatedTime": 1,
    "cashierLink": "text",
    "payerAccountDetailList": [
      {
        "accountName": "text",
        "bankNo": "text",
        "bankAccount": "text"
      }
    ],
    "payeeAccountDetail": {
      "accountName": "text",
      "bankNo": "text",
      "bankAccount": "text"
    },
    "paid": true,
    "callbackCode": 0,
    "closedTime": 1
  }
}
```

***

### 六、AES 加密说明

| 参数项  | 说明          |
| ---- | ----------- |
| 运算模式 | ECB         |
| 填充模式 | PKCS7       |
| 秘钥长度 | 256 bits    |
| 秘钥   | 同 AccessKey |
| 字符编码 | UTF-8       |
| 输出格式 | Base64      |

#### 🔑 示例

| 项目   | 值                                  |
| ---- | ---------------------------------- |
| 原始值  | `Test`                             |
| 秘钥   | `ecb797f9e9feab0a92ab283978d33711` |
| 加密结果 | `M2SwiX1fxQ5aJ34scDi0zA==`         |

👉 可使用在线工具测试：[**AES 加密工具**](https://www.toolhelper.cn/SymmetricEncryption/AES)

***

### 七、风控要求

为满足平台风控与合规要求，**第三方商户在发起拉单请求前**，必须先调用 **`AdvisedAmount`** 接口以获取**推荐金额**。

* 推荐金额需在用户界面中 **明确展示**；
* 用户需 **自主确认并选择** 后方可继续拉单；
* 未经用户确认的 **自动拉单行为** 将被视为违规操作。

> 此机制旨在保障用户知情权与资金安全，确保交易过程合规可控。

***

### 八、接口文档与环境说明

#### 环境地址

| 环境   | Endpoint                        |
| ---- | ------------------------------- |
| 测试环境 | `https://mubiapi.xc-wallet.com` |
| 生产环境 | `https://mubiapi.xcwallet.net`  |

#### ⚠️ 上线前须完成以下事项

1. 联系运营人员获取 **生产环境商户后台链接**；
2. **重新申请并配置 AccessKey**；
3. 设置并验证 API设置；

> 以上配置完成并通过测试后，方可切换至生产环境进行业务操作。