> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oristapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ISV 交易 API

## 概述

本套 API 供 **ISV 客户** 完成 [Onboarding](./onboarding-api) 后调用，代其终端客户完成转账、收款、Payout、银行账户管理等日常交易操作。

ISV 调用时传入 `walletId`，OristaPay 会按 ISV ↔ 商户的归属关系自动完成鉴权。**交易接口字段零变更**。

## 鉴权与签名

所有接口均需携带签名请求头，详见 [认证与签名](./auth)。

## 接口索引

| #  | 接口                   | REST 路径                                    |
| -- | -------------------- | ------------------------------------------ |
| 1  | 静态收款地址查询             | `POST /api/v1/wallet/static-address/query` |
| 2  | 查询支持币种               | `POST /api/v1/wallet/supported/currencies` |
| 3  | Request Payment 订单申报 | `POST /api/v1/payment/order/declare`       |
| 4  | 订单材料补充               | `POST /api/v1/payment/order/add/materials` |
| 5  | 划拨                   | `POST /api/v1/payment/internal-transfer`   |
| 6  | 订单详情                 | `POST /api/v1/payment/order/detail`        |
| 7  | 订单列表                 | `POST /api/v1/payment/order/list`          |
| 8  | 对账单下载                | `POST /api/v1/payment/reconciliation`      |
| 9  | 添加收款账号               | `POST /api/v1/wallet/bank_account/add`     |
| 10 | 更新收款账号               | `POST /api/v1/wallet/bank_account/update`  |
| 11 | 删除收款账号               | `POST /api/v1/wallet/bank_account/del`     |
| 12 | 查询收款账号               | `POST /api/v1/wallet/bank_account/get`     |
| 13 | Payout 询价            | `POST /api/v1/payout/quote`                |
| 14 | Payout 下单            | `POST /api/v1/payout/book`                 |
| 15 | Payout 订单查询          | `POST /api/v1/payout/enquiry`              |
| 16 | Payout 重新结算          | `POST /api/v1/payout/reSettle`             |
| 17 | 订单结果通知               | Webhook                                    |
| 18 | 添加收款账号结果通知           | Webhook                                    |
| 19 | Payout 结果通知          | Webhook                                    |
| 20 | Payout 退款结果通知        | Webhook                                    |
| 21 | Payout 重新结算结果通知      | Webhook                                    |

# 收付款与转账

### 1. 静态收款地址查询

查询指定钱包的 Request Payment 静态收款地址。

**请求参数**

| 参数名        | 类型       | 是否必填 | 描述                                   |
| ---------- | -------- | ---- | ------------------------------------ |
| `walletId` | `int64`  | 是    | 钱包 ID                                |
| `network`  | `string` | 否    | 区块链网络：`ETH` / `TRX` / `SOL` / `POLY` |
| `currency` | `string` | 否    | 币种：`USDT` / `USDC`                   |

**响应参数**

| 参数名       | 类型                         | 描述     |
| --------- | -------------------------- | ------ |
| `code`    | `int32`                    | 业务码    |
| `message` | `string`                   | 业务消息   |
| `data`    | `Array<StaticAddressData>` | 静态地址列表 |

`StaticAddressData` 字段：

| 字段名            | 类型       | 描述                                                                  |
| -------------- | -------- | ------------------------------------------------------------------- |
| `walletId`     | `int64`  | 钱包 ID                                                               |
| `network`      | `string` | 区块链网络，如 `ETH` / `TRX`                                               |
| `currency`     | `string` | 币种，如 `USDT` / `USDC`                                                |
| `address`      | `string` | 静态收款地址                                                              |
| `qrCodeBase64` | `string` | 该地址的二维码图片，Base64 编码，含 `data:image/png;base64,` 前缀，可直接放入 `<img src>` |

**请求示例**

```json theme={null}
{
  "walletId": 123456789,
  "network": "ETH",
  "currency": "USDT"
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success",
  "data": [
    {
      "walletId": 123456789,
      "network": "ETH",
      "currency": "USDT",
      "address": "0x9f8b2c1d4e5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c",
      "qrCodeBase64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ]
}
```

### 2. 查询支持币种

按 `walletId + type` 查询该钱包在指定业务类型下支持的币种、可用网络、单笔金额范围与币种精度。调用方可用该接口在创建入金 / 出金订单前做前置校验，避免提交未开通或超出限额的币种组合。

**请求参数**

| 参数名        | 类型       | 是否必填 | 描述                                           |
| ---------- | -------- | ---- | -------------------------------------------- |
| `walletId` | `int64`  | 是    | 钱包 ID                                        |
| `type`     | `string` | 是    | 业务类型 / 限额类型：`4` 入金（deposit），`3` 提币（withdraw） |

**响应参数**

| 参数名       | 类型                                    | 描述                    |
| --------- | ------------------------------------- | --------------------- |
| `code`    | `int32`                               | 业务码                   |
| `message` | `string`                              | 业务消息                  |
| `data`    | `Array<SupportedCurrenciesQueryData>` | 支持币种列表；`code = 1` 时返回 |

`SupportedCurrenciesQueryData` 字段：

| 字段名         | 类型              | 说明                                    |
| ----------- | --------------- | ------------------------------------- |
| `type`      | `int32`         | 业务类型 / 限额类型，与请求 `type` 对应             |
| `currency`  | `string`        | 币种，如 `USDT` / `USDC` / `USD`          |
| `minAmount` | `string`        | 单笔最小金额，字符串形式的十进制数                     |
| `maxAmount` | `string`        | 单笔最大金额，字符串形式的十进制数                     |
| `networks`  | `Array<string>` | 该币种支持的区块链网络列表，如 `ETH` / `TRX` / `SOL` |
| `precision` | `int32`         | 金额精度，小数位数                             |

**请求示例**

```json theme={null}
{
  "walletId": 123456789,
  "type": 1
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success",
  "data": [
    {
      "type": 4,
      "currency": "USDT",
      "minAmount": "10",
      "maxAmount": "50000",
      "networks": ["ETH", "TRX"],
      "precision": 6
    },
    {
      "type": 4,
      "currency": "USDC",
      "minAmount": "10",
      "maxAmount": "50000",
      "networks": ["ETH", "SOL"],
      "precision": 6
    }
  ]
}
```

### 3. Request Payment 订单申报

申报 Request Payment 入金订单。

**请求参数**

| 参数名              | 类型                | 是否必填 | 描述                            |
| ---------------- | ----------------- | ---- | ----------------------------- |
| `walletId`       | `int64`           | 是    | 入金钱包 ID                       |
| `extOrderNo`     | `string`          | 是    | 外部订单 ID，全局唯一                  |
| `senderAddress`  | `string`          | 是    | 付款方钱包地址                       |
| `network`        | `string`          | 是    | 网络：`ETH` / `TRX`              |
| `currency`       | `string`          | 是    | 币种：`USDT` / `USDC`            |
| `amount`         | `string`          | 是    | 申报金额，需与最终入金金额完全匹配             |
| `senderName`     | `string`          | 是    | 付款方名称                         |
| `countryRegion`  | `string`          | 是    | 付款方国家/地区 ISO 3166 编码（如 `HKG`） |
| `contactAddress` | `string`          | 是    | 付款方联系住址                       |
| `receiverName`   | `string`          | 是    | 收款商户名称                        |
| `message`        | `string`          | 否    | 附言                            |
| `materials`      | `Array<Material>` | 否    | 订单还原材料申报对象集合                  |

`Material` 字段：

| 参数名                     | 类型       | 是否必填 | 描述     |
| ----------------------- | -------- | ---- | ------ |
| `productType`           | `string` | 是    | 商品类型   |
| `productName`           | `string` | 是    | 商品名称   |
| `productPrice`          | `string` | 是    | 商品价格   |
| `productCount`          | `string` | 是    | 商品数量   |
| `productUnit`           | `string` | 是    | 商品单位   |
| `logisticsTrackingName` | `string` | 否    | 物流公司名称 |
| `logisticsTrackingNo`   | `string` | 否    | 物流单号   |

**响应参数**

| 参数名       | 类型       | 描述   |
| --------- | -------- | ---- |
| `code`    | `int32`  | 业务码  |
| `message` | `string` | 业务消息 |

**请求示例**

```json theme={null}
{
  "walletId": "429883231600640",
  "extOrderNo": "1747626211614",
  "senderAddress": "0x213F2B229BE4f3FFF88fc874a986b19D79623339",
  "network": "ETH",
  "currency": "USDC",
  "amount": "150",
  "senderName": "Reflective Method Invocation",
  "countryRegion": "HKG",
  "contactAddress": "contact address hong kong",
  "receiverName": "Reflective Method Invocation",
  "message": "request payment msg",
  "materials": [
    {
      "productType": "Electronics",
      "productName": "Wireless Bluetooth Headphones",
      "productPrice": "89.99",
      "productCount": "150",
      "productUnit": "pcs",
      "logisticsTrackingName": "FedEx International Priority",
      "logisticsTrackingNo": "FX123456789US"
    }
  ]
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success"
}
```

