> ## 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 Transaction API

# ISV Transaction API

## Overview

This API set is designed for **ISV customers** to call on behalf of their end customers (merchants) after completing [Onboarding](./onboarding-api). It covers transfers, payment declarations, Payout, bank account management, and other daily transaction operations.

ISVs simply pass `walletId` when calling these APIs. OristaPay automatically enforces authorization based on the ISV ↔ merchant relationship. **Transaction API fields remain unchanged.**

## Authentication & Signing

All endpoints require signature headers. See [Authentication & Signing](./auth) for details.

## API Index

| #  | API                                  | REST Path                                  |
| -- | ------------------------------------ | ------------------------------------------ |
| 1  | Static Receiving Address Query       | `POST /api/v1/wallet/static-address/query` |
| 2  | Supported Currencies Query           | `POST /api/v1/wallet/supported/currencies` |
| 3  | Request Payment Order Declaration    | `POST /api/v1/payment/order/declare`       |
| 4  | Request Payment Material Supplement  | `POST /api/v1/payment/order/add/materials` |
| 5  | Internal Transfer                    | `POST /api/v1/payment/internal-transfer`   |
| 6  | Order Details                        | `POST /api/v1/payment/order/detail`        |
| 7  | Order List                           | `POST /api/v1/payment/order/list`          |
| 8  | Download Statement                   | `POST /api/v1/payment/reconciliation`      |
| 9  | Add Beneficiary Bank Account         | `POST /api/v1/wallet/bank_account/add`     |
| 10 | Update Beneficiary Bank Account      | `POST /api/v1/wallet/bank_account/update`  |
| 11 | Delete Beneficiary Bank Account      | `POST /api/v1/wallet/bank_account/del`     |
| 12 | Enquiry Beneficiary Bank Account     | `POST /api/v1/wallet/bank_account/get`     |
| 13 | Payout Quote                         | `POST /api/v1/payout/quote`                |
| 14 | Payout Order                         | `POST /api/v1/payout/book`                 |
| 15 | Payout Order Enquiry                 | `POST /api/v1/payout/enquiry`              |
| 16 | Payout Re-Settle                     | `POST /api/v1/payout/reSettle`             |
| 17 | Order Result Notification            | Webhook                                    |
| 18 | Add Bank Account Result Notification | Webhook                                    |
| 19 | Payout Result Notification           | Webhook                                    |
| 20 | Payout Refund Result Notification    | Webhook                                    |
| 21 | Payout Re-Settle Result Notification | Webhook                                    |

# Wallet Payment API

### 1. Static Receiving Address Query

**Interface Overview**

Query the Request Payment static receiving address of a specified wallet.

**Request Parameters**

| Field Name | Type     | M / O / CM | Description                                        |
| :--------- | :------- | :--------- | :------------------------------------------------- |
| `walletId` | `int64`  | M          | Wallet ID                                          |
| `network`  | `string` | O          | Blockchain network: `ETH` / `TRX` / `SOL` / `POLY` |
| `currency` | `string` | O          | Currency: `USDT` / `USDC`                          |

**Response Parameters**

| Field Name | Type                       | Description               |
| :--------- | :------------------------- | :------------------------ |
| `code`     | `int32`                    | Business response code    |
| `message`  | `string`                   | Business response message |
| `data`     | `Array<StaticAddressData>` | Static address list       |

`StaticAddressData` fields:

| Field Name     | Type     | Description                                                                                                                         |
| :------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `walletId`     | `int64`  | Wallet ID                                                                                                                           |
| `network`      | `string` | Blockchain network, such as `ETH` / `TRX`                                                                                           |
| `currency`     | `string` | Currency, such as `USDT` / `USDC`                                                                                                   |
| `address`      | `string` | Static receiving address                                                                                                            |
| `qrCodeBase64` | `string` | QR code image of the address, Base64 encoded, including the `data:image/png;base64,` prefix. It can be directly used in `<img src>` |

**Request Example**

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

**Response Example**

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

### 2. Supported Currencies Query

**Interface Overview**

Query the currencies, available networks, single-transaction amount range, and currency precision supported by the wallet under a specified business type by `walletId + type`. The caller can use this API for pre-validation before creating deposit or withdrawal orders, to avoid submitting unsupported or out-of-limit currency combinations.

**Request Parameters**

| Field Name | Type     | M / O / CM | Description                                           |
| :--------- | :------- | :--------- | :---------------------------------------------------- |
| `walletId` | `int64`  | M          | Wallet ID                                             |
| `type`     | `string` | M          | Business type / limit type: `4` deposit, `3` withdraw |

**Response Parameters**

| Field Name | Type                                  | Description                                       |
| :--------- | :------------------------------------ | :------------------------------------------------ |
| `code`     | `int32`                               | Business response code                            |
| `message`  | `string`                              | Business response message                         |
| `data`     | `Array<SupportedCurrenciesQueryData>` | Supported currency list; returned when `code = 1` |

`SupportedCurrenciesQueryData` fields:

| Field Name  | Type            | Description                                                                        |
| :---------- | :-------------- | :--------------------------------------------------------------------------------- |
| `type`      | `int32`         | Business type / limit type, corresponding to the request `type`                    |
| `currency`  | `string`        | Currency, such as `USDT` / `USDC` / `USD`                                          |
| `minAmount` | `string`        | Minimum single-transaction amount, decimal number in string format                 |
| `maxAmount` | `string`        | Maximum single-transaction amount, decimal number in string format                 |
| `networks`  | `Array<string>` | Supported blockchain network list for this currency, such as `ETH` / `TRX` / `SOL` |
| `precision` | `int32`         | Amount precision, number of decimal places                                         |

**Request Example**

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

**Response Example**

