# bitwin介接文件(币盈)
## 说明
### 环境网址
测试环境 : `https://stage-api.bitwin.ai`
正式环境 : `https://api.bitwin.ai`
### 版本
v4 : `/api/v4`
### 鉴权信息(Header)
`"X-Bitwin-Access" : "your api access"`
<font color=#FF0000>＊请注意每180天会更新</font>
### 资料请用Json格式提交
`Content-Type:application/json`
### 签名金钥&鉴权信息金钥
请找商务获取
### 版本差異（v3）
新增法币栏位(FiatCurrency)
栏位调整： MerchantRMB更名为FiatCurrencyAmount
### 系统支持币种
| 币别 | 說明 |
|:-|:-|
| BTC | Bitcoin |
| ETH | Ethereum(以太坊) |
| USDT_ERC20 | Ethereum USDT(ERC-20) |
| USDT_TRC20 | Tron USDT(TRC-20) |
| USDT_BEP20 | Binance smart chain USDT(BEP-20)<font color=#FF0000>[维护中]</font> |
## 目录
* [交易金额限制](#交易金额限制)
* [签名规则](#签名规则)
* [建立付款订单](#建立付款订单) : `POST /api/v4/CreateCryptoPayOrder`
* [查询付款订单](#查询付款订单) : `POST /api/v4/QueryCryptoPayOrder`
* [建立商户出款单](#建立商户出款单) : `POST /api/v4/MerchantWithdraw`
* [查询商户出款单](#查询商户出款单) : `POST /api/v4/QueryMerchantWithdraw`
* [查询建议汇率](#查询建议汇率) : `POST /api/v4/ExchangeRate`
* [Bitwin会员钱包绑定](#Bitwin会员钱包绑定) : `POST /api/v4/BuildRelationUser`
* [[notify] 支付订单回调](#支付订单回调) : `由Bitwin系统发起至贵方提供的网址`
* [[notify] 商户出款回调](#商户出款回调) : `由Bitwin系统发起至贵方提供的网址`
* [[notify] Bitwin会员钱包绑定回调](#Bitwin会员钱包绑定回调) : `由Bitwin系统发起至贵方提供的网址`
## 交易金额限制
| 币别 | 交易最小数量 | 交易最大数量 | 支援小数单位 |
|:-:|:-|:-|:-|
| BTC | 0.0007 | 1 | 0.00001 |
| ETH | 0.025 | 10 | 0.0001 |
| USDT_ERC20 | 7 | 无上限 | 0.01 |
| USDT_TRC20 | 7 | 无上限 | 0.01 |
| USDT_BEP20 | 7 | 无上限 | 0.01 |
**EX 1：单次BTC交易至少0.0001BTC，可以接受0.00012BTC，不接受0.000123BTC**
**EX 2：交易单位為「聪」（Satoshi、Sat），故交易数量务必再乘上10^8。**
## 签名规则
将参数(除了Sign)，依照升冪排序后，各value用,连接，最后再加上签名金钥，md5后转为全大写即为sign。
**范例**
```
开发者令牌为：A299953927BB4959F7807B0F4A188E0C
传送参数：
{
"MerchantId": "bitwinTest",
"MerchantOrderId": "29367465624676320",
"TimeStamp": "1620371899034",
"Sign": ""
}
将参数排序 顺序为[已拿除sign]
["MerchantId", "MerchantOrderId", "TimeStamp"]
并将资料依序用value并用","连接,最后再加上开发者令牌
＊参数内容为空则不需加密
加密内容为
bitwinTest,DA2021062821004,1620371899034,A299953927BB4959F7807B0F4A188E0C
md5後即為sign
5C94029301A669EEC49EAB32768F5875
```
## 建立付款订单
**URL** : `/api/v4/CreateCryptoPayOrder`
**Method** : `POST`
**请求参数**
| 参数|是否必填|类型|参数介绍 |
|:-------------|:-------------|:-------------|:-------------|
| MerchantId | Y | string | 商户编号 |
| MerchantUserId | N | string | 商户会员编号 |
| MerchantOrderId | Y | string | 商户订单编号 |
| OrderDescription | N | string | 商户订单备注 |
| Amount | Y | string | 金额 |
| FiatCurrency | N | string | 订单法币单位 （如未填写预设人民币） |
| FiatCurrencyAmount | N | string | 订单等值法币金额(商户) |
| Symbol | Y | string | 币种(BTC,ETH,USDT_ERC20,USDT_TRC20,USDT_BEP20) |
| CallBackUrl | Y | string | 回调网址 |
| TimeStamp | Y | string | 时间戳记 |
| Sign | Y | string | 签名 |
**回应参数**
| 参数|参数介绍 |
|:-------------|:-------------|
| OrderId | Bitwin订单编号 |
| Qrcode | QRCODE 网址 |
| Amount | 订单提交金额 |
| RealAmount | 会员需付款金额 |
| CryptoWallet | 付款地址 |
| ReturnCode | 回应代码 |
| ReturnMessage | 回应讯息＊ code非200才会有内容 |
| Sign | 签名 |
[GoTop](#目录)
## 查询付款订单
**URL** : `/api/v4/QueryCryptoPayOrder`
**Method** : `POST`
**请求参数**
| 参数 | 是否必填 | 类型 | 参数介绍 |
|:-------------|:-------------|:-------------|:-------------|
| MerchantId | Y | string | 商户编号 |
| MerchantOrderId | N | string | 商户订单编号(与OrderId择一) |
| OrderId | N | string | Bitwin订单编号(与MerchantOrderId择一) |
| TimeStamp | Y | string | 时间戳记 |
| Sign | Y | string | 签名 |
**回应参数**
| 参数 | 参数介绍 |
|:-------------|:-------------|
| OrderId | Bitwin订单编号 |
| MerchantOrderId | 商户订单编号 |
| MerchantUserId | 商户使用者编号 |
| OrderDescription | 商户订单备注 |
| Symbol | 币种(BTC,ETH,USDT_ERC20,USDT_TRC20,USDT_BEP20) |
| Amount | 订单提交金额 |
| RealAmount | 会员需付款金额 |
| FiatCurrency | 订单法币单位 |
| FiatCurrencyAmount | 订单等值法币金额(商户) |
| ExchangeRMB | 订单等值人民币(系统) |
| OrderStatus | 订单状态(PENDING,SUCCESS,FAIL) |
| CallBackUrl | 回调网址 |
| ReturnCode | 回应代码 |
| ReturnMessage | 回应讯息 ＊code非200 才会有内容 |
| Sign | 签名 |
[GoTop](#目录)
## 建立商户出款单
**URL** : `/api/v4/MerchantWithdraw`
**Method** : `POST`
**请求参数**
| 参数 | 是否必填 | 类型 | 参数介绍 |
|:-------------|:-------------|:-------------|:-------------|
| MerchantId | Y | string | 商户编号 |
| MerchantUserId | N | string | 商户会员编号 |
| MerchantWithdrawId | Y | string | 商户提款编号 |
| UserWallet | Y | string | 商户会员钱包地址 |
| Symbol | Y | string | 币种(BTC,ETH,USDT_ERC20,USDT_TRC20,USDT_BEP20) |
| Amount | Y | string | 金额 |
| FiatCurrency | N | string | 订单法币单位 （如未填写预设人民币） |
| FiatCurrencyAmount | N | string | 订单等值法币金额(商户) |
| CallBackUrl | Y | string | 回调网址 |
| TimeStamp | Y | string | 时间戳记 |
| Sign | Y | string | 签名 |
**回应参数**
| 参数 | 参数介绍 |
|:-------------|:-------------|
| WithdrawId | Bitwin提款订单编号 |
| MerchantWithdrawId | 商户提款编号 |
| ReturnCode | 回应代码 |
| ReturnMessage | 回应讯息 ＊code非200 才会有内容 |
| Sign | 签名 |
[GoTop](#目录)
## 查询商户出款单
**URL** : `/api/v4/QueryMerchantWithdraw`
**Method** : `POST`
**请求参数**
| 参数 | 是否必填 | 类型 | 参数介绍 |
|:-------------|:-------------|:-------------|:-------------|
| MerchantId | Y | string | 商户编号 |
| WithdrawId | N | string | Bitwin提款订单编号(与MerchantWithdrawIdID择一) |
| MerchantWithdrawId | N | string | 商户提领订单编号(与WithdrawId择一) |
| TimeStamp | Y | string | 时间戳记 |
| Sign | Y | string | 签名 |
**回应参数**
| 参数 | 参数介绍 |
|:-------------|:-------------|
| MerchantUserId | 商户使用者编号 |
| UserWallet | 会员钱包地址 |
| MerchantWithdrawId | 商户提款订单编号 |
| WithdrawId | Bitwin提款订单编号 |
| Symbol | 币种(BTC,ETH,USDT_ERC20,USDT_TRC20,USDT_BEP20) |
| Amount | 订单提交金额 |
| FiatCurrency | 订单法币单位 （如未填写预设人民币） |
| FiatCurrencyAmount | 订单等值法币金额(商户) |
| ExchangeRMB | 订单等值人民币(系统) |
| Status | 订单状态(PENDING,SUCCESS,FAIL) |
| WithdrawDateTime | 提领发起时间 |
| ApprovedDateTime | 审核时间 |
| ReturnCode | 回应代码 |
| ReturnMessage | 回应讯息 ＊code非200 才会有内容 |
| Sign | 签名 |
[GoTop](#目录)
## 查询建议汇率
**URL** : `/api/v4/ExchangeRate`
**Method** : `POST`
**请求参数**
| 参数 | 是否必填 | 类型 | 参数介绍 |
|:-------------|:-------------|:-------------|:-------------|
| Symbol | Y | string | 币种(BTC,ETH,USDT_ERC20,USDT_TRC20,USDT_BEP20) |
| TimeStamp | Y | string | 时间戳 |
**回应参数**
| 参数 | 参数介绍 |
|:-------------|:-------------|
| RMBRate | 建议汇率 |
| RMBBuyRate | 建议汇率 |
| ReturnCode | 回应代码 |
| ReturnMessage | 回应讯息 ＊code非200 才会有内容 |
[GoTop](#目录)
## Bitwin会员钱包绑定
**URL** : `/api/v4/BuildRelationUser`
**Method** : `POST`
**请求参数**
| 参数 | 是否必填 | 类型 | 参数介绍 |
|:-------------|:-------------|:-------------|:-------------|
| MerchantId | Y | string | 商户编号 |
| MerchantUserId | Y | string | 商户会员编号（回调辨识用 |
| CallBackUrl | Y | string | 回调网址 |
| TimeStamp | Y | string | 时间戳记 |
| Sign | Y | string | 签名 |
**回应参数**
| 参数 | 参数介绍 |
|:-------------|:-------------|
| QrcodeData | 会员扫码资料 |
| QrcodeImageUrl | 会员扫码的网址（需使用Bitwin App |
| ReturnCode | 回应代码 |
| ReturnMessage | 回应讯息 ＊code非200 才会有内容 |
| Sign | 签名 |
[GoTop](#目录)
## 支付订单回调
**URL** : `Bitwin系统回调贵方提供的网址(付款完成才會回調)`
**Method** : `POST`
**参数**
| 参数 | 类型 | 参数介绍 |
|:-------------|:-------------|:-------------|
| MerchantId | string | 商户编号 |
| MerchantOrderId | string | 商户订单编号 |
| OrderId | string | Bitwin订单编号 |
| Symbol | string | 币种(BTC,ETH,USDT_ERC20,USDT_TRC20,USDT_BEP20) |
| Amount | string | 订单提交金额 |
| PayAmount | string | 会员需付款金额 |
| FiatCurrency |string | 订单法币单位 （如未填写预设人民币） |
| FiatCurrencyAmount | string | 订单等值法币金额(商户) |
| ExchangeRMB | string | 订单等值人民币(系统) |
| PayUnixTimestamp | string | 付款时间 |
| Sign | string | 签名 |
**回应(貴司)**
成功请回传: SUCCESS
失败请回传: ERROR:失败原因
[GoTop](#目录)
## 商户出款回调
**URL** : `Bitwin系统回调贵方提供的网址`
**Method** : `POST`
**参数**
| 参数 | 类型 | 参数介绍 |
|:-------------|:-------------|:-------------|
| MerchantId | string | 商户编号 |
| MerchantUserId | string | 商户会员编号 |
| MerchantWithdrawId | string | 商户提款订单编号 |
| UserWallet | string | 会员钱包地址 |
| WithdrawId | string | Bitwin提款订单编号 |
| WithdrawAmount | string | 提款金额 |
| FiatCurrency |string | 订单法币单位 （如未填写预设人民币） |
| FiatCurrencyAmount | string | 订单等值法币金额(商户) |
| ExchangeRMB | string | 订单等值人民币(系统) |
| Symbol | string | 币种(BTC,ETH,USDT_ERC20,USDT_TRC20,USDT_BEP20) |
| ReplyDateTime | string | 请款时间 |
| Sign | string | 签名 |
**回应(貴司)**
成功请回传: SUCCESS
失败请回传: ERROR:失败原因
[GoTop](#目录)
## Bitwin会员钱包绑定回调
**URL** : `Bitwin系统回调贵方提供的网址`
**Method** : `POST`
**参数**
| 参数 | 类型 | 参数介绍 |
|:-------------|:-------------|:-------------|
| MerchantId | string | 商户编号 |
| MerchantUserId | string | 商户会员编号 |
| UserName | string | Bitwin會員名稱 |
| BTC | string | 会员钱包地址(BTC) <font color=#FF6600>*会员有该钱包才会显示该栏位</font>|
| ETH | string | 会员钱包地址(ETH) <font color=#FF6600>*会员有该钱包才会显示该栏位</font>|
| USDT_ERC20 | string | 会员钱包地址(USDT_ERC20) <font color=#FF6600>*会员有该钱包才会显示该栏位</font>|
| USDT_TRC20 | string | 会员钱包地址(USDT_TRC20) <font color=#FF6600>*会员有该钱包才会显示该栏位</font>|
| USDT_BEP20 | string | 会员钱包地址(USDT_BEP20) <font color=#FF6600>*会员有该钱包才会显示该栏位</font>|
| Sign | string | 签名 |
**回应(貴司)**
成功请回传: SUCCESS
失败请回传: ERROR:失败原因
[GoTop](#目录)
Sign in with Wallet
Connect another wallet