### 4. Request Payment 订单材料补充

为已申报的订单补充商品/物流材料。

**请求参数**

| 参数名         | 类型                | 是否必填 | 描述         |
| ----------- | ----------------- | ---- | ---------- |
| `walletId`  | `int64`           | 是    | 入金钱包 ID    |
| `orderNo`   | `string`          | 是    | RD 订单号     |
| `materials` | `Array<Material>` | 否    | 订单还原材料对象集合 |

`Material` 字段同「1. Request Payment 订单申报」。

**响应参数**

| 参数名       | 类型       | 描述   |
| --------- | -------- | ---- |
| `code`    | `int32`  | 业务码  |
| `message` | `string` | 业务消息 |

**请求示例**

```json theme={null}
{
  "walletId": "429883231600640",
  "orderNo": "447767487604736",
  "materials": [
    {
      "productType": "Electronics",
      "productName": "Wireless Bluetooth Headphones",
      "productPrice": "89.99",
      "productCount": "150",
      "productUnit": "pcs",
      "logisticsTrackingName": "FedEx International Priority",
      "logisticsTrackingNo": "FX123456789US"
    }
  ]
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success"
}
```

### 5. 划拨

钱包内部托管资产 → 交易资产的划拨。

**请求参数**

| 参数名                    | 类型       | 是否必填 | 描述                                                                |
| ---------------------- | -------- | ---- | ----------------------------------------------------------------- |
| `walletId`             | `int64`  | 是    | 钱包 ID                                                             |
| `internalTransferType` | `int32`  | 是    | 划拨类型：`1` 托管资产 → 交易资产                                              |
| `network`              | `string` | 条件   | 来源资产网络：`ETH` / `TRX` / `SOL` / `POLY`，`internalTransferType=1` 必填 |
| `currency`             | `string` | 是    | 币种：`USDT` / `USDC`                                                |
| `amount`               | `string` | 是    | 金额                                                                |
| `extOrderNo`           | `string` | 是    | 外部订单 ID，全局唯一                                                      |

**响应参数**

| 参数名       | 类型                     | 描述   |
| --------- | ---------------------- | ---- |
| `code`    | `int32`                | 业务码  |
| `message` | `string`               | 业务消息 |
| `data`    | `InternalTransferData` | 划拨结果 |

`InternalTransferData` 字段：

| 字段名       | 类型       | 描述    |
| --------- | -------- | ----- |
| `orderNo` | `string` | 划拨订单号 |

**请求示例**

```json theme={null}
{
  "walletId": 1001,
  "internalTransferType": 1,
  "network": "ETH",
  "currency": "USDT",
  "amount": "1.0",
  "extOrderNo": "EXT123456789"
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success",
  "data": {
    "orderNo": "ORDER123456789"
  }
}
```

### 6. 订单详情

按订单号或外部订单号查询钱包订单详情。

**请求参数**

| 参数名          | 类型       | 是否必填 | 描述                                 |
| ------------ | -------- | ---- | ---------------------------------- |
| `orderNo`    | `string` | 条件   | RD 订单号                             |
| `extOrderNo` | `string` | 条件   | 外部订单号；`orderNo` / `extOrderNo` 二选一 |

**响应参数**

| 参数名       | 类型                      | 描述   |
| --------- | ----------------------- | ---- |
| `code`    | `int32`                 | 业务码  |
| `message` | `string`                | 业务消息 |
| `data`    | `WalletOrderDetailData` | 订单详情 |

`WalletOrderDetailData` 字段：

| 字段名           | 类型       | 描述                 |
| ------------- | -------- | ------------------ |
| `orderNo`     | `string` | RD 订单号             |
| `extOrderNo`  | `string` | 外部订单号              |
| `orderType`   | `int32`  | 订单类型               |
| `orderStatus` | `string` | 见附录【入金订单状态】        |
| `fromAddress` | `string` | 发起方地址              |
| `fromWallet`  | `string` | 来源钱包               |
| `toAddress`   | `string` | 接收方地址              |
| `toWallet`    | `string` | 目标钱包               |
| `amount`      | `string` | 金额                 |
| `network`     | `string` | 网络：`ETH` / `TRX`   |
| `currency`    | `string` | 币种：`USDT` / `USDC` |
| `expireTime`  | `int64`  | 订单过期时间             |
| `createTime`  | `int64`  | 订单创建时间             |

**请求示例**

```json theme={null}
{
  "orderNo": "ORDER123456789"
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success",
  "data": {
    "orderNo": "447767487604736",
    "extOrderNo": "1744341998597",
    "orderType": 4,
    "orderStatus": "SUCCESS",
    "fromAddress": "0x213F2B229BE4f3FFF88fc874a986b19D79623339",
    "toAddress": "0xc496E20b19F009543E49b8512CB990ceb0a230F0",
    "toWallet": "429883231600640",
    "amount": "17",
    "network": "ETH",
    "currency": "USDT",
    "expireTime": 1744342629783,
    "createTime": 1744343297296
  }
}
```

### 7. 订单列表

按 `walletId` 分页查询钱包订单列表，可通过订单状态、币种和创建时间范围进行筛选。返回的订单数据使用钱包订单统一结构，适合用于订单列表页、对账前置查询或按状态轮询订单进度。

**请求参数**

| 参数名          | 类型       | 是否必填 | 说明                                                                   |
| ------------ | -------- | ---- | -------------------------------------------------------------------- |
| `walletId`   | `int64`  | 是    | 钱包 ID（必须归属当前 API Key 对应的企业，或其名下的 ISV 子企业）                            |
| `status`     | `string` | 否    | 订单状态；不传则查询全部状态                                                       |
| `currency`   | `string` | 否    | 币种，如 `USDT` / `USDC`                                                 |
| `startTime`  | `string` | 否    | 查询开始时间，按订单创建时间过滤；格式为 ISO8601 with timezone，例如 `2026-01-01T00:00:00Z` |
| `endTime`    | `string` | 否    | 查询结束时间，按订单创建时间过滤；格式为 ISO8601 with timezone，例如 `2026-01-01T00:00:00Z` |
| `pageNumber` | `int32`  | 是    | 页码，从 `1` 开始                                                          |
| `pageSize`   | `int32`  | 是    | 每页数量，默认 `20`，最大支持 `100`，超过 `100` 按 `100` 处理                          |

**响应参数**

| 参数名       | 类型                             | 说明                  |
| --------- | ------------------------------ | ------------------- |
| `code`    | `int32`                        | 业务码：`1` 成功，其它见错误码   |
| `message` | `string`                       | 业务消息                |
| `data`    | `Array<WalletOrderDetailData>` | 订单列表；`code = 1` 时返回 |
| `page`    | `Page`                         | 分页信息                |

`Page` 字段：

| 字段名            | 类型      | 说明   |
| -------------- | ------- | ---- |
| `pageNumber`   | `int32` | 当前页码 |
| `pageSize`     | `int32` | 每页数量 |
| `totalPages`   | `int32` | 总页数  |
| `totalRecords` | `int32` | 总记录数 |

`WalletOrderDetailData` 字段：

| 字段名           | 类型       | 描述                  |
| ------------- | -------- | ------------------- |
| `orderNo`     | `string` | 订单号                 |
| `extOrderNo`  | `string` | 外部订单号               |
| `orderType`   | `int32`  | 订单类型                |
| `orderStatus` | `string` | 见附录【入金订单状态】         |
| `fromAddress` | `string` | 发起方地址               |
| `fromWallet`  | `string` | 来源钱包                |
| `toAddress`   | `string` | 接收方地址               |
| `toWallet`    | `string` | 目标钱包                |
| `amount`      | `string` | 金额                  |
| `network`     | `string` | 区块链网络：`ETH` / `TRX` |
| `currency`    | `string` | 币种：`USDT` / `USDC`  |
| `expireTime`  | `int64`  | 订单过期时间              |
| `createTime`  | `int64`  | 订单创建时间              |

**请求示例**

```json theme={null}
{
  "walletId": 519309997363200,
  "status": "SUCCESS,IN_PROGRESS",
  "currency": "USDT",
  "startTime": "2026-01-01T00:00:00Z",
  "endTime": "2026-01-31T23:59:59Z",
  "pageNumber": 1,
  "pageSize": 20
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success",
  "data": [
    {
      "orderNo": "447767487604736",
      "extOrderNo": "1744341998597",
      "orderType": 4,
      "orderStatus": "SUCCESS",
      "fromAddress": "0x213F2B229BE4f3FFF88fc874a986b19D79623339",
      "fromWallet": "123456",
      "toAddress": "0xc496E20b19F009543E49b8512CB990ceb0a230F0",
      "toWallet": "429883231600640",
      "amount": "17",
      "network": "ETH",
      "currency": "USDT",
      "expireTime": 1744342629783,
      "createTime": 1744343297296
    }
  ],
  "page": {
    "pageNumber": 1,
    "pageSize": 20,
    "totalPages": 1,
    "totalRecords": 1
  }
}
```