```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 Order Declaration

**Interface Overview**

Submit a Request Payment deposit order.

**Request Parameters**

| Field Name       | Type              | M / O / CM | Description                                                                      |
| :--------------- | :---------------- | :--------- | :------------------------------------------------------------------------------- |
| `walletId`       | `int64`           | M          | Deposit wallet ID                                                                |
| `extOrderNo`     | `string`          | M          | External order ID, globally unique                                               |
| `senderAddress`  | `string`          | M          | Payer wallet address                                                             |
| `network`        | `string`          | M          | Blockchain network: `ETH` / `TRX` / `SOL` / `POLY`                               |
| `currency`       | `string`          | M          | Currency: `USDT` / `USDC`                                                        |
| `amount`         | `string`          | M          | Declared amount. The declared amount must exactly match the final deposit amount |
| `senderName`     | `string`          | M          | Payer name                                                                       |
| `countryRegion`  | `string`          | M          | Country/region ISO 3166 code, for example `HKG`                                  |
| `contactAddress` | `string`          | M          | Payer contact address                                                            |
| `receiverName`   | `string`          | M          | Recipient merchant name                                                          |
| `message`        | `string`          | O          | Remark                                                                           |
| `materials`      | `Array<Material>` | O          | Collection of order material declaration objects                                 |

`Material` fields:

| Field Name              | Type     | M / O / CM | Description            |
| :---------------------- | :------- | :--------- | :--------------------- |
| `productType`           | `string` | M          | Product type           |
| `productName`           | `string` | M          | Product name           |
| `productPrice`          | `string` | M          | Product price          |
| `productCount`          | `string` | M          | Product quantity       |
| `productUnit`           | `string` | M          | Product unit           |
| `logisticsTrackingName` | `string` | O          | Logistics company name |
| `logisticsTrackingNo`   | `string` | O          | Tracking number        |

**Response Parameters**

| Field Name | Type     | Description      |
| :--------- | :------- | :--------------- |
| `code`     | `int32`  | Response code    |
| `message`  | `string` | Response message |

**Request Example**

```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"
    }
  ]
}
```

**Response Example**

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

### 4. Request Payment Material Supplement

**Interface Overview**

Supplement product and logistics materials for an existing declared order.

**Request Parameters**

| Field Name  | Type              | M / O / CM | Description                          |
| :---------- | :---------------- | :--------- | :----------------------------------- |
| `walletId`  | `int64`           | M          | Deposit wallet ID                    |
| `orderNo`   | `string`          | M          | Order number                         |
| `materials` | `Array<Material>` | O          | Collection of order material objects |

`Material` fields are the same as those in `1. Request Payment Order Declaration`.

**Response Parameters**

| Field Name | Type     | Description      |
| :--------- | :------- | :--------------- |
| `code`     | `int32`  | Response code    |
| `message`  | `string` | Response message |

**Request Example**

```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"
    }
  ]
}
```

**Response Example**

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

### 5. Internal Transfer

**Interface Overview**

Transfer wallet assets from custody assets to trading assets.

**Request Parameters**

| Field Name             | Type     | M / O / CM | Description                                                                                  |
| :--------------------- | :------- | :--------- | :------------------------------------------------------------------------------------------- |
| `walletId`             | `int64`  | M          | Wallet ID                                                                                    |
| `internalTransferType` | `int32`  | M          | Internal transfer type: `1` = custody assets to trading assets                               |
| `network`              | `string` | CM         | Source asset network: `ETH` / `TRX` / `SOL` / `POLY`; required when `internalTransferType=1` |
| `currency`             | `string` | M          | Currency: `USDT` / `USDC`                                                                    |
| `amount`               | `string` | M          | Amount                                                                                       |
| `extOrderNo`           | `string` | M          | External order ID, globally unique                                                           |

**Response Parameters**

| Field Name | Type                   | Description              |
| :--------- | :--------------------- | :----------------------- |
| `code`     | `int32`                | Response code            |
| `message`  | `string`               | Response message         |
| `data`     | `InternalTransferData` | Internal transfer result |

`InternalTransferData` fields:

| Field Name | Type     | Description           |
| :--------- | :------- | :-------------------- |
| `orderNo`  | `string` | Transfer order number |

**Request Example**

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

**Response Example**

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

### 6. Order Details

**Interface Overview**

Query wallet order details by order number or external order number.

**Request Parameters**

| Field Name   | Type     | M / O / CM | Description                                                              |
| :----------- | :------- | :--------- | :----------------------------------------------------------------------- |
| `walletId`   | `int64`  | M          | Wallet ID                                                                |
| `orderNo`    | `string` | CM         | Order number. Either `orderNo` or `extOrderNo` must be provided          |
| `extOrderNo` | `string` | CM         | External order number. Either `orderNo` or `extOrderNo` must be provided |

**Response Parameters**

| Field Name | Type                    | Description      |
| :--------- | :---------------------- | :--------------- |
| `code`     | `int32`                 | Response code    |
| `message`  | `string`                | Response message |
| `data`     | `WalletOrderDetailData` | Order details    |

`WalletOrderDetailData` fields:

| Field Name    | Type     | Description                                        |
| :------------ | :------- | :------------------------------------------------- |
| `orderNo`     | `string` | Order number                                       |
| `extOrderNo`  | `string` | External order number                              |
| `orderType`   | `int32`  | Order type                                         |
| `orderStatus` | `string` | See Appendix: Deposit Order Status                 |
| `fromAddress` | `string` | Initiator address                                  |
| `fromWallet`  | `string` | Source wallet                                      |
| `toAddress`   | `string` | Recipient address                                  |
| `toWallet`    | `string` | Target wallet                                      |
| `amount`      | `string` | Amount                                             |
| `network`     | `string` | Blockchain network: `ETH` / `TRX` / `SOL` / `POLY` |
| `currency`    | `string` | Currency: `USDT` / `USDC`                          |
| `expireTime`  | `int64`  | Order expiration time                              |
| `createTime`  | `int64`  | Order creation time                                |

**Request Example**

```json theme={null}
{
  "walletId": 1001,
  "orderNo": "ORDER123456789"
}
```

**Response Example**

```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. Order List

