# 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&#x26;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&#x26;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设置；

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://apidoc.xc-wallet.com/xcwallet-shang-hu-jie-kou-wen-dang.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.