### 8. 对账单下载

每日上午 9 点可提供 D-1 日对账单下载（时区：香港 UTC+8）。

**请求参数**

| 参数名            | 类型       | 是否必填 | 描述                                                                                                                                                |
| -------------- | -------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `walletId`     | `int64`  | 是    | 钱包 ID                                                                                                                                             |
| `billDate`     | `string` | 是    | 账单日期，格式：`yyyyMMdd`                                                                                                                                |
| `modeType`     | `int32`  | 是    | 授权模式：`1` 直连模式 / `2` 授权模式（含子钱包）                                                                                                                    |
| `accountType`  | `int32`  | 是    | 账户类型：`1` 存管账户 / `2` 交易账户                                                                                                                          |
| `currencyType` | `int32`  | 是    | 币种类型：`1` ETH-USDT / `2` ETH-USDC / `3` TRX-USDT / `4` USDT / `5` USDC / `6` USD / `14` SOL-USDC / `15` SOL-USDT / `16` POLY-USDC / `17` POLY-USDT |

**响应参数**

| 参数名       | 类型               | 描述    |
| --------- | ---------------- | ----- |
| `code`    | `int32`          | 业务码   |
| `message` | `string`         | 业务消息  |
| `data`    | `WalletBillData` | 对账单信息 |

`WalletBillData` 字段：

| 字段名        | 类型       | 描述            |
| ---------- | -------- | ------------- |
| `fileName` | `string` | 文件名称          |
| `fileUrl`  | `string` | 对账单 zip 包下载地址 |

**请求示例**

```json theme={null}
{
  "walletId": 123456789,
  "billDate": "20250330",
  "modeType": 1,
  "accountType": 1,
  "currencyType": 1
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "success",
  "data": {
    "fileName": "20231123_123456789_Statement_ETHUSDT.zip",
    "fileUrl": "https://hk-pro-wallet-private-oss.oss-cn-hongkong.aliyuncs.com/thirdpartybilling/1737925914987610112.zip"
  }
}
```

# 银行账户管理

| Path                                 | Request                    | Response                 |
| ------------------------------------ | -------------------------- | ------------------------ |
| `/api/v1/wallet/bank_account/add`    | `AddBankAccountRequest`    | `BankAccountResponse`    |
| `/api/v1/wallet/bank_account/update` | `UpdateBankAccountRequest` | `BankAccountResponse`    |
| `/api/v1/wallet/bank_account/del`    | `DelBankAccountRequest`    | `DelBankAccountResponse` |
| `/api/v1/wallet/bank_account/get`    | `GetBankAccountRequest`    | `GetBankAccountResponse` |

> 以下接口共享 `BankAccountData` 与 `FileInfo` 定义。

`BankAccountData` 字段：

| 字段名                     | 类型                | 描述                                          |
| ----------------------- | ----------------- | ------------------------------------------- |
| `settlementAccountUID`  | `int64`           | 结算账户标识                                      |
| `walletId`              | `int64`           | 钱包 ID                                       |
| `alias`                 | `string`          | 别名                                          |
| `accountOwnership`      | `int32`           | 与钱包关系：`1` own / `2` other / `3` Third party |
| `currency`              | `string`          | 币种：`USD`                                    |
| `accountType`           | `int32`           | 账户类型：`1` RD Wallet / `2` Bank Account       |
| `companyName`           | `string`          | 公司名称                                        |
| `accountNumber`         | `string`          | 账号（RD Wallet ID 或 Bank Number）              |
| `bankId`                | `string`          | 香港银行 ID，例如 `003`                            |
| `beneficiaryAddress1`   | `string`          | 收款方地址 1（不允许中文）                              |
| `beneficiaryAddress2`   | `string`          | 收款方地址 2（不允许中文）                              |
| `beneficiaryAddress3`   | `string`          | 收款方地址 3：国家/地区 ISO 3166 编码                   |
| `beneficiarySwiftCode`  | `string`          | 银行 Swift Code                               |
| `intermediarySwiftCode` | `string`          | 中间银行 Swift Code                             |
| `companyCode`           | `string`          | 企业编码                                        |
| `status`                | `int32`           | 状态：`0` 处理中 / `1` 成功 / `2` 失败                |
| `paymentFiles`          | `Array<FileInfo>` | 支付证明文件                                      |
| `remark`                | `string`          | 备注                                          |

`FileInfo` 字段：

| 字段名        | 类型       | 描述                       |
| ---------- | -------- | ------------------------ |
| `fileKey`  | `string` | 文件 ID（上传接口返回）            |
| `fileName` | `string` | 文件名称                     |
| `fileUrl`  | `string` | 文件 URL（上传接口返回，URL 会定期更新） |

### 9. 添加收款账号

**请求参数**

| 参数名                     | 类型                | 是否必填 | 描述                                                   |
| ----------------------- | ----------------- | ---- | ---------------------------------------------------- |
| `walletId`              | `int64`           | 是    | 钱包 ID                                                |
| `alias`                 | `string`          | 是    | 别名                                                   |
| `accountOwnership`      | `int32`           | 是    | `1` own / `2` other / `3` Third party                |
| `currency`              | `string`          | 是    | 币种：`USD`                                             |
| `accountType`           | `int32`           | 是    | `1` RD Wallet / `2` Bank Account                     |
| `companyName`           | `string`          | 是    | 公司名称（`accountOwnership=2` 时必须与 `companyCode` 对应公司一致） |
| `accountNumber`         | `string`          | 是    | 账号                                                   |
| `bankId`                | `string`          | 是    | 香港银行 ID，例如 `003`                                     |
| `beneficiaryAddress1`   | `string`          | 条件   | `accountType=2` 必填                                   |
| `beneficiaryAddress2`   | `string`          | 条件   | `accountType=2` 必填                                   |
| `beneficiaryAddress3`   | `string`          | 条件   | `accountType=2` 必填，国家/地区 ISO 3166                    |
| `beneficiarySwiftCode`  | `string`          | 条件   | `accountType=2` 必填，必须是 HK 地区                         |
| `intermediarySwiftCode` | `string`          | 否    | 中间银行 Swift Code，必须是 HK 地区                            |
| `companyCode`           | `string`          | 条件   | `accountOwnership=2` 必填                              |
| `paymentFiles`          | `Array<FileInfo>` | 条件   | `accountOwnership=3` 必填                              |
| `remark`                | `string`          | 否    | 备注，`accountOwnership=3` 选填                           |

**响应参数**

| 参数名       | 类型                | 描述   |
| --------- | ----------------- | ---- |
| `code`    | `int32`           | 业务码  |
| `message` | `string`          | 业务消息 |
| `data`    | `BankAccountData` | 账户信息 |

**请求示例**

```json theme={null}
{
  "walletId": 4298832316123456,
  "alias": "name alias",
  "accountOwnership": 2,
  "currency": "USD",
  "accountType": 2,
  "companyName": "narti adiddf",
  "accountNumber": "8888888",
  "bankId": "003",
  "beneficiaryAddress1": "payee address1",
  "beneficiaryAddress2": "payee address2",
  "beneficiaryAddress3": "HK",
  "beneficiarySwiftCode": "DHBKHKHHXXX",
  "intermediarySwiftCode": "DHBKHKHHXXX",
  "companyCode": "HK1239876654",
  "paymentFiles": [
    {
      "fileKey": "file_key_123",
      "fileName": "证明文件.pdf"
    }
  ],
  "remark": "备注信息"
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success",
  "data": {
    "settlementAccountUID": 1236547995462114,
    "walletId": 4298832316123456,
    "alias": "name alias",
    "accountOwnership": 2,
    "currency": "USD",
    "accountType": 2,
    "companyName": "narti adiddf",
    "accountNumber": "8888888",
    "bankId": "003",
    "beneficiaryAddress1": "payee address1",
    "beneficiaryAddress2": "payee address2",
    "beneficiaryAddress3": "HK",
    "beneficiarySwiftCode": "DHBKHKHHXXX",
    "intermediarySwiftCode": "DHBKHKHHXXX",
    "companyCode": "HK1239876654",
    "status": 0,
    "paymentFiles": [
      {
        "fileKey": "file_key_123",
        "fileName": "证明文件.pdf",
        "fileUrl": "https://xxxxx"
      }
    ],
    "remark": "备注信息"
  }
}
```

### 10. 更新收款账号

仅可更新非关键字段；`accountOwnership` / `currency` / `accountType` / `companyName` / `companyCode` 不在更新范围内。

**请求参数**