**Interface Overview**

Query wallet orders by `walletId` with pagination. Orders can be filtered by status, currency, and creation time range. The returned order data uses the unified wallet order structure and is suitable for order list pages, pre-reconciliation queries, or polling order progress by status.

**Request Parameters**

| Field Name   | Type     | M / O / CM | Description                                                                                                                         |
| :----------- | :------- | :--------- | :---------------------------------------------------------------------------------------------------------------------------------- |
| `walletId`   | `int64`  | M          | Wallet ID. It must belong to the enterprise corresponding to the current API Key, or to an ISV sub-enterprise under that enterprise |
| `status`     | `string` | O          | Order status. If not provided, all statuses are queried                                                                             |
| `currency`   | `string` | O          | Currency, such as `USDT` / `USDC`                                                                                                   |
| `startTime`  | `string` | O          | Query start time, filtered by order creation time. Format: ISO8601 with timezone, for example `2026-01-01T00:00:00Z`                |
| `endTime`    | `string` | O          | Query end time, filtered by order creation time. Format: ISO8601 with timezone, for example `2026-01-01T00:00:00Z`                  |
| `pageNumber` | `int32`  | M          | Page number, starting from `1`                                                                                                      |
| `pageSize`   | `int32`  | M          | Number of records per page. Default is `20`, maximum is `100`. Values greater than `100` are treated as `100`                       |

**Response Parameters**

| Field Name | Type                           | Description                                                                  |
| :--------- | :----------------------------- | :--------------------------------------------------------------------------- |
| `code`     | `int32`                        | Business response code. `1` means success; other values refer to error codes |
| `message`  | `string`                       | Business response message                                                    |
| `data`     | `Array<WalletOrderDetailData>` | Order list; returned when `code = 1`                                         |
| `page`     | `Page`                         | Pagination information                                                       |

`Page` fields:

| Field Name     | Type    | Description                |
| :------------- | :------ | :------------------------- |
| `pageNumber`   | `int32` | Current page number        |
| `pageSize`     | `int32` | Number of records per page |
| `totalPages`   | `int32` | Total pages                |
| `totalRecords` | `int32` | Total records              |

`WalletOrderDetailData` fields:

| Field Name    | Type     | Description                        |
| :------------ | :------- | :--------------------------------- |
| `orderNo`     | `string` | Order number                       |
| `extOrderNo`  | `string` | External order number              |
| `orderType`   | `int32`  | Order type                         |
| `orderStatus` | `string` | See Appendix: Deposit Order Status |
| `fromAddress` | `string` | Initiator address                  |
| `fromWallet`  | `string` | Source wallet                      |
| `toAddress`   | `string` | Recipient address                  |
| `toWallet`    | `string` | Target wallet                      |
| `amount`      | `string` | Amount                             |
| `network`     | `string` | Blockchain network: `ETH` / `TRX`  |
| `currency`    | `string` | Currency: `USDT` / `USDC`          |
| `expireTime`  | `int64`  | Order expiration time              |
| `createTime`  | `int64`  | Order creation time                |

**Request Example**

```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
}
```

**Response Example**

```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. Download Statement

**Interface Overview**

Statements for D-1 can be downloaded from 9:00 AM every day. The time zone is Hong Kong UTC+8.

**Request Parameters**

| Field Name     | Type     | M / O / CM | Description                                                                                                                                                 |
| :------------- | :------- | :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `walletId`     | `int64`  | M          | Wallet ID                                                                                                                                                   |
| `billDate`     | `string` | M          | Billing date in `yyyyMMdd` format                                                                                                                           |
| `modeType`     | `int32`  | M          | Authorization mode: `1` = direct connection mode; `2` = authorization mode including sub-wallets                                                            |
| `accountType`  | `int32`  | M          | Account type: `1` = custody account; `2` = trading account                                                                                                  |
| `currencyType` | `int32`  | M          | Currency type: `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 |

**Response Parameters**

| Field Name | Type             | Description           |
| :--------- | :--------------- | :-------------------- |
| `code`     | `int32`          | Response code         |
| `message`  | `string`         | Response message      |
| `data`     | `WalletBillData` | Statement information |

`WalletBillData` fields:

| Field Name | Type     | Description                               |
| :--------- | :------- | :---------------------------------------- |
| `fileName` | `string` | File name                                 |
| `fileUrl`  | `string` | Download URL of the statement zip package |

**Request Example**

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

**Response Example**

```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"
  }
}
```

# Bank Account API

