文档说明

Bying数字资产交易开发文档

阅读对象

本文阅读对象:DAPP系统(有转账需求的区块链应用)集成Bying数字资产交易涉及的技术架构师,研发工程师,测试工程师,系统运维工程师。

数字资产交易模式

DAPP交易

DAPP数字资产交易又称移动端数字资产交易,是商户通过在移动端应用DAPP中调用Bying数字资产交易模块定义的scheme完成数字资产交易的模式。

扫码交易

扫码交易是商户系统按Bying数字资产交易的协议生成交易二维码,用户再用Bying钱包(或移动端的浏览器,前提必须安装Bying钱包)“扫一扫”完成交易的模式。该模式适用于PC网站数字资产交易、实体店单品或订单数字资产交易、媒体广告数字资产交易等场景。

数字资产交易账户

匿名账户

匿名账户无需平台注册认证,但是不提供通过Bying钱包交易接口发送支付后的交易结果回调服务,只返回交易后的交易Hash,可通过Bying钱包查看交易结果。

注册账户

注册账户需提交相应资料至Bying官方,审核资料通过后,Bying官方将开发时需要的账户信息发送给注册账户。注册账户除匿名账户所有的功能外,还提供交易结果回调服务,以及交易结果查询服务。

账户参数与对应关系如表。

账户参数 API参数名称 详细说明
DAPPID dappid dappid 是Bying钱包注册用户DAPP的唯一标识,在申请通过后由Bying官方分配,用于标识该应用。
DAPP秘钥 dappkey 交易过程生成签名的密钥,仅保留在商户系统和Bying数字资产交易后台,不会在网络中传播。商户妥善保管该 Key,切勿在网络中传输,不能在其他客户端中存储,保证 key不会被泄漏。

注册需信息

账户参数 API参数名称 详细说明
商户名称 mername Merdemo
应用名称 demo Demo
授权域名 oauthdomain api.bying.io或IP
回调推送方法 callbackUrl http://api.bying.io:8089/api/thirdparty/tx/callBackDemoUrl

接口规则

协议规则

商户接入Bying支付,调用API必须遵循以下规则:

规则名称 详细说明
传输方式 为保证交易安全性,采用HTTPS传输
提交方式 采用POST方法提交
数据格式 1、 api接口提交和返回数据都为JSON格式
2、 调用Bying钱包交易参数使用URLEncoder.encode处理
字符编码 统一采用UTF-8字符编码
签名算法 MD5
签名要求 请求和接收数据均需要校验签名,详细方法请参考安全规范-签名算法
判断逻辑 先判断协议字段返回,再判断业务返回,最后判断交易状态

交易数量

接口中的交易数量为带小数的字符串,比特币系列精确到小数点后8位,以太系列精确到小数点18位。

交易类型

scan-扫码提交交易, dapp-Dapp调起Bying钱包交易, native-其他APP调起Bying钱包交易,交易结果交易类型可参照这里。

时间

标准北京时间,时区为东八区;如果商户的系统时间为非标准北京时间。参数值必须根据商户系统所在时区先换算成标准北京时间, 例如商户所在地为0时区的伦敦,当地时间为2014年11月11日0时0分0秒,换算成北京时间为2014年11月11日8时0分0秒。

时间戳

标准北京时间,时区为东八区,自1970年1月1日 0点0分0秒以来的秒数。注意:部分系统取到的值为毫秒级,需要转换成秒(10位数字)。

商户订单号

商户交易的订单号由商户自定义生成,Bying数字资产交易要求商户订单号保持唯一性(建议根据当前系统时间加随机序列来生成订单号)。重新发起一笔支付要使用原订单号,避免重复支付;已提交过交易的订单号不能重新发起交易。

支持数字币类型

币种名称 币种符号 备注
比特币 BTC 公链
以太坊 ETH 公链
莱特币 LTC 公链
以太经典 ETC 公链
零币 ZEC 公链
量子 QTUM 公链
达世 DASH 公链
狗狗币 DOGE 公链
维基币 WICC 公链(即将支持)
超级比特币 SBTC 公链-分叉
世界比特币 WBTC 公链-分叉
闪电比特币 LBTC 公链-分叉
比特币现金 BCH 公链-分叉
比特币矿石 BCO 公链-分叉(即将支持)
所有以太坊ERC20 Token ERC20 Token 基于以太坊的ERC20 Token均支持

安全规范

签名算法

签名生成的通用步骤如下(示例):
第一步,设所有发送或者接收到的数据为集合M,将集合M内非空参数值的参数按照参数名ASCII码从小到大排序(字典序),使用URL键值对的格式(即key1=value1&key2=value2…)拼接成字符串stringA。
特别注意以下重要规则:
参数名ASCII码从小到大排序(字典序);
如果参数的值为空不参与签名;
参数名区分大小写;
验证调用返回或Bying主动通知签名时,传送的sign参数不参与签名,将生成的签名与该sign值作校验。
Bying接口可能增加字段,验证签名时必须支持增加的扩展字段
第二步,在stringA最后拼接上key得到stringSignTemp字符串,并对stringSignTemp进行MD5运算,再将得到的字符串所有字符转换为大写,得到sign值signValue。