| 参数名                     | 类型                | 是否必填 | 描述                         |
| ----------------------- | ----------------- | ---- | -------------------------- |
| `walletId`              | `int64`           | 是    | 钱包 ID                      |
| `settlementAccountUID`  | `int64`           | 是    | 结算账户标识                     |
| `alias`                 | `string`          | 否    | 别名                         |
| `accountNumber`         | `string`          | 否    | 账号                         |
| `bankId`                | `string`          | 否    | 香港银行 ID                    |
| `beneficiaryAddress1`   | `string`          | 否    | 收款方地址 1                    |
| `beneficiaryAddress2`   | `string`          | 否    | 收款方地址 2                    |
| `beneficiaryAddress3`   | `string`          | 否    | 收款方地址 3                    |
| `beneficiarySwiftCode`  | `string`          | 否    | Swift Code（HK 地区）          |
| `intermediarySwiftCode` | `string`          | 否    | 中间银行 Swift Code（HK 地区）     |
| `paymentFiles`          | `Array<FileInfo>` | 条件   | `accountOwnership=3` 必填    |
| `remark`                | `string`          | 否    | 备注，`accountOwnership=3` 选填 |

**响应参数**：与「9. 添加收款账号」相同，`data` 为 `BankAccountData`。

**请求示例**

```json theme={null}
{
  "settlementAccountUID": 1236547995462114,
  "walletId": 4298832316123456,
  "alias": "name alias",
  "accountNumber": "8888888",
  "bankId": "003",
  "beneficiaryAddress1": "payee address1",
  "beneficiaryAddress2": "payee address2",
  "beneficiaryAddress3": "HK",
  "beneficiarySwiftCode": "DHBKHKHHXXX",
  "intermediarySwiftCode": "DHBKHKHHXXX",
  "paymentFiles": [
    {
      "fileKey": "file_key_123",
      "fileName": "证明文件.pdf"
    }
  ],
  "remark": "备注信息"
}
```

**响应示例**：结构与「9. 添加收款账号」响应示例一致。

### 11. 删除收款账号

**请求参数**

| 参数名                    | 类型       | 是否必填 | 描述     |
| ---------------------- | -------- | ---- | ------ |
| `walletId`             | `int64`  | 是    | 钱包 ID  |
| `settlementAccountUID` | `int64`  | 是    | 结算账户标识 |
| `reason`               | `string` | 是    | 删除原因   |

**响应参数**

| 参数名       | 类型       | 描述   |
| --------- | -------- | ---- |
| `code`    | `int32`  | 业务码  |
| `message` | `string` | 业务消息 |

**请求示例**

```json theme={null}
{
  "settlementAccountUID": 1236547995462114,
  "walletId": 4298832316123456,
  "reason": "del reason"
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success"
}
```

### 12. 查询收款账号

**请求参数**

| 参数名                    | 类型       | 是否必填 | 描述           |
| ---------------------- | -------- | ---- | ------------ |
| `walletId`             | `int64`  | 是    | 钱包 ID        |
| `settlementAccountUID` | `int64`  | 否    | 结算账户标识（精确查询） |
| `companyCode`          | `string` | 否    | 企业编码（按企业过滤）  |

**响应参数**

| 参数名       | 类型                       | 描述   |
| --------- | ------------------------ | ---- |
| `code`    | `int32`                  | 业务码  |
| `message` | `string`                 | 业务消息 |
| `data`    | `Array<BankAccountData>` | 账户列表 |

**请求示例**

```json theme={null}
{
  "settlementAccountUID": 1236547995462114,
  "walletId": 4298832316123456,
  "companyCode": "HK1239876654"
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success",
  "data": [
    {
      "settlementAccountUID": 1236547995462114,
      "walletId": 4298832316123456,
      "alias": "name alias",
      "accountOwnership": 2,
      "currency": "USD",
      "accountType": 2,
      "companyName": "narti adiddf",
      "accountNumber": "8888888",
      "bankId": "003",
      "beneficiaryAddress1": "payee address1",
      "beneficiaryAddress2": "payee address2",
      "beneficiaryAddress3": "HK",
      "beneficiarySwiftCode": "DHBKHKHHXXX",
      "intermediarySwiftCode": "DHBKHKHHXXX",
      "companyCode": "HK1239876654",
      "status": 0,
      "paymentFiles": [
        {
          "fileKey": "file_key_123",
          "fileName": "证明文件.pdf",
          "fileUrl": "https://xxxxx"
        }
      ],
      "remark": "备注信息"
    }
  ]
}
```

***

# 兑换与出金

### 13. Payout 询价

获取指定币对价格及转账信息。`fromAmount` / `toAmount` 二选一。

**请求参数**

| 参数名            | 类型       | 是否必填 | 描述                                                        |
| -------------- | -------- | ---- | --------------------------------------------------------- |
| `walletId`     | `int64`  | 是    | 钱包 ID                                                     |
| `fromCurrency` | `string` | 是    | 卖出币种：`USDT` / `USDC`                                      |
| `fromAmount`   | `string` | 否    | 卖出金额，2 位小数                                                |
| `toCurrency`   | `string` | 是    | 买入币种：`USD`                                                |
| `toAmount`     | `string` | 否    | 买入金额，2 位小数                                                |
| `paymentWay`   | `string` | 是    | 支付方式：`RDT` / `CHATS`                                      |
| `feeMode`      | `int32`  | 条件   | `paymentWay=CHATS` 必填。`1` 收付双方共同承担（SHAR）；`2` 付款方承担所有（OUR） |

**响应参数**

| 参数名       | 类型                | 描述   |
| --------- | ----------------- | ---- |
| `code`    | `int32`           | 业务码  |
| `message` | `string`          | 业务消息 |
| `data`    | `PayoutQuoteData` | 询价结果 |

`PayoutQuoteData` 字段：

| 字段名               | 类型       | 描述             |
| ----------------- | -------- | -------------- |
| `walletId`        | `int64`  | 钱包 ID          |
| `fromCurrency`    | `string` | 卖出币种           |
| `fromAmount`      | `string` | 卖出金额           |
| `toCurrency`      | `string` | 买入币种           |
| `toAmount`        | `string` | 买入金额（已扣手续费）    |
| `paymentWay`      | `string` | 支付方式           |
| `feeMode`         | `int32`  | 手续费扣费模式        |
| `quoteId`         | `int64`  | 询价 ID（下单时使用）   |
| `price`           | `string` | 价格             |
| `priceExpireTime` | `string` | 价格有效截止时间，毫秒时间戳 |
| `feeAmount`       | `string` | 手续费            |
| `feeCurrency`     | `string` | 手续费币种          |

**请求示例**

```json theme={null}
{
  "walletId": 1000232233,
  "fromCurrency": "USDT",
  "fromAmount": "200.12",
  "toCurrency": "USD",
  "paymentWay": "CHATS",
  "feeMode": 1
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success",
  "data": {
    "walletId": "429405186232384",
    "fromCurrency": "USDT",
    "fromAmount": "200.12",
    "toCurrency": "USD",
    "toAmount": "192.83",
    "paymentWay": "CHATS",
    "feeMode": 1,
    "quoteId": "665131773713321985",
    "price": "0.9986",
    "priceExpireTime": "1736387772381",
    "feeAmount": "7",
    "feeCurrency": "USD"
  }
}
```

### 14. Payout 下单

基于询价 ID 下单。

**请求参数**

| 参数名                    | 类型       | 是否必填 | 描述                                   |
| ---------------------- | -------- | ---- | ------------------------------------ |
| `walletId`             | `int64`  | 是    | 钱包 ID                                |
| `quoteId`              | `int64`  | 是    | 询价 ID                                |
| `settlementAccountUID` | `int64`  | 是    | 结算账户标识，通过查询收款账号接口取得                  |
| `purpose`              | `string` | 是    | 付款目的，见附录【付款目的】                       |
| `extOrderNo`           | `string` | 是    | 业务方订单号（数字、大小写字母、`_`、`-`、`*`，同商户号下唯一） |

**响应参数**

| 参数名       | 类型               | 描述   |
| --------- | ---------------- | ---- |
| `code`    | `int32`          | 业务码  |
| `message` | `string`         | 业务消息 |
| `data`    | `PayoutBookData` | 下单结果 |

`PayoutBookData` 字段：

| 字段名                    | 类型       | 描述               |
| ---------------------- | -------- | ---------------- |
| `walletId`             | `int64`  | 钱包 ID            |
| `quoteId`              | `int64`  | 询价 ID            |
| `settlementAccountUID` | `int64`  | 结算账户标识           |
| `purpose`              | `string` | 付款目的             |
| `orderNo`              | `string` | 订单号              |
| `fromCurrency`         | `string` | 卖出币种             |
| `fromAmount`           | `string` | 卖出金额             |
| `toCurrency`           | `string` | 买入币种             |
| `toAmount`             | `string` | 买入金额             |
| `paymentWay`           | `string` | 支付方式             |
| `feeMode`              | `int32`  | 手续费扣费模式          |
| `feeAmount`            | `string` | 手续费              |
| `feeCurrency`          | `string` | 手续费币种            |
| `orderStatus`          | `string` | 见附录【Payout 订单状态】 |
| `createTime`           | `int64`  | 订单创建时间           |
| `extOrderNo`           | `string` | 业务方订单号           |