| 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` |

> The following APIs share the `BankAccountData` and `FileInfo` definitions.

`BankAccountData` fields:

| Field Name              | Type              | Description                                                     |
| :---------------------- | :---------------- | :-------------------------------------------------------------- |
| `settlementAccountUID`  | `int64`           | Settlement account ID                                           |
| `walletId`              | `int64`           | Wallet ID                                                       |
| `alias`                 | `string`          | Alias                                                           |
| `accountOwnership`      | `int32`           | Relationship with wallet: `1` own / `2` other / `3` third party |
| `currency`              | `string`          | Currency: `USD`                                                 |
| `accountType`           | `int32`           | Account type: `1` RD Wallet / `2` Bank Account                  |
| `companyName`           | `string`          | Company name                                                    |
| `accountNumber`         | `string`          | RD Wallet ID or bank account number                             |
| `bankId`                | `string`          | Hong Kong bank ID, for example `003`                            |
| `beneficiaryAddress1`   | `string`          | Beneficiary address line 1. Chinese characters are not allowed  |
| `beneficiaryAddress2`   | `string`          | Beneficiary address line 2. Chinese characters are not allowed  |
| `beneficiaryAddress3`   | `string`          | Beneficiary address line 3: country/region ISO 3166 code        |
| `beneficiarySwiftCode`  | `string`          | Beneficiary bank Swift Code                                     |
| `intermediarySwiftCode` | `string`          | Intermediary bank Swift Code                                    |
| `companyCode`           | `string`          | Company profile code                                            |
| `status`                | `int32`           | Status: `0` processing / `1` success / `2` failed               |
| `paymentFiles`          | `Array<FileInfo>` | Proof of payment files                                          |
| `remark`                | `string`          | Remark                                                          |

`FileInfo` fields:

| Field Name | Type     | Description                                                            |
| :--------- | :------- | :--------------------------------------------------------------------- |
| `fileKey`  | `string` | File ID returned by the upload API                                     |
| `fileName` | `string` | File name                                                              |
| `fileUrl`  | `string` | File URL returned by the upload API. The URL is refreshed periodically |

### 9. Add Beneficiary Bank Account

**Interface Overview**

Add a beneficiary bank account.

**Request Parameters**

| Field Name              | Type              | M / O / CM | Description                                                                       |
| :---------------------- | :---------------- | :--------- | :-------------------------------------------------------------------------------- |
| `walletId`              | `int64`           | M          | Wallet ID                                                                         |
| `alias`                 | `string`          | M          | Alias of this bank account                                                        |
| `accountOwnership`      | `int32`           | M          | Ownership: `1` own / `2` other / `3` third party                                  |
| `currency`              | `string`          | M          | Currency: `USD`                                                                   |
| `accountType`           | `int32`           | M          | Account type: `1` RD Wallet / `2` Bank Account                                    |
| `companyName`           | `string`          | M          | Company name. When `accountOwnership=2`, this name must match the company profile |
| `accountNumber`         | `string`          | M          | RD Wallet ID or bank account number                                               |
| `bankId`                | `string`          | M          | Hong Kong bank ID, for example `003`                                              |
| `beneficiaryAddress1`   | `string`          | CM         | Required when `accountType=2`                                                     |
| `beneficiaryAddress2`   | `string`          | CM         | Required when `accountType=2`                                                     |
| `beneficiaryAddress3`   | `string`          | CM         | Required when `accountType=2`. Country/region ISO 3166 code                       |
| `beneficiarySwiftCode`  | `string`          | CM         | Required when `accountType=2`; must be a Hong Kong bank Swift Code                |
| `intermediarySwiftCode` | `string`          | O          | Intermediary bank Swift Code; must be a Hong Kong bank Swift Code                 |
| `companyCode`           | `string`          | CM         | Required when `accountOwnership=2`                                                |
| `paymentFiles`          | `Array<FileInfo>` | CM         | Required when `accountOwnership=3`                                                |
| `remark`                | `string`          | O          | Optional when `accountOwnership=3`                                                |

**Response Parameters**

| Field Name | Type              | Description              |
| :--------- | :---------------- | :----------------------- |
| `code`     | `int32`           | Response code            |
| `message`  | `string`          | Response message         |
| `data`     | `BankAccountData` | Bank account information |

**Request Example**

```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": "xxxx.pdf"
    }
  ],
  "remark": "remark"
}
```

**Response Example**

```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": "xxxx.pdf",
        "fileUrl": "https://xxxxx"
      }
    ],
    "remark": "remark"
  }
}
```

### 10. Update Beneficiary Bank Account

**Interface Overview**

Update non-key fields of a beneficiary bank account. `accountOwnership`, `currency`, `accountType`, `companyName`, and `companyCode` cannot be updated.

**Request Parameters**

| Field Name              | Type              | M / O / CM | Description                         |
| :---------------------- | :---------------- | :--------- | :---------------------------------- |
| `walletId`              | `int64`           | M          | Wallet ID                           |
| `settlementAccountUID`  | `int64`           | M          | Settlement account ID               |
| `alias`                 | `string`          | O          | Alias                               |
| `accountNumber`         | `string`          | O          | RD Wallet ID or bank account number |
| `bankId`                | `string`          | O          | Hong Kong bank ID                   |
| `beneficiaryAddress1`   | `string`          | O          | Beneficiary address line 1          |
| `beneficiaryAddress2`   | `string`          | O          | Beneficiary address line 2          |
| `beneficiaryAddress3`   | `string`          | O          | Beneficiary address line 3          |
| `beneficiarySwiftCode`  | `string`          | O          | Beneficiary bank Swift Code         |
| `intermediarySwiftCode` | `string`          | O          | Intermediary bank Swift Code        |
| `paymentFiles`          | `Array<FileInfo>` | CM         | Required when `accountOwnership=3`  |
| `remark`                | `string`          | O          | Optional when `accountOwnership=3`  |

**Response Parameters**

Same as `9. Add Beneficiary Bank Account`. `data` is `BankAccountData`.

**Request Example**

```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": "xxxx.pdf"
    }
  ],
  "remark": "remark"
}
```

**Response Example**

Same structure as the response example in `9. Add Beneficiary Bank Account`.

### 11. Delete Beneficiary Bank Account

**Interface Overview**

Delete a beneficiary bank account.

**Request Parameters**

| Field Name             | Type     | M / O / CM | Description           |
| :--------------------- | :------- | :--------- | :-------------------- |
| `walletId`             | `int64`  | M          | Wallet ID             |
| `settlementAccountUID` | `int64`  | M          | Settlement account ID |
| `reason`               | `string` | M          | Reason for deletion   |

**Response Parameters**

| Field Name | Type     | Description      |
| :--------- | :------- | :--------------- |
| `code`     | `int32`  | Response code    |
| `message`  | `string` | Response message |

**Request Example**

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

**Response Example**

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

### 12. Enquiry Beneficiary Bank Account

**Interface Overview**

Query beneficiary bank accounts.

**Request Parameters**

| Field Name             | Type     | M / O / CM | Description                           |
| :--------------------- | :------- | :--------- | :------------------------------------ |
| `walletId`             | `int64`  | M          | Wallet ID                             |
| `settlementAccountUID` | `int64`  | O          | Settlement account ID for exact query |
| `companyCode`          | `string` | O          | Company profile code                  |

**Response Parameters**

| Field Name | Type                     | Description       |
| :--------- | :----------------------- | :---------------- |
| `code`     | `int32`                  | Response code     |
| `message`  | `string`                 | Response message  |
| `data`     | `Array<BankAccountData>` | Bank account list |

**Request Example**

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

**Response Example**

```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": "xxxx.pdf",
          "fileUrl": "https://xxxxx"
        }
      ],
      "remark": "remark"
    }
  ]
}
```

# Convert API

## Payout Model

### 13. Payout Quote

**Interface Overview**

Obtain the price and transfer-related information for a specified currency pair. At least one of `fromAmount` or `toAmount` must be provided.

**Request Parameters**

| Field Name     | Type     | M / O / CM | Description                                                                                                              |
| :------------- | :------- | :--------- | :----------------------------------------------------------------------------------------------------------------------- |
| `walletId`     | `int64`  | M          | Wallet ID                                                                                                                |
| `fromCurrency` | `string` | M          | From currency: `USDT` / `USDC`                                                                                           |
| `fromAmount`   | `string` | CM         | From amount, supports 2 decimal places                                                                                   |
| `toCurrency`   | `string` | M          | To currency: `USD`                                                                                                       |
| `toAmount`     | `string` | CM         | To amount, supports 2 decimal places                                                                                     |
| `paymentWay`   | `string` | M          | Payment method: `RDT` / `CHATS`                                                                                          |
| `feeMode`      | `int32`  | CM         | Required if `paymentWay=CHATS`. `1` = shared by both sender and receiver (SHAR); `2` = borne entirely by the payer (OUR) |

**Response Parameters**

| Field Name | Type              | Description      |
| :--------- | :---------------- | :--------------- |
| `code`     | `int32`           | Response code    |
| `message`  | `string`          | Response message |
| `data`     | `PayoutQuoteData` | Quote data       |

`PayoutQuoteData` fields:

| Field Name        | Type     | Description                           |
| :---------------- | :------- | :------------------------------------ |
| `walletId`        | `int64`  | Wallet ID                             |
| `fromCurrency`    | `string` | From currency                         |
| `fromAmount`      | `string` | From amount                           |
| `toCurrency`      | `string` | To currency                           |
| `toAmount`        | `string` | To amount after deducting service fee |
| `paymentWay`      | `string` | Payment method                        |
| `feeMode`         | `int32`  | Fee deduction mode                    |
| `quoteId`         | `int64`  | Quote ID                              |
| `price`           | `string` | Price                                 |
| `priceExpireTime` | `string` | Price expiration time in milliseconds |
| `feeAmount`       | `string` | Service fee                           |
| `feeCurrency`     | `string` | Fee currency                          |

**Request Example**

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

**Response Example**

```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 Order