举例:

                                        假设传送的参数如下:
dappid: byingd930ea5d5a258f4f
symbol: BTC
quantity : 8.88
nonce: ibuaiVcKdpRxkhJA

第一步:对参数按照key=value的格式,并按照参数名ASCII字典序排序如下:
stringA="dappid=byingd930ea5d5a258f4f&nonce=ibuaiVcKdpRxkhJA&quantity=8.88&
symbol=BTC";

第二步:拼接API密钥:
stringSignTemp=stringA+"&dappkey=192006250b4c09247ec02edce69f6a2d"
//注:key为商户平台设置的密钥key
sign=MD5(stringSignTemp).toUpperCase()="9A0A8659F005D6984697E2CA0A9CF3B7"
//注:MD5签名方式

最终得到最终发送的数据:
stringSignFinal = URLEncoder.encode(stringSignTemp+”&sign=”+sign)

生成随机数算法

Bying数字资产交易API接口协议中包含字段 nonce,主要保证签名不可预测。我们推荐生成随机数算法如下:调用随机数函数生成,将得到的值转换为字符串。

商户回调API安全

在普通的网络环境下,HTTP请求存在DNS劫持、运营商插入广告、数据被窃取,正常数据被修改等安全风险。商户回调接口使用HTTPS协议可以保证数据传输的安全性。所以Bying建议商户提供给Bying支付的各种回调采用HTTPS协议。

DAPP数字资产交易

设置授权域名

通过提交注册资料时提供。

设置支付回调链接

通过提交注册资料时提供。

Sdk(scheme)交易

扫码交易

业务流程时序图

调起Bying Sdk(scheme)交易接口

请求参数

字段名 变量名 必填 类型 示例值 描述
DAPPID dappid String(32) 1230000109 Bying分配的账户号(匿名账户不用填写)
请求类型 callType String(10) dapp 请求交易类型
商户名称 mername String(20) 天天DA 商户名称(不用签名,仅用于钱包展示)
商户订单编号 outTradeNum String(32) 20180518125346 商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-且在同一个商户号下唯一。(匿名账户不用填写)
币种符号 symbol String(10) EOS 币种的简称,请参照 支持数字币类型
Gas限制 gasLimit Int 61000 ETH系列gaslimit赋值,假如自定义合约内容则需要手动去赋值。假如不传contractData不为空则默认值未61000,假如contractData为空,则默认值为21000
目的地址 toAddress String(50)) 0xf5bd826f8d7dbb53eff02c2e803aeae28e18a0ce 转入方的币种地址
转账数量 quantity BigDecimal(32,18) 12.021214 转入的数量
是否Token isToken Boolean true 是否是token
Token依赖币种符号 psymbol String(10) ETH Bying Token币种的简称,请参照 支持数字币类型
自定义合约内容 contractData String(无限制) 0xf6e93d486……3323435363768676 16进制的自定义合约字符串
随机字符 nonce String(32) 5K8264ILTKCH16I8ZNMTM67VS 随机字符串,长度要求在32位以内。
Bying钱包回调 callBack String(256) 1、回调URL https://xxxx/sss.htmls?returnCode=SUCCESS& returnErrorCode=&retrunTxHash=s324……123
2、h5返回结果byingSendTxResult(string json字符串)
仅用户移动端回调 用于结果直接回调,不需要则不用传。
1、交易完成后,移动端回调该页面。默认在URL后面增加参数;
2、H5页面直接回调js方法名;
签名字符串 sign String(32) C380BEC2BFD727A4B6845133519F3AD6 通过签名算法计算得出的签名值,详见签名生成算法

返回结果

Dapp H5调起Bying钱包发送交易:

字段名 变量名 必填 类型 示例值 描述
返回状态码 returnCode String(16) SUCCESS SUCCESS/FAIL
此字段是通信标识,非交易标识,交易是否成功需要查看resultCode来判断
返回交易Hash retrunTxHash String(64) Asfd3123……asdf returnCode为SUCCESS时返回交易hash,FAIL时返回空
商户订单编号 outTradeNum String(32) 20180518125346 商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-且在同一个商户号下唯一。(匿名账户不用填写)
返回错误码 returnErrorCode String(128) SIGNERROR 返回信息,如非空,为错误原因
签名失败
参数格式校验错误
返回交易发送错误详情 returnTxErrorDetail String(128) 发送区块返回错误信息

returnErrorCode定义