**请求示例**

```json theme={null}
{
  "walletId": 1000232233,
  "quoteId": 665131773713321985,
  "settlementAccountUID": 48775048489845,
  "purpose": "PMT001",
  "extOrderNo": "1234567898"
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success",
  "data": {
    "walletId": "429405186232384",
    "quoteId": "665205920267108353",
    "settlementAccountUID": 1236547995462114,
    "purpose": "PMT001",
    "orderNo": "431513431160832",
    "fromCurrency": "USDT",
    "fromAmount": "200.12",
    "toCurrency": "USD",
    "toAmount": "192.83",
    "paymentWay": "CHATS",
    "feeMode": 1,
    "feeAmount": "7",
    "feeCurrency": "USD",
    "orderStatus": "SUBMITTED",
    "createTime": "1736405450558",
    "extOrderNo": "1234567898"
  }
}
```

### 15. Payout 订单查询

按订单号或询价 ID 查询订单。

**请求参数**

| 参数名        | 类型       | 是否必填 | 描述                                |
| ---------- | -------- | ---- | --------------------------------- |
| `walletId` | `int64`  | 是    | 钱包 ID                             |
| `orderNo`  | `string` | 否    | RD 订单号                            |
| `quoteId`  | `int64`  | 否    | 询价 ID。`orderNo` / `quoteId` 至少二选一 |

**响应参数**

| 参数名       | 类型           | 描述   |
| --------- | ------------ | ---- |
| `code`    | `int32`      | 业务码  |
| `message` | `string`     | 业务消息 |
| `data`    | `PayoutData` | 订单详情 |

`PayoutData` 字段：

| 字段名                    | 类型       | 描述               |
| ---------------------- | -------- | ---------------- |
| `walletId`             | `int64`  | 钱包 ID            |
| `quoteId`              | `int64`  | 询价 ID            |
| `orderNo`              | `string` | 订单号              |
| `fromCurrency`         | `string` | 卖出币种             |
| `fromAmount`           | `string` | 卖出金额             |
| `toCurrency`           | `string` | 买入币种             |
| `toAmount`             | `string` | 买入金额             |
| `tradeFromAmount`      | `string` | 实际成交卖出金额         |
| `tradeToAmount`        | `string` | 实际成交买入金额         |
| `price`                | `string` | 下单价格             |
| `tradePrice`           | `string` | 成交价格             |
| `orderStatus`          | `string` | 见附录【Payout 订单状态】 |
| `createTime`           | `int64`  | 订单创建时间           |
| `finishTime`           | `int64`  | 订单完成时间           |
| `errorMsg`             | `string` | 失败原因             |
| `settlementAccountUID` | `int64`  | 结算账户标识           |
| `purpose`              | `string` | 付款目的             |
| `paymentWay`           | `string` | 支付方式             |
| `feeMode`              | `int32`  | 手续费扣费模式          |
| `feeAmount`            | `string` | 手续费              |
| `feeCurrency`          | `string` | 手续费币种            |
| `refundOrderNo`        | `string` | 失败时退款订单号         |
| `refundAmount`         | `string` | 失败时退款金额          |
| `refundCurrency`       | `string` | 失败时退款币种          |
| `extOrderNo`           | `string` | 业务方订单号           |

**请求示例**

```json theme={null}
{
  "walletId": 1000232233,
  "quoteId": 665131773713321985
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success",
  "data": {
    "walletId": 1000232233,
    "quoteId": 665131773713321985,
    "orderNo": "442112731049984",
    "fromCurrency": "USDT",
    "fromAmount": "200.12",
    "toCurrency": "USD",
    "toAmount": "192.83",
    "tradeFromAmount": "200.12",
    "tradeToAmount": "192.83",
    "price": "1.142",
    "tradePrice": "1.142",
    "orderStatus": "SUCCESSFUL",
    "createTime": 1741580889957,
    "finishTime": 1741580889957,
    "settlementAccountUID": 1236547995462114,
    "purpose": "PMT001",
    "paymentWay": "CHATS",
    "feeMode": 1,
    "feeAmount": "7",
    "feeCurrency": "USD",
    "extOrderNo": "1234567898"
  }
}
```

### 16. Payout 重新结算

针对结算失败或退款订单发起重新结算。

**请求参数**

| 参数名                    | 类型       | 是否必填 | 描述                                    |
| ---------------------- | -------- | ---- | ------------------------------------- |
| `walletId`             | `int64`  | 是    | 钱包 ID                                 |
| `orderNo`              | `string` | 是    | 原 Payout 订单号                          |
| `refundOrderNo`        | `string` | 是    | 退款订单号                                 |
| `settlementAccountUID` | `int64`  | 是    | 结算账户标识                                |
| `purpose`              | `string` | 是    | 付款目的                                  |
| `remark`               | `string` | 是    | 描述                                    |
| `paymentWay`           | `string` | 是    | 支付方式：`RDT` / `CHATS`                  |
| `feeMode`              | `int32`  | 条件   | `paymentWay=CHATS` 必填，含义同 Payout 询价接口 |

**响应参数**

| 参数名       | 类型                   | 描述     |
| --------- | -------------------- | ------ |
| `code`    | `int32`              | 业务码    |
| `message` | `string`             | 业务消息   |
| `data`    | `PayoutReSettleData` | 重新结算结果 |

`PayoutReSettleData` 字段：

| 字段名                    | 类型       | 描述           |
| ---------------------- | -------- | ------------ |
| `walletId`             | `int64`  | 钱包 ID        |
| `orderNo`              | `string` | 原 Payout 订单号 |
| `refundOrderNo`        | `string` | 退款订单号        |
| `settlementAccountUID` | `int64`  | 结算账户标识       |
| `purpose`              | `string` | 付款目的         |
| `remark`               | `string` | 描述           |
| `paymentWay`           | `string` | 支付方式         |
| `feeMode`              | `int32`  | 手续费扣费模式      |
| `amount`               | `string` | 重新结算金额       |
| `currency`             | `string` | 重新结算币种       |
| `feeAmount`            | `string` | 手续费          |
| `feeCurrency`          | `string` | 手续费币种        |

**请求示例**

```json theme={null}
{
  "walletId": 1000232233,
  "orderNo": "442112731049984",
  "refundOrderNo": "232112731049984",
  "settlementAccountUID": 1236547995462114,
  "purpose": "PMT001",
  "remark": "remark",
  "paymentWay": "CHATS",
  "feeMode": 1
}
```

**响应示例**

```json theme={null}
{
  "code": 1,
  "message": "Success",
  "data": {
    "walletId": 1000232233,
    "orderNo": "442112731049984",
    "refundOrderNo": "232112731049984",
    "settlementAccountUID": 1236547995462114,
    "purpose": "PMT001",
    "remark": "remark",
    "paymentWay": "CHATS",
    "feeMode": 1,
    "amount": "183",
    "currency": "USD",
    "feeAmount": "7",
    "feeCurrency": "USD"
  }
}
```

***

# 回调（Webhook）

### 请求规范

| 项目           | 值                                                              |
| ------------ | -------------------------------------------------------------- |
| 方法           | `POST`                                                         |
| Content-Type | `application/json; charset=utf-8`                              |
| 请求体          | JSON，结构由事件类型决定（如 `WITHDRAWAL_SUCCESS` / `DEPOSIT_COMPLETED` 等） |
| 超时           | 默认 8 秒；超时视为失败，可能触发业务层重试                                        |

**请求头**

| Header         | 说明                                   |
| -------------- | ------------------------------------ |
| `X-Api-Key`    | 商户 `api_key`，标识本次回调的归属商户             |
| `X-Timestamp`  | UTC 毫秒时间戳字符串，回调发出时刻                  |
| `X-Nonce`      | 本次回调唯一随机串（32 位 hex），用于商户侧去重          |
| `X-Signature`  | HMAC-SHA256 签名，算法见下方签名验证             |
| `Content-Type` | 固定 `application/json; charset=utf-8` |

### 签名验证

**算法与入向接口完全一致（对称），共用同一把** `sign_secret`：

```text theme={null}
string_to_sign = "POST" + PATH + X-Timestamp + X-Nonce + SHA256_HEX(BODY)
signature      = HEX( HMAC_SHA256( sign_secret, string_to_sign ) )
```

* `PATH`：回调 URL 的 path 部分，不含域名与 query
* `BODY`：HTTP 请求体**原始字节**

#### 验签步骤