**Interface Overview**

Place a payout order based on a quote ID.

**Request Parameters**

| Field Name             | Type     | M / O / CM | Description                                                                                                                                         |
| :--------------------- | :------- | :--------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| `walletId`             | `int64`  | M          | Wallet ID                                                                                                                                           |
| `quoteId`              | `int64`  | M          | Quote ID                                                                                                                                            |
| `settlementAccountUID` | `int64`  | M          | Settlement account ID, obtained through the bank account enquiry API                                                                                |
| `purpose`              | `string` | M          | See Appendix: Purpose                                                                                                                               |
| `extOrderNo`           | `string` | M          | Unique order ID provided by the business entity. Only numbers, letters, `_`, `-`, and `*` are allowed. Must be unique under the same wallet account |

**Response Parameters**

| Field Name | Type             | Description       |
| :--------- | :--------------- | :---------------- |
| `code`     | `int32`          | Response code     |
| `message`  | `string`         | Response message  |
| `data`     | `PayoutBookData` | Payout order data |

`PayoutBookData` fields:

| Field Name             | Type     | Description                                     |
| :--------------------- | :------- | :---------------------------------------------- |
| `walletId`             | `int64`  | Wallet ID                                       |
| `quoteId`              | `int64`  | Quote ID                                        |
| `settlementAccountUID` | `int64`  | Settlement account ID                           |
| `purpose`              | `string` | Purpose                                         |
| `orderNo`              | `string` | Order number                                    |
| `fromCurrency`         | `string` | From currency                                   |
| `fromAmount`           | `string` | From amount                                     |
| `toCurrency`           | `string` | To currency                                     |
| `toAmount`             | `string` | To amount                                       |
| `paymentWay`           | `string` | Payment method                                  |
| `feeMode`              | `int32`  | Fee deduction mode                              |
| `feeAmount`            | `string` | Service fee                                     |
| `feeCurrency`          | `string` | Fee currency                                    |
| `orderStatus`          | `string` | See Appendix: Payout Order Status               |
| `createTime`           | `int64`  | Order creation time                             |
| `extOrderNo`           | `string` | Unique order ID provided by the business entity |

**Request Example**

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

**Response Example**