名称 描述 原因 解决方案
SYSTEMERROR 系统错误 系统超时 系统异常,请用相同参数重新调用
DOMAINERROR 域名错误 域名错误 当前访问域名与提交的域名不同
DAPPID_NOT_EXIST DAPPID不存在 参数中DAPPID和存储不匹配 请检查DAPPID是否正确
LACK_PARAMS 缺少参数 缺少必要的请求参数 请检查参数是否齐全
OUT_TRADE_NO_USED 商户订单号重复 同一笔交易不能多次提交 请核实商户订单号是否重复提交
SIGNERROR 签名错误 参数签名结果不正确 请检查签名参数和方法是否都符合签名算法要求
NOT_UTF8 编码格式错误 未使用指定编码格式 请使用UTF-8编码格式
OTHER_ERROR 未知错误 未知错误 未知错误
CHECK_PARAMS_ERROR 校验参数错误 校验参数错误 校验参数错误(非法参数)

二维码扫描生成规则

bying://dapp/thirdPartysendTx?parmas= encode(params) 参数参照 调起Bying Sdk(scheme)交易接口

查询发送结果请求接口

接口链接

测试: http://api.bying.io:8089/api/thirdparty/tx/orderquery

请求参数

字段名 变量名 必填 类型 示例值 描述
DAPPID dappid String(32) 1230000109 Bying分配的账户号(匿名账户不用填写)
请求类型 callType String(10) dapp 请求交易类型
商户名称 mername String(20) 天天DA 商户名称(不用签名,仅用于钱包展示)
商户订单编号 outTradeNum String(32) 20180518125346 商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-且在同一个商户号下唯一。(匿名账户不用填写)
币种符号 symbol String(10) EOS 币种的简称,请参照 支持数字币类型
是否Token isToken Boolean true 是否是token 选择交易hash参数时必传
Token依赖币种符号 psymbol String(10) ETH Bying Token 币种的简称,请参照 支持数字币类型 选择交易hash参数时必传,且未Token时
随机字符 nonce String(32) 5K8264ILTKCH16I8ZNMTM67VS 随机字符串,长度要求在32位以内。
签名字符串 sign String(32) C380BEC2BFD727A4B6845133519F3AD6 通过签名算法计算得出的签名值,详见签名生成算法

返回结果

字段名 变量名 必填 类型 示例值 描述
返回状态码 returnCode String(16) SUCCESS SUCCESS/FAIL
此字段是通信标识,非交易标识,交易是否成功需要查看resultCode来判断
返回错误码 returnMsg String(128) SIGNERROR 返回结果
C returnResultType String(16) REPLAY 推送时才有可能会返回REPLAY(当交易回滚时会触发)

returnCode为SUCCESS时有返回
返回结果

字段名 变量名 必填 类型 示例值 描述
Bying流水号 byingNum int 123 Bying流水号
交易hash txhash String(64) Xxx12423xxxx 交易发送至区块产生的交易hash
商户订单编号 outTradeNum String(32) 20180518125346 商户系统内部订单号,要求32个字符内,只能是数字、大小写字母_-且在同一个商户号下唯一。(匿名账户不用填写)
确认区块高度 confirmHeight int 1000000 交易被确认时的区块高度
确认区块hash confirmBlockHash String(64) Xaasdfasdf13dsaf 交易被确认时的区块hash
父币种符号 psymbol String(10) ETH 币种的简称,请参照 支持数字币类型
是否Token isToken Boolean true 是否Token
Token依赖币种符号 psymbol String(10) ETH 币种的简称,请参照 支持数字币类型
当前区块高度 currHeight int 10000232 当前区块高度
交易是否确认 txIsConfirmation Boolean True 交易是否被确认
交易记录list集合 records json 参照交易记录集合

交易记录list集合

字段名 变量名 必填 类型 示例值 描述
交易地址 txaddress String(50) xxxxxxxxx 交易地址
交易类型 txtype Int 1.2 1:转出 2:转入
交易数量 txquantity BigDecimal(32,18) 12.021214 转入的数量(公链转账,以及标准ERC20转账),自定义合约转账的为0
是否内存 mempooltx Boolean True 是否为内容交易
币种符号 symbol String(10) EOS 币种的简称,请参照 支持数字币类型
是否Token isToken String(10) true 是否是token
交易确认时间 txtime Int 1526710171 区块确认交易时间
交易小费 txfee BigDecimal(32,18) 0.000698067005184000 该笔交易产生的小费
交易是否合法 txisvaild Boolean true 交易是否合法

异步回调推送JSON定义

回调方法类型:POST
收到推送返回“SUCCESS”字符串,不返回则会进入重复推送计划。(异步立即回调,失败后5分钟、1小时、24小时各回调一次,一直失败则不推送),广播至网络上回调一次(未确认交易)
推送JSON参照6.3查询返回结果

Demo 示例

参考示例:http://api.bying.io:8085/mobile/dapp/thirdparty/demo/sendtxDemo.html