1. **取请求头**：`X-Timestamp`、`X-Nonce`、`X-Signature`、`X-Api-Key`
2. **校验时间戳窗口**：`abs(now_ms − X-Timestamp) ≤ 5 × 60 × 1000`，否则直接拒绝（`401`）
3. **读取请求体**：在任何反序列化/解析**之前**拿到原始字节（见下方避坑提示）
4. **重算签名**：用 `sign_secret` 和步骤 3 得到的 body，按上面的公式算出 `expected`
5. **常量时间比对**：用框架提供的 `constant_time_compare` / `hmac.compare_digest` 比对 `expected` 与 `X-Signature`，**不要用** `==`（防时序攻击）
6. **幂等去重**：用 `X-Nonce` 作为幂等键判重，已处理过则直接返回上次结果

#### 避坑提示

* **必须是原始字节**：任何中间件/框架如果在你拿到 body 之前做了反序列化、字符重编码、JSON 规范化（例如 `JSON.stringify` 重排字段或美化空格），都会让签名失配。
* **PATH 严格匹配**：拼签名用的 `PATH` 必须和网关发来的 URL path 完全一致——不能加尾斜杠、不能 urldecode、不能去掉前缀。
* **大小写敏感**：`X-Signature` 是小写 hex；`METHOD` 固定大写 `POST`。
* **空 body 也要参与签名**：若本次回调 body 为空，`SHA256_HEX("")` = `e3b0c442...b855`，不能省略。

#### 多语言参考实现

**Python**

```python theme={null}
import hashlib
import hmac

def verify(path: str, ts: str, nonce: str, body_bytes: bytes,
           x_signature: str, sign_secret: str) -> bool:
    body_hash = hashlib.sha256(body_bytes).hexdigest()
    expected = hmac.new(
        sign_secret.encode(),
        ("POST" + path + ts + nonce + body_hash).encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, x_signature)
```

**Node.js**

```javascript theme={null}
const crypto = require('crypto');

function verify(path, ts, nonce, bodyBuf, xSignature, signSecret) {
  const bodyHash = crypto.createHash('sha256').update(bodyBuf).digest('hex');
  const expected = crypto
    .createHmac('sha256', signSecret)
    .update('POST' + path + ts + nonce + bodyHash)
    .digest('hex');

  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(xSignature, 'utf8');

  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
```

**Java**

```java theme={null}
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.MessageDigest;
import java.util.HexFormat;

public static boolean verify(String path, String ts, String nonce,
                             byte[] body, String xSignature, String signSecret) throws Exception {
    String bodyHash = HexFormat.of().formatHex(
        MessageDigest.getInstance("SHA-256").digest(body));
    String toSign = "POST" + path + ts + nonce + bodyHash;

    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(signSecret.getBytes(), "HmacSHA256"));
    String expected = HexFormat.of().formatHex(mac.doFinal(toSign.getBytes()));

    return MessageDigest.isEqual(
        expected.getBytes(), xSignature.getBytes());
}
```

**Go**

```go theme={null}
package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
)

func Verify(path, ts, nonce string, body []byte, xSig, signSecret string) bool {
    sum := sha256.Sum256(body)
    bodyHash := hex.EncodeToString(sum[:])

    mac := hmac.New(sha256.New, []byte(signSecret))
    mac.Write([]byte("POST" + path + ts + nonce + bodyHash))
    expected := hex.EncodeToString(mac.Sum(nil))

    return hmac.Equal([]byte(expected), []byte(xSig))
}
```

> **调试小技巧** 验签失败时，把你算出的 `string_to_sign` 打印一次 —— 99% 的 bug 都出在这段字符串与网关侧拼的不一致（PATH、BODY 二次序列化、字符编码）。把你的字符串和对应的 `X-Request-Id` 发给技术支持，可以快速定位。

### 响应要求

* 商户端**必须**在 8 秒内完成响应。
* HTTP 状态码 `2xx` 视为回调投递成功；非 `2xx`、超时或响应体为业务错误均视为失败。
* 响应体建议遵循统一约定：

成功：

```json theme={null}
{
  "code": 1,
  "message": "OK"
}
```

失败：

```json theme={null}
{
  "code": 6001,
  "message": "failed"
}
```

### 幂等与重放防护

* **幂等键**：推荐以 `X-Nonce` 作为幂等键持久化，重复收到同一 key 的回调立刻返回上次处理结果，不重复执行业务。
* **重放防护**：校验 `X-Timestamp` 与服务器时间差在 **±5 分钟**以内，超窗直接拒绝。
* **签名强校验**：任何签名验证失败，直接返回 `4xx`，不进入业务处理。

### 事件载荷

### 17. 订单结果通知

| 字段            | 类型       | 描述                                |
| ------------- | -------- | --------------------------------- |
| `orderNo`     | `string` | RD 订单号                            |
| `currency`    | `string` | 币种：`USDT` / `USDC`                |
| `network`     | `string` | 网络：`ETH` / `TRX` / `SOL` / `POLY` |
| `status`      | `string` | 订单状态，见附录【入金订单状态】                  |
| `amount`      | `string` | 金额                                |
| `fromAddress` | `string` | 发起方地址                             |
| `fromWallet`  | `string` | 来源钱包                              |
| `toAddress`   | `string` | 接收方地址                             |
| `toWallet`    | `string` | 目标钱包                              |
| `txHash`      | `string` | 区块链交易哈希                           |
| `orderType`   | `int32`  | 订单类型                              |
| `extOrderNo`  | `string` | 外部订单号                             |

**示例**

```json theme={null}
{
  "orderNo": "ORDER123456789",
  "currency": "USDT",
  "network": "ETH",
  "status": "SUCCESS",
  "amount": "1.0",
  "fromAddress": "0x123456789abcdef",
  "toAddress": "0x987654321fedcba",
  "fromWallet": "123456",
  "toWallet": "1234567",
  "txHash": "0x123456789abcdef123456789abcdef",
  "orderType": 1,
  "extOrderNo": "EXT123456789"
}
```

### 18. 添加收款账号结果通知

| 字段                      | 类型       | 描述                                |
| ----------------------- | -------- | --------------------------------- |
| `settlementAccountUID`  | `int64`  | 结算账户标识                            |
| `walletId`              | `int64`  | 钱包 ID                             |
| `alias`                 | `string` | 别名                                |
| `accountOwnership`      | `int32`  | `1` own；`2` other；`3` Third party |
| `currency`              | `string` | 币种：`USD`                          |
| `accountType`           | `int32`  | `1` RD Wallet；`2` Bank Account    |
| `accountName`           | `string` | 账户名称                              |
| `accountNumber`         | `string` | 账号                                |
| `bankId`                | `string` | 香港银行 ID，例如 `003`                  |
| `beneficiaryAddress1`   | `string` | 收款方地址 1（不允许中文）                    |
| `beneficiaryAddress2`   | `string` | 收款方地址 2（不允许中文）                    |
| `beneficiaryAddress3`   | `string` | 收款方地址 3：国家/地区 ISO 3166 编码         |
| `beneficiarySwiftCode`  | `string` | 银行 Swift Code                     |
| `intermediarySwiftCode` | `string` | 中间银行 Swift Code                   |
| `companyCode`           | `string` | 企业编码                              |
| `status`                | `int32`  | `0` 处理中；`1` 成功；`2` 失败             |

**示例**

```json theme={null}
{
  "settlementAccountUID": 1236547995462114,
  "walletId": 4298832316123456,
  "alias": "name alias",
  "accountOwnership": 2,
  "currency": "USD",
  "accountType": 2,
  "accountName": "narti adiddf",
  "accountNumber": "8888888",
  "bankId": "003",
  "beneficiaryAddress1": "payee address1",
  "beneficiaryAddress2": "payee address2",
  "beneficiaryAddress3": "HK",
  "beneficiarySwiftCode": "DHBKHKHHXXX",
  "intermediarySwiftCode": "DHBKHKHHXXX",
  "companyCode": "HK1239876654",
  "status": 0
}
```

### 19. Payout 结果通知

| 字段名                    | 类型       | 描述                                                     |
| ---------------------- | -------- | ------------------------------------------------------ |
| `walletId`             | `int64`  | 钱包 ID                                                  |
| `quoteId`              | `int64`  | 询价 ID                                                  |
| `orderNo`              | `string` | 订单号                                                    |
| `fromCurrency`         | `string` | 卖出币种                                                   |
| `fromAmount`           | `string` | 卖出金额                                                   |
| `toCurrency`           | `string` | 买入币种                                                   |
| `toAmount`             | `string` | 买入金额                                                   |
| `tradeFromAmount`      | `string` | 实际成交卖出金额                                               |
| `tradeToAmount`        | `string` | 实际成交买入金额                                               |
| `price`                | `string` | 下单价格                                                   |
| `tradePrice`           | `string` | 成交价格                                                   |
| `orderStatus`          | `string` | 见附录【Payout 订单状态】                                       |
| `createTime`           | `int64`  | 订单创建时间                                                 |
| `finishTime`           | `int64`  | 订单完成时间                                                 |
| `errorMsg`             | `string` | 订单失败原因                                                 |
| `settlementAccountUID` | `int64`  | 结算账户标识                                                 |
| `purpose`              | `string` | 见附录【付款目的】                                              |
| `paymentWay`           | `string` | 支付方式：`RDT` / `CHATS`                                   |
| `feeMode`              | `int32`  | 手续费扣费模式，默认值：`1`。`1` 收付双方共同承担（SHAR）；`2` 付款方承担所有手续费（OUR） |
| `feeAmount`            | `string` | 手续费                                                    |
| `feeCurrency`          | `string` | 手续费币种                                                  |
| `refundOrderNo`        | `string` | Payout 订单状态为 `SETTLING_FAILED` 时有值，用于重新发起结算            |
| `extOrderNo`           | `string` | 业务方订单号（只能是数字、大小写字母、`_`、`-`、`*`，且在同一个商户号下唯一）            |