```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 Order Enquiry

**Interface Overview**

Query payout order information by order number or quote ID.

**Request Parameters**

| Field Name | Type     | M / O / CM | Description                                             |
| :--------- | :------- | :--------- | :------------------------------------------------------ |
| `walletId` | `int64`  | M          | Wallet ID                                               |
| `orderNo`  | `string` | CM         | At least one of `orderNo` or `quoteId` must be provided |
| `quoteId`  | `int64`  | CM         | At least one of `orderNo` or `quoteId` must be provided |

**Response Parameters**

| Field Name | Type         | Description          |
| :--------- | :----------- | :------------------- |
| `code`     | `int32`      | Response code        |
| `message`  | `string`     | Response message     |
| `data`     | `PayoutData` | Payout order details |

`PayoutData` fields:

| Field Name             | Type     | Description                                     |
| :--------------------- | :------- | :---------------------------------------------- |
| `walletId`             | `int64`  | Wallet ID                                       |
| `quoteId`              | `int64`  | Quote ID                                        |
| `orderNo`              | `string` | Order number                                    |
| `fromCurrency`         | `string` | From currency                                   |
| `fromAmount`           | `string` | From amount                                     |
| `toCurrency`           | `string` | To currency                                     |
| `toAmount`             | `string` | To amount                                       |
| `tradeFromAmount`      | `string` | Actual traded from amount                       |
| `tradeToAmount`        | `string` | Actual traded to amount                         |
| `price`                | `string` | Order price                                     |
| `tradePrice`           | `string` | Trade price                                     |
| `orderStatus`          | `string` | See Appendix: Payout Order Status               |
| `createTime`           | `int64`  | Order creation time                             |
| `finishTime`           | `int64`  | Order completion time                           |
| `errorMsg`             | `string` | Failure reason                                  |
| `settlementAccountUID` | `int64`  | Settlement account ID                           |
| `purpose`              | `string` | Purpose                                         |
| `paymentWay`           | `string` | Payment method                                  |
| `feeMode`              | `int32`  | Fee deduction mode                              |
| `feeAmount`            | `string` | Service fee                                     |
| `feeCurrency`          | `string` | Fee currency                                    |
| `refundOrderNo`        | `string` | Refund order number when the order fails        |
| `refundAmount`         | `string` | Refund amount when the order fails              |
| `refundCurrency`       | `string` | Refund currency when the order fails            |
| `extOrderNo`           | `string` | Unique order ID provided by the business entity |

**Request Example**

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

**Response Example**

```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 Re-Settle

**Interface Overview**

Re-initiate settlement after a refund or failed settlement.

**Request Parameters**

| Field Name             | Type     | M / O / CM | Description                                                                    |
| :--------------------- | :------- | :--------- | :----------------------------------------------------------------------------- |
| `walletId`             | `int64`  | M          | Wallet ID                                                                      |
| `orderNo`              | `string` | M          | Original payout order number                                                   |
| `refundOrderNo`        | `string` | M          | Refund order number                                                            |
| `settlementAccountUID` | `int64`  | M          | Settlement account ID                                                          |
| `purpose`              | `string` | M          | See Appendix: Purpose                                                          |
| `remark`               | `string` | M          | Remark                                                                         |
| `paymentWay`           | `string` | M          | Payment method: `RDT` / `CHATS`                                                |
| `feeMode`              | `int32`  | CM         | Required if `paymentWay=CHATS`; meaning is the same as in the Payout Quote API |

**Response Parameters**

| Field Name | Type                 | Description        |
| :--------- | :------------------- | :----------------- |
| `code`     | `int32`              | Response code      |
| `message`  | `string`             | Response message   |
| `data`     | `PayoutReSettleData` | Re-settlement data |

`PayoutReSettleData` fields:

| Field Name             | Type     | Description                  |
| :--------------------- | :------- | :--------------------------- |
| `walletId`             | `int64`  | Wallet ID                    |
| `orderNo`              | `string` | Original payout order number |
| `refundOrderNo`        | `string` | Refund order number          |
| `settlementAccountUID` | `int64`  | Settlement account ID        |
| `purpose`              | `string` | Purpose                      |
| `remark`               | `string` | Remark                       |
| `paymentWay`           | `string` | Payment method               |
| `feeMode`              | `int32`  | Fee deduction mode           |
| `amount`               | `string` | Re-settlement amount         |
| `currency`             | `string` | Re-settlement currency       |
| `feeAmount`            | `string` | Service fee                  |
| `feeCurrency`          | `string` | Fee currency                 |

**Request Example**

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

**Response Example**

```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"
  }
}
```

# Callback

### Callback Request Specification

| Item         | Value                                                                                                                |
| :----------- | :------------------------------------------------------------------------------------------------------------------- |
| Method       | `POST`                                                                                                               |
| Content-Type | `application/json; charset=utf-8`                                                                                    |
| Request Body | JSON. The structure depends on the event type, such as order result notification or bank account result notification |
| Timeout      | Default 8 seconds. Timeout is treated as failure and may trigger business-level retries                              |

**Request Headers**

| Header         | Description                                                                    |
| :------------- | :----------------------------------------------------------------------------- |
| `X-Api-Key`    | Merchant `api_key`, identifying the merchant to which the callback belongs     |
| `X-Timestamp`  | UTC millisecond timestamp string when the callback is sent                     |
| `X-Nonce`      | Unique random string for this callback, 32-character hex, used for idempotency |
| `X-Signature`  | HMAC-SHA256 signature                                                          |
| `Content-Type` | Fixed as `application/json; charset=utf-8`                                     |

### Signature Verification

The algorithm is the same as inbound API signing and uses the same `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`: the path part of the callback URL, excluding domain and query string.
* `BODY`: the raw HTTP request body bytes.

#### Verification Steps

1. Read request headers: `X-Timestamp`, `X-Nonce`, `X-Signature`, and `X-Api-Key`.
2. Validate the timestamp window: `abs(now_ms - X-Timestamp) <= 5 * 60 * 1000`; otherwise reject with `401`.
3. Read the raw request body before any parsing or deserialization.
4. Recalculate the signature using `sign_secret` and the raw body.
5. Compare the calculated signature and `X-Signature` using constant-time comparison.
6. Use `X-Nonce` as the idempotency key. If it has already been processed, return the previous result directly.