**示例**

```json theme={null}
{
  "walletId": 1000232233,
  "quoteId": 665131773713321985,
  "orderNo": "442112731049984",
  "fromCurrency": "USDT",
  "fromAmount": "200.12",
  "toCurrency": "USD",
  "toAmount": "192.83",
  "tradeFromAmount": "200.12",
  "tradeToAmount": "192.83",
  "price": "1.142",
  "tradePrice": "1.142",
  "orderStatus": "SUCCESSFUL",
  "createTime": 1741580889957,
  "finishTime": 1741580889957,
  "settlementAccountUID": 1236547995462114,
  "purpose": "PMT001",
  "paymentWay": "CHATS",
  "feeMode": 1,
  "feeAmount": "7",
  "feeCurrency": "USD",
  "extOrderNo": "1234567898"
}
```

### 20. Payout 退款结果通知

| 字段名              | 类型       | 描述         |
| ---------------- | -------- | ---------- |
| `walletId`       | `int64`  | 钱包 ID      |
| `orderNo`        | `string` | Payout 订单号 |
| `refundOrderNo`  | `string` | 退款订单号      |
| `refundAmount`   | `string` | 实际退款金额     |
| `refundCurrency` | `string` | 退款币种       |
| `refundReason`   | `string` | 退款原因，有则回传  |
| `refundTime`     | `int64`  | 退款时间       |

**示例**

```json theme={null}
{
  "walletId": 123456789,
  "orderNo": "442112731049984",
  "refundOrderNo": "442112731049984D1",
  "refundAmount": "664.26",
  "refundCurrency": "USD",
  "refundReason": "refund",
  "refundTime": 1741580889957
}
```

### 21. Payout 重新结算结果通知

| 字段名                    | 类型       | 描述                                                     |
| ---------------------- | -------- | ------------------------------------------------------ |
| `walletId`             | `int64`  | 钱包 ID                                                  |
| `orderNo`              | `string` | Payout 订单号                                             |
| `refundOrderNo`        | `string` | 退款订单号                                                  |
| `settlementAccountUID` | `int64`  | 结算账户标识                                                 |
| `purpose`              | `string` | 见附录【付款目的】                                              |
| `remark`               | `string` | 描述                                                     |
| `paymentWay`           | `string` | 支付方式：`RDT` / `CHATS`                                   |
| `feeMode`              | `int32`  | 手续费扣费模式，默认值：`1`。`1` 收付双方共同承担（SHAR）；`2` 付款方承担所有手续费（OUR） |
| `amount`               | `string` | 结算金额                                                   |
| `currency`             | `string` | 结算币种                                                   |
| `feeAmount`            | `string` | 手续费                                                    |
| `feeCurrency`          | `string` | 手续费币种                                                  |
| `createTime`           | `int64`  | 订单创建时间                                                 |
| `finishTime`           | `int64`  | 订单完成时间                                                 |
| `orderStatus`          | `string` | 重新结算订单状态，见附录【Payout 订单状态】                              |

**示例**

```json theme={null}
{
  "walletId": 1000232233,
  "orderNo": "442112731049984",
  "refundOrderNo": "232112731049984",
  "settlementAccountUID": 1236547995462114,
  "purpose": "PMT001",
  "remark": "remark",
  "paymentWay": "CHATS",
  "feeMode": 1,
  "amount": "183",
  "currency": "USD",
  "feeAmount": "7",
  "feeCurrency": "USD",
  "createTime": 1741580889957,
  "finishTime": 1741580889957,
  "orderStatus": "SUCCESSFUL"
}
```

# 附录

### 响应码

| code   | 含义                                         |
| ------ | ------------------------------------------ |
| `1`    | 成功                                         |
| `6001` | 通用业务失败（failed）                             |
| `6002` | 参数错误（parameter error）                      |
| `6003` | 订单不存在（order not exist）                     |
| `6004` | 订单重复（order duplicate）                      |
| `6005` | 没有权限（no permissions）                       |
| `6006` | 资产不存在（assets not exists）                   |
| `6101` | 钱包账号不存在（wallet account not exists）         |
| `6102` | 钱包余额不足（wallet insufficient fund）           |
| `6103` | 钱包账号无效（wallet status invalid）              |
| `6104` | 收款钱包不可用（recipient wallet unavailable）      |
| `6105` | 收款钱包不存在（recipient wallet not exists）       |
| `6109` | 付款日限额不足（Daily payment limit exceeded）      |
| `6110` | 收款月限额不足（Monthly collection limit exceeded） |
| `6301` | 通道不可用（provider unavailable）                |
| `6302` | 币种对不可用（symbol unavailable）                 |
| `6303` | 通道拒绝（provider reject）                      |
| `6304` | 价格已过期（price expire time）                   |
| `6305` | 金额低于最低限额（amount lt min amount）             |
| `6306` | 金额高于最高限额（amount gt max amount）             |
| `6307` | 不在交易时间内（outside of hours）                  |
| `6401` | 地址已存在                                      |
| `6406` | 请求正在处理中（processing）                        |
| `6801` | 重复申请（duplicate request）                    |
| `6802` | 资料错误（profile error），返回 `errors` 列表         |
| `6803` | 钱包数量达到上限（reach the max limit）              |

### Payout 订单状态

| code              | 中文   | 说明        |
| ----------------- | ---- | --------- |
| `SUBMITTED`       | 已提交  | 订单已提交     |
| `CONVERTING`      | 兑换中  | 订单兑换中     |
| `SETTLING`        | 结算中  | 兑换成功，进行结算 |
| `SETTLING_FAILED` | 结算失败 | 兑换成功，结算失败 |
| `SETTLING_REFUND` | 退款   | 结算成功后被退款  |
| `SUCCESSFUL`      | 交易成功 | 订单处理成功    |
| `FAILED`          | 交易失败 | 订单处理失败    |

### 入金订单状态

| code                    | 中文    | 说明                              |
| ----------------------- | ----- | ------------------------------- |
| `SUBMITTED`             | 已提交   | 订单已提交                           |
| `VERIFYING`             | 订单验证  | 订单提交后进行安全验证（仅 Request Payment）  |
| `AWAIT_FOR_RECEIVE`     | 等待收款  | 订单创建成功，等待收款（仅 Request Payment）  |
| `PAYMENT_VERIFYING`     | 收款验证中 | 平台已收款，进行安全验证（仅 Request Payment） |
| `AWAIT_FOR_DECLARATION` | 待补充材料 | 待补充贸易材料（仅 Request Payment）      |
| `DECLARATION_REVIEW`    | 材料验证中 | 材料审核中                           |
| `SUCCESS`               | 交易成功  | 订单成功                            |
| `FAILED`                | 交易失败  | 订单失败                            |
| `CLOSED`                | 交易关闭  | 订单到期后关闭                         |
| `RETURNING`             | 退款中   | 退款中                             |
| `RETURNED`              | 已退款   | 退款处理成功                          |
| `IN_PROGRESS`           | 收款验证中 | 平台已收款，进行安全验证（仅 Deposit）         |

### 订单类型

| code | 类型                |
| ---- | ----------------- |
| `1`  | Deposit           |
| `2`  | Wallet Transfer   |
| `3`  | Internal Transfer |
| `4`  | Request Payment   |
| `5`  | Withdraw          |

### 字段说明：amount（金额）

字段类型恒为 `string`，精度按币种类型区分：

* **数币（Digital Currency）**：最多保留 6 位小数，满足链上交易精度需求。
* **法币（Fiat Currency）**：最多保留 2 位小数，精确到「分」。
* **日元（JPY）**：无小数货币，必须为整数，不得包含小数部分。

请按币种严格控制金额格式，避免精度误差或接口处理异常。

### 付款目的（purpose）

| code     | 含义                                                                          |
| -------- | --------------------------------------------------------------------------- |
| `PMT001` | Invoice payments — 发票付款                                                     |
| `PMT002` | Payment for services — 服务付款                                                 |
| `PMT003` | Payment for software — 软件付款                                                 |
| `PMT004` | Payment for imported goods — 进口货物付款                                         |
| `PMT005` | Travel services — 旅行服务                                                      |
| `PMT006` | Transfer to own account — 转账到自己的账户                                          |
| `PMT007` | Repayment of loans — 贷款偿还                                                   |
| `PMT009` | Payment of property rental — 物业租金                                           |
| `PMT010` | Information Service Charges — 信息服务费                                         |
| `PMT011` | Advertising & Public relations-related expenses — 广告和公共关系费用                 |
| `PMT012` | Royalty / trademark / patent / copyright fees — 版权/商标/专利费用                  |
| `PMT013` | Brokers / front-end / commitment / guarantee / custodian fees — 经济费、保管费、托管费 |
| `PMT014` | Advisors, technical assistance, academic knowledge — 顾问费、技术援助、知识费用          |
| `PMT015` | Representative office expenses — 办公室费用                                      |
| `PMT016` | Tax Payment — 税费                                                            |
| `PMT017` | Transportation fees for goods — 货物运输费用                                      |
| `PMT018` | Construction costs / expenses — 建筑成本                                        |
| `PMT019` | Insurance Premium — 保险费                                                     |
| `PMT020` | General Goods Trades - Offline trade — 一般商品贸易                               |
| `PMT021` | Insurance Claims Payment — 保险赔付费用                                           |
| `PMT024` | Medical Treatment — 医疗                                                      |
| `PMT025` | Donations — 捐赠                                                              |
| `PMT026` | Mutual Fund Investment — 投资                                                 |
| `PMT027` | Currency Exchange — 货币兑换                                                    |
| `PMT028` | Advance Payments for Goods — 预付商品款项                                         |
| `PMT029` | Merchant Settlement — 商户结算                                                  |
| `PMT030` | Repatriation Fund Settlement — 遣返/回国资金结算                                    |

### 国家地区编码

ISO 3166 三字母编码（如 `HKG` / `CHN` / `MAC` / `USA` / `BMU` / `WSM` / `SYC` / `CYM` / `VGB` 等）。完整列表请向商务/技术支持索取，或参考 Confluence 外链：`https://rdwallet.atlassian.net/wiki/external/NzNjMzU5MjZkNTE4NGZkZWI2NzhmYTdiM2IyYjZmNjM`

### 行业编码

`subIndustryCode` 取值参见 Confluence 外链（可下载 Excel）：`https://rdwallet.atlassian.net/wiki/external/YjA0N2FiNjcwNjljNDI2MDk0MGE4OTRkZjYxZmEyMmY`

### 档案错误描述（code = 6802）

下列消息均来自资料校验，按所属模块分组（实际消息为 **英文**，此处保留原文）。

**\[Business details]**

* `Industry cannot be empty!`
* `Added industries exceeded limit: 3`
* `Industry code cannot be empty!`
* `Industry code does not exist!`
* `Sales turnover of last year cannot be empty!`
* `Incorrect sales turnover of last year input!`
* `Year(s) in business cannot be empty!`
* `Incorrect year(s) in business input!`
* `Location(s) of business cannot be empty!`
* `Location(s) of business exceeded limit: 3`
* `Industry details cannot be empty!`
* `Industry details exceeded maximum length`

**\[Entity details]**

* `We only support partnership business in Hong Kong`
* `We only support sole proprietorship business in Hong Kong`
* `Please enter the ciNumber.`
* `Please enter the brNumber.`
* `Operating place cannot be empty!`
* `Operating address cannot be empty!`
* `Operating address exceeded maximum length`
* `Company registered place cannot be empty!`
* `Company registered place not supported:[区域名称]`
* `The operating place is not supported:[区域名称]`
* `Company registered address cannot be empty!`
* `Company registered address maximum length`
* `Company registered address in English only`
* `Website exceeded maximum length`
* `Incorrect business type!`
* `Business registration certificate number exceeded max length`
* `Business registration certificate number cannot be empty`
* `Certificate of incorporation number exceeded maximum length`
* `Certificate of incorporation number cannot be empty`
* `Name of business in English cannot be empty!`
* `Name of business in Chinese cannot be empty!`
* `Name of business in Chinese exceeded maximum length`
* `Name of business in English exceeded maximum length`
* `Not allowed option`
* `Please upload a valid proof of Certificate of Incorporation`
* `Please upload a valid proof of Memorandum and Articles of Association`
* `Please upload a valid proof of Business Registration`
* `Please upload a valid proof of Partnership Agreement`
* `Please upload a valid proof of Certificate of Incumbency`
* `Please upload a valid proof of KYC Files`
* `Duplicated document`
* `Please enter a valid business type.`
* `Company incorporation date cannot be empty`
* `Company incorporation date cannot be empty be greater than current date:[对应数值]`
* `Place of financial regulator cannot be empty!`
* `Incorrect place of financial regulator input!`
* `Name of regulator cannot be empty!`
* `Name of regulator exceeded maximum length`
* `Type of license cannot be empty!`
* `Type of license exceeded maximum length`
* `Incorrect place of incorporation!`
* `Sorry, the country/region is not supported yet! ... :{placeOfIncorporation}`
* `Please upload a valid proof of License/Certificate of Financial Institution`
* `Place of listing cannot be empty!`
* `Incorrect place of listing input!`
* `Name of exchange cannot be empty!`
* `Name of exchange exceeded maximum length`
* `Stock code cannot be empty!`
* `Stock code exceeded maximum length`
* `Place of government owner cannot be empty!`
* `Incorrect place of government owner input!`

**\[Key people]**

* `Email exceeded maximum length`
* `Incorrect email address format`
* `AreaCode exceeded maximum length`
* `MobileNumber exceeded maximum length`
* `Incorrect country/region of key people`
* `Incorrect country/region and idType of key people`
* `Incorrect idType`
* `The user's idv information is incomplete`
* `Last name in English exceeded maximum length`
* `Last name in English and first name in English cannot have only one value`
* `First name in English exceeded maximum length`
* `Name in Chinese exceeded maximum length`
* `idNumber exceeded maximum length`
* `Incorrect gender`
* `Please upload a valid proof of key people`
* `Please set a valid quorum`
* `Id Number[{idNumber}] was duplicate!`
* `Signer must be equal or greater than quorum`
* `Direct number has to be between 1 to 99`
* `Partner number has to be between 2 to 6`
* `Please add at least one owner`
* `Please add at most one owner`
* `Only limited company can create director`
* `Only partnership can create partner`
* `Please select at least one role for user:`
* `IsOwner is only supported by sole proprietorship`

**\[Shareholder]**

* `Shareholder structure cannot be empty`
* `Incorrect Level in sharesholder structure, only Zero to Ten Level`
* `Last name in English exceeded maximum length`
* `First name in English exceeded maximum length`
* `Name in Chinese exceeded maximum length`
* `Shareholder (company) name in English exceeded maximum length`
* `Shareholder (company) name in Chinese exceeded maximum length`
* `Shareholder (company) RegulatorName exceeded maximum length`
* `Shareholder (company) ExchangeName exceeded maximum length`
* `Shareholder (company) Stock code exceeded maximum length`
* `Incorrect ownedSharesPercent`
* `Shareholder type cannot be empty`
* `Please input correct shareholder type:{type}`
* `Shareholder (personal) name in English and Chinese cannot be empty at the same time!`
* `Shareholder (company) name cannot be empty`
* `Shareholder (company) business type cannot be empty`
* `Please input correct business type for the shareholder (company):{businessType}`
* `We only support sole proprietorship business in Hong Kong`
* `We only support partnership business in Hong Kong`
* `Shareholder (company) place of incorporate cannot be empty`
* `Incorrect shareholder (company) place of incorporate`
* `We only support company registered place for partnership and sole proprietorship in Hong Kong only`
* `Last name in English and first name in English cannot have only one value`
* `ParentId cannot be empty`
* `Listed/government owner/financial regulator not support partnership business`
* `Place of financial regulator cannot be empty!`
* `Place of financial regulator not supported!`
* `Name of regulator cannot be empty!`
* `Name of regulator exceeded maximum length`
* `Type of license cannot be empty!`
* `Type of license exceeded maximum length`
* `Listed/government owner not support sole proprietorship business`
* `Place of listing cannot be empty!`
* `Place of listing not supported!`
* `Name of exchange cannot be empty!`
* `Name of exchange exceeded maximum length`
* `Stock code cannot be empty!`
* `Stock code exceeded maximum length`
* `Place of government owner cannot be empty!`
* `Incorrect place of government owner input!`
* `Corresponding shareholder type for sameId[{id}] is different`
* `Corresponding shareholder name for sameId[{id}] is different`
* `Incorrect parentId in sharesholder structure`
* `Abnormal shareholder structure`
* `Shareholder structure cannot exceed 10 layers`
* `Shareholder structure is not necessary`

**\[Others]**

* `Customer type error.`