#### Common Pitfalls

* The signature must be calculated over the raw bytes. JSON re-serialization, key reordering, whitespace changes, or encoding changes will cause signature mismatch.
* `PATH` must match exactly. Do not add or remove a trailing slash, URL-decode it, or remove gateway prefixes.
* `X-Signature` is lowercase hex. The method is fixed as uppercase `POST`.
* Empty body must also be signed. `SHA256_HEX("")` is `e3b0c442...b855`.

#### Reference Implementations

**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))
}
```

### Response Requirements

* The merchant system must respond within 8 seconds.
* HTTP `2xx` status code is treated as successful delivery.
* Non-`2xx`, timeout, or business error response is treated as failed delivery.
* Recommended response body:

Success:

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

Failure:

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

### Idempotency and Replay Protection

* **Idempotency key**: use `X-Nonce` as the idempotency key and persist it. If the same key is received again, return the previous result directly.
* **Replay protection**: validate that `X-Timestamp` is within ±5 minutes of the server time.
* **Strict signature verification**: reject any request with invalid signature using `4xx` and do not enter business processing.

### Callback Data Types

### 17. Order Result Notification

| Field Name    | Type     | Description                                        |
| :------------ | :------- | :------------------------------------------------- |
| `orderNo`     | `string` | Order number                                       |
| `currency`    | `string` | Currency: `USDT` / `USDC`                          |
| `network`     | `string` | Blockchain network: `ETH` / `TRX` / `SOL` / `POLY` |
| `status`      | `string` | Order status. See Appendix: Deposit Order Status   |
| `amount`      | `string` | Amount                                             |
| `fromAddress` | `string` | Initiator address                                  |
| `fromWallet`  | `string` | Source wallet                                      |
| `toAddress`   | `string` | Recipient address                                  |
| `toWallet`    | `string` | Target wallet                                      |
| `txHash`      | `string` | Transaction hash                                   |
| `orderType`   | `int32`  | Order type                                         |
| `extOrderNo`  | `string` | External order number                              |

**Sample Data**

```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. Add Bank Account Result Notification

| Field Name              | Type     | Description                                              |
| :---------------------- | :------- | :------------------------------------------------------- |
| `settlementAccountUID`  | `int64`  | Settlement account ID                                    |
| `walletId`              | `int64`  | Wallet ID                                                |
| `alias`                 | `string` | Alias                                                    |
| `accountOwnership`      | `int32`  | Ownership: `1` own / `2` other / `3` third party         |
| `currency`              | `string` | Currency: `USD`                                          |
| `accountType`           | `int32`  | Account type: `1` RD Wallet / `2` Bank Account           |
| `accountName`           | `string` | Account name                                             |
| `accountNumber`         | `string` | RD Wallet ID or bank account number                      |
| `bankId`                | `string` | Hong Kong bank ID, for example `003`                     |
| `beneficiaryAddress1`   | `string` | Beneficiary address line 1                               |
| `beneficiaryAddress2`   | `string` | Beneficiary address line 2                               |
| `beneficiaryAddress3`   | `string` | Beneficiary address line 3: country/region ISO 3166 code |
| `beneficiarySwiftCode`  | `string` | Beneficiary bank Swift Code                              |
| `intermediarySwiftCode` | `string` | Intermediary bank Swift Code                             |
| `companyCode`           | `string` | Company profile code                                     |
| `status`                | `int32`  | Status: `0` processing / `1` success / `2` failed        |

**Sample Data**

```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 Result Notification

| Field Name             | Type     | Description                                                                                                                                           |
| :--------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `walletId`             | `int64`  | Wallet ID                                                                                                                                             |
| `quoteId`              | `int64`  | Quote ID                                                                                                                                              |
| `orderNo`              | `string` | Order number                                                                                                                                          |
| `fromCurrency`         | `string` | From currency: `USDT` / `USDC`                                                                                                                        |
| `fromAmount`           | `string` | From amount                                                                                                                                           |
| `toCurrency`           | `string` | To currency: `USD`                                                                                                                                    |
| `toAmount`             | `string` | To amount after deducting service fee                                                                                                                 |
| `tradeFromAmount`      | `string` | Actual traded from amount                                                                                                                             |
| `tradeToAmount`        | `string` | Actual traded to amount                                                                                                                               |
| `price`                | `string` | Order price                                                                                                                                           |
| `tradePrice`           | `string` | Trade price                                                                                                                                           |
| `orderStatus`          | `string` | See Appendix: Payout Order Status                                                                                                                     |
| `createTime`           | `int64`  | Order creation time                                                                                                                                   |
| `finishTime`           | `int64`  | Order completion time                                                                                                                                 |
| `errorMsg`             | `string` | Failure reason                                                                                                                                        |
| `settlementAccountUID` | `int64`  | Settlement account ID                                                                                                                                 |
| `purpose`              | `string` | See Appendix: Purpose                                                                                                                                 |
| `paymentWay`           | `string` | Payment method: `RDT` / `CHATS`                                                                                                                       |
| `feeMode`              | `int32`  | Fee deduction mode. Default value: `1`. `1` = shared by both sender and receiver (SHAR); `2` = borne entirely by the payer (OUR)                      |
| `feeAmount`            | `string` | Service fee                                                                                                                                           |
| `feeCurrency`          | `string` | Fee currency                                                                                                                                          |
| `refundOrderNo`        | `string` | Available when the payout order status is `SETTLING_FAILED`; used to re-initiate settlement                                                           |
| `extOrderNo`           | `string` | Unique order ID provided by the business entity. Only numbers, letters, `_`, `-`, and `*` are allowed. Must be unique under the same merchant account |

**Sample Data**

```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 Refund Result Notification

| Field Name       | Type     | Description                          |
| :--------------- | :------- | :----------------------------------- |
| `walletId`       | `int64`  | Wallet ID                            |
| `orderNo`        | `string` | Payout order number                  |
| `refundOrderNo`  | `string` | Refund order number                  |
| `refundAmount`   | `string` | Actual refund amount                 |
| `refundCurrency` | `string` | Refund currency                      |
| `refundReason`   | `string` | Refund reason, returned if available |
| `refundTime`     | `int64`  | Refund time                          |

**Sample Data**

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

### 21. Payout Re-Settle Result Notification

| Field Name             | Type     | Description                                                                                                                      |
| :--------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------- |
| `walletId`             | `int64`  | Wallet ID                                                                                                                        |
| `orderNo`              | `string` | Payout order number                                                                                                              |
| `refundOrderNo`        | `string` | Refund order number                                                                                                              |
| `settlementAccountUID` | `int64`  | Settlement account ID                                                                                                            |
| `purpose`              | `string` | See Appendix: Purpose                                                                                                            |
| `remark`               | `string` | Remark                                                                                                                           |
| `paymentWay`           | `string` | Payment method: `RDT` / `CHATS`                                                                                                  |
| `feeMode`              | `int32`  | Fee deduction mode. Default value: `1`. `1` = shared by both sender and receiver (SHAR); `2` = borne entirely by the payer (OUR) |
| `amount`               | `string` | Settlement amount                                                                                                                |
| `currency`             | `string` | Settlement currency                                                                                                              |
| `feeAmount`            | `string` | Service fee                                                                                                                      |
| `feeCurrency`          | `string` | Fee currency                                                                                                                     |
| `createTime`           | `int64`  | Order creation time                                                                                                              |
| `finishTime`           | `int64`  | Order completion time                                                                                                            |
| `orderStatus`          | `string` | Re-settlement order status. See Appendix: Payout Order Status                                                                    |

**Sample Data**

```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"
}
```

# Appendix

### Response Code

| Code   | Description                        |
| :----- | :--------------------------------- |
| `1`    | success                            |
| `6001` | failed, general business failure   |
| `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 less than minimum amount    |
| `6306` | amount greater than maximum amount |
| `6307` | outside of business hours          |
| `6401` | address already exists             |
| `6406` | processing                         |
| `6801` | duplicate request                  |
| `6802` | profile error                      |
| `6803` | reach the max limit                |

### Payout Order Status

| Code              | Description            | Remark                                          |
| :---------------- | :--------------------- | :---------------------------------------------- |
| `SUBMITTED`       | Submitted              | Order submitted                                 |
| `CONVERTING`      | Exchanging             | Order exchanging                                |
| `SETTLING`        | Settling               | Exchange successful, proceeding with settlement |
| `SETTLING_FAILED` | Settlement failed      | Exchange successful, settlement failed          |
| `SETTLING_REFUND` | Refund processing      | Refunded after successful settlement            |
| `SUCCESSFUL`      | Successful transaction | Order processed successfully                    |
| `FAILED`          | Transaction failed     | Order processing failed                         |

### Deposit Order Status

| Code                    | Description                      | Remark                                                                                                        |
| :---------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------ |
| `SUBMITTED`             | Submitted                        | Order submitted                                                                                               |
| `VERIFYING`             | Order verification               | Security verification after order submission. Applies only to Request Payment                                 |
| `AWAIT_FOR_RECEIVE`     | Awaiting payment                 | Order created successfully and awaiting payment. Applies only to Request Payment                              |
| `PAYMENT_VERIFYING`     | Payment verification in progress | Payment has been received by the platform and is under security verification. Applies only to Request Payment |
| `AWAIT_FOR_DECLARATION` | Additional documents required    | Trade documents pending submission. Applies only to Request Payment                                           |
| `DECLARATION_REVIEW`    | Document review in progress      | Document review in progress                                                                                   |
| `SUCCESS`               | Transaction successful           | Order successful                                                                                              |
| `FAILED`                | Transaction failed               | Order failed                                                                                                  |
| `CLOSED`                | Transaction closed               | Order closed due to expiration                                                                                |
| `RETURNING`             | Refund processing                | Refund processing                                                                                             |
| `RETURNED`              | Refunded                         | Refund processed successfully                                                                                 |
| `IN_PROGRESS`           | Payment verification in progress | Payment has been received by the platform and is under security verification. Applies only to Deposit         |

### Order Type

| Code | Description       |
| :--- | :---------------- |
| `1`  | Deposit           |
| `2`  | Wallet Transfer   |
| `3`  | Internal Transfer |
| `4`  | Request Payment   |
| `5`  | Withdraw          |

### Field Description: amount

This field indicates the transaction amount. Its type is `string`. Precision requirements vary by currency type:

* **Digital Currency**: generally supports up to 6 decimal places to meet on-chain transaction precision requirements.
* **Fiat Currency**: generally supports up to 2 decimal places, accurate to cents.
* **Japanese Yen (JPY)**: JPY has no decimal places. The amount must be an integer and must not contain a decimal part.

Please strictly control the amount format according to the currency type to avoid precision errors or processing exceptions.

### Purpose

| Code     | Description                                                                                             |
| :------- | :------------------------------------------------------------------------------------------------------ |
| `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 fees, trademark fees, patent fees, and copyright fees                                           |
| `PMT013` | Fees for brokers, front-end fee, commitment fee, guarantee fee, and custodian fee                       |
| `PMT014` | Fees for advisors, technical assistance, and academic knowledge, including remuneration for specialists |
| `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                                                                            |

### Country/Region Code

[Country/Region Code](/en/others-resources/country-code)

### Industry Code

[Industry Code](/en/others-resources/industry-code)

### Profile Error Description

The following messages are returned by profile validation and grouped by module.

**\[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:[area name]`
* `The operating place is not supported:[area name]`
* `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:[corresponding value]`
* `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.`