优盾钱包API开发接口文档

    1、目录

    1.1、生成地址

    1.2、提币

    1.3、代付

    1.4、交易回调

    1.5、校验地址合法性

    1.6、获取商户支持币种信息

    2、接口明细

    1、生成地址

    1.1 场景说明

    请求指定币种地址,如要成功获取地址,需先存在钱包,且钱包支持该币种, 详情参看

    1.2 接口详情

    1.2.1 接口地址
    接口详情
    URL 【/mch/address/create】
    请求方式 POST
    1.2.2 参数
    1.2.2.1 参数说明
    参数 类型 是否必填 说明 备注
    timestamp String 时间戳 验签说明
    nonce String 随机数 验签说明
    sign String 签名 验签说明
    body String 消息内容 json字符串,格式如下
    [
        {
         "merchantId":"300015",
         "mainCoinType":520,
         "callUrl":"http://localhost:8080/callBack"
        }
    ]
    1.2.2.2 body参数字段
    body参数名称 类型 是否必填 说明
    merchantId String 商户号
    mainCoinType Integer 主币种编号,使用获取商户币种信息接口
    callUrl String 回调地址,通过该接口创建的地址,以后关于该地址的充币信息会通过您指定的回调地址通知您。具体示例见 交易回调接口
    walletId String 钱包编号,默认根据主钱包生成地址
    alias String 地址别名
    1.2.2.3 示例
    {
        "timestamp": 1535005047,
        "nonce": 10000,
        "sign": "a230def43c1a12b14393880a28d4e005",
        "body": "[{\"merchantId\":\"300015\",\"mainCoinType\":520,\"callUrl\":\"http://localhost:8080/callBack\"}]"}
    1.2.3 返回状态码表
    code 解释
    -1 生成地址失败
    200 生成地址成功
    4001 商户不存在
    4005 非法参数
    4045 币种信息错误
    4162 签名异常
    4163 签名错误
    4166 商户没有配置套餐
    4168 商户地址达到上限
    4169 商户已禁用
    4175 钱包编号错误
    4017 商户没有创建钱包
    4176 钱包未添加支持该币种
    4188 暂不支持
    4226 商户普通账户被禁用
    4261 商户管理员账户被禁用
    4262 账户不存在

    1.3 调取示例

    1.3.1 成功
    {
        "data":{
            "coinType":520,
            "address":"0xbe4e3699cb870bc95365fe04a187dd279a651a58"
        },
        "message":"SUCCESS",
        "code":200
    }
    1.3.2 失败
    {
        "code": "4101",
        "message": "SIGN_MSG_ERROR"}

    2、发送提币申请

    2.1 场景说明

    提币申请

    2.2 接口详情

    2.2.1 接口地址
    接口详情
    URL 【/mch/withdraw】
    请求方式 POST
    2.2.2 参数
    2.2.2.1 参数说明
    参数 类型 是否必填 说明 备注
    timestamp String 时间戳 验签说明
    nonce String 随机数 验签说明
    sign String 签名 验签说明
    body String 消息内容 json字符串,格式如下
    [
        {
            "address":"raadSxrUhG5EQVCY75CSGaVLWCeXd6yH6s",
            "amount":"0.11",
            "merchantId":"100109",
            "mainCoinType":"144",
            "coinType":"144",
            "callUrl":"http://localhost:8080/mch/callBack",
            "businessId":"15",
            "memo":"10112"
        }
    ]
    2.2.2.2 body参数字段
    body参数名称 是否必填 类型 说明
    address String 提币地址
    amount String 提币数量
    merchantId String 商户号
    mainCoinType String 主币种编号,使用获取商户币种信息接口
    coinType String 子币种编号,使用获取商户币种信息接口
    callUrl String 回调地址,通过该callUrl告知您该笔提币交易的状态,具体示例见 交易回调接口
    businessId String 业务编号,必须保证该字段在系统内唯一,如果重复,则该笔提币钱包将不会进行接收
    memo String 备注,XRP和EOS,这两种币的提币申请该字段可选,其他类型币种不填
    2.2.2.3 示例
    {
      "timestamp": 1535005047,
      "nonce": 100000,
      "sign": "6df1512ee650431632ce1541a6b064e1",
      "body": "[{\"address\":\"raadSxrUhG5EQVCY75CSGaVLWCeXd6yH6s\",\"amount\":\"0.11\",\"merchantId\":\"100109\",\"mainCoinType\":\"144\",\"coinType\":\"144\",\"callUrl\":\"http://localhost:8080/callBack\",\"businessId\":\"15\",\"memo\":\"10112\"}]"}
    2.2.3 返回状态码表
    code 解释
    200 提币成功
    523 参数为空
    581 无效的提币金额
    4005 非法参数
    4014 币种为空
    4034 未找到该币种信息
    4162 签名异常
    4163 签名错误
    4169 商户已被禁用
    4183 到账地址异常
    4193 EOS金额小数点后超过4位长度
    4214 暂无可用的币种
    4226 商户普通账户被禁用
    4261 商户管理员账户被禁用
    4284 商户不存在
    4288 业务编号(BusinessId)重复,请勿重复申请
    4598 传入body中的list对象中的所有merchantId必须保持一致
    4001 商户不存在
    2.3.1 成功
    {
        "message":"SUCCESS",
        "code":200
    }
    2.3.2 失败
    {
        "code": "4101",
        "message": "SIGN_MSG_ERROR"
    }

    3、代付

    3.1 场景说明

    代付,发送自动付款申请,未设置代付信息或代付失败则进入审核状态。。

    3.2 接口详情

    3.2.1 接口地址
    接口详情
    URL 【/mch/withdraw/proxypay】
    请求方式 POST
    3.2.2 参数
    3.2.2.1 参数说明
    参数 类型 是否必填 说明 备注
    timestamp String 时间戳 验签说明
    nonce String 随机数 验签说明
    sign String 签名 验签说明
    body String 消息内容 json字符串,格式如下
    [
      {
          "address":"raadSxrUhG5EQVCY75CSGaVLWCeXd6yH6s",
          "amount":"0.1",
          "merchantId":"100146",
          "mainCoinType":"144",
          "coinType":"144",
          "callUrl":"http://localhost:8080/callBack",
          "businessId":"571001",
          "memo":"10112"
      }
    ]
    3.2.2.2 body参数说明
    body参数名称 类型 是否必填 说明
    merchantId String 商户号
    address String 提币地址
    mainCoinType String 主币种编号,使用获取商户币种信息接口
    coinType String 子币种编号,使用获取商户币种信息接口
    amount String 交易数量
    callUrl String 回调地址,提币(审核、交易)结果将通过该地址进行回调,具体示例见 交易回调接口
    businessId String 业务编号,必须保证该字段在系统内唯一,如果重复,则该笔提币钱包将不会进行接收
    memo String 备注,XRP和EOS,这两种币的提币申请该字段可选,其他类型币种不填
    3.2.2.2 示例
    {
        "timestamp": 1535005047,
        "nonce": 100000,
        "sign": "e1bee3a417b9c606ba6cedda26db761a",
        "body": "[{\"address\":\"raadSxrUhG5EQVCY75CSGaVLWCeXd6yH6s\",\"amount\":\"0.1\",\"merchantId\":\"100146\",\"mainCoinType\":\"144\",\"coinType\":\"144\",\"callUrl\":\"http://localhost:8080/callBack\",\"businessId\":\"571001\",\"memo\":\"10112\"}]"
    }
    3.2.3 返回状态码表
    code 解释
    200 成功
    4005 非法参数
    4001 商户不存在
    4166 商户没有配置套餐
    4169 商户已被禁用
    4612 签名异常
    4163 签名错误
    569 无效的地址
    571 已存在审核记录,将不再进行处理
    581 非法提币金额
    554 商户不支持该币种
    4183 到账地址异常
    4193 EOS金额小数点后超过4位长度
    4214 暂无可用的币种
    4261 商户管理员账户被禁用
    4226 商户普通账户被禁用
    4284 商户不存在

    3.3 调取示例

    3.3.1 成功
    {
        "message":"SUCCESS",
        "code":200
    }
    3.3.2 失败
    {
        "code": "4101",
        "message": "SIGN_MSG_ERROR"
    }

    4、交易回调接口

    4.1 场景说明

    网关收到交易处理结果,调用商户提供的回调接口,通知商户具体变化信息。该接口网关发送给您指定的回调地址的内容,处理您的业务信息。分充值回调和提币回调, 其中提币最多会进行两次回调( 审核回调 + 交易结果回调)

    4.2 接口详情

    4.2.1 接口地址
    接口详情
    URL
    请求方式 POST
    4.2.2 参数
    4.2.2.1 参数说明
    参数 类型 是否必填 说明 备注
    timestamp String 时间戳 验签说明
    nonce String 随机数 验签说明
    sign String 签名 验签说明
    body String 消息内容 json字符串,格式如下
    {
        "address":"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW",
        "amount":"12345678",
        "blockHigh":"102419",
        "coinType":"206",
        "decimals":"8",
        "fee":"452000",
        "mainCoinType":"206",
        "status":3,
        "tradeId":"20181024175416907",
        "tradeType":1,
        "txId":"31689c332536b56a2246347e206fbed2d04d461a3d668c4c1de32a75a8d436f0",
        "businessId":"",// 提币回调为提币接口传入的businessId,充币无值
        "memo":""
    }
    4.2.2.2 body参数说明
    body参数名称 类型 说明
    address String 地址
    amount String 交易数量,根据币种精度获取实际金额,实际金额=amount/pow(10,decimals),即实际金额等于amount除以10的decimals次方
    fee String 矿工费,根据币种精度获取实际金额,实际金额获取同上
    decimals String 币种精度
    coinType String 子币种编号,使用获取商户币种信息接口
    mainCoinType String 主币种编号,使用获取商户币种信息接口
    businessId String 业务编号,提币回调时为提币请求时传入的,充币回调无值
    blockHigh String 区块高度
    status Integer 状态,见 回调接口状态说明
    tradeId String 业务流水号
    tradeType Integer 交易类型,见 回调接口交易类型说明
    txid String 区块链交易哈希
    memo String 备注,XRP和EOS,使用获取商户币种信息接口,这2种类型币的充提币可能有值
    4.2.2.2 示例
    {
        "timestamp": 1535005047,
        "nonce": 100000,
        "sign": "e1bee3a417b9c606ba6cedda26db761a",
        "body": "{\"address\":\"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW\",\"amount\":\"12345678\",\"blockHigh\":\"102419\",\"coinType\":\"206\",\"decimals\":\"8\",\"fee\":\"452000\",\"mainCoinType\":\"206\",\"status\":3,\"tradeId\":\"20181024175416907\",\"tradeType\":1,\"txId\":\"31689c332536b56a2246347e206fbed2d04d461a3d668c4c1de32a75a8d436f0\"}"
    }

    5、校验地址合法性

    5.1 场景说明

    校验地址的合法性,添加地址、提币申请等场景时可先校验地址合法性,参看 校验规则

    5.2 接口详情

    5.2.1 接口地址
    接口详情
    URL 【/mch/check/address】
    请求方式 Post
    5.2.2 参数
    5.2.2.1 参数说明
    参数 类型 是否必填 说明 备注
    timestamp String 时间戳
    nonce String 随机数
    sign String 签名
    body String 消息内容 json字符串,格式如下
    {
        "merchantId":200000,
        "mainCoinType":"206",
        "address":"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW"
    }
    5.2.2.2 body参数说明
    body参数名称 类型 是否必填 说明
    merchantId Long 商户号
    mainCoinType String 主币种编号,使用获取商户币种信息接口
    address String 需校验的地址
    5.2.2.2 示例
    {
        "timestamp": 1535005047,
        "nonce": 100000,
        "sign": "e1bee3a417b9c606ba6cedda26db761a",
        "body": "[{\"merchantId\":200000,\"mainCoinType\":\"206\",\"address\":\"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW\"}]"
    5.2.3 返回状态码表
    code 解释
    200 成功
    4005 非法参数
    4162 签名异常
    4163 签名错误
    4165 地址不合法

    5.3 调取示例

    5.3.1 成功
    {
        "code":200,
        "message":"SUCCESS"
    }
    5.3.2 失败
    {
        "code":4005,
        "message":"PARAM_ERROR"
    }

    6、获取商户支持的币种信息

    6.1 场景说明

    获取商户支持的币种,以及余额

    6.2 接口详情

    6.2.1 接口地址
    接口详情
    URL 【/mch/support-coins】
    请求方式 POST
    6.2.2 参数
    6.2.2.1 参数说明
    参数 类型 是否必填 说明
    timestamp String 时间戳
    nonce String 随机数
    sign String 签名
    body String 消息内容
    6.2.2.2 body参数说明
    body参数名称 类型 是否必填 说明
    merchantId Long 商户号
    showBalance Boolean 是否查询余额,false不获取,true获取
    6.2.2.3 示例
    {
        "timestamp": 1535005047,
        "nonce": 100000,
        "sign": "e1bee3a417b9c606ba6cedda26db761a",
        "body": "{\"merchantId\":\"200032\",\"showBalance\":true}"
    }
    6.2.3 返回状态码表
    状态码 解释
    -1 查询失败
    200 查询成功
    4005 非法参数

    6.3 调取示例

    6.3.1 成功
    {
        "code": 200,
        "message": "SUCCESS",
        "data":[
            {
                "name": "BTC", // 币种别名
                "coinName":"Bitcoin", // 币种全称
                "symbol":"BTC", // 币种单位
                "mainCoinType":"0", //主币种类型
                "coinType":"0", // 币种类型
                "decimals":"8", // 币种精度
                "tokenStatus":"0", // 0: 主币 1:代币
                "mainSymbol":"BTC", //主币种单位
                "balance":"0", // 币种余额 
                "logo":"http://bipay-admin.oss-cn-hangzhou.aliyuncs.com/bipay-admin-release/coin-logo/BTC.png" // 币种log地址
            },
            {
                "name": "ETH", // 币种别名
                "coinName":"Ethereum", // 币种全称
                "symbol":"ETH", // 币种单位
                "mainCoinType":"60", //主币种类型
                "coinType":"60", // 币种类型
                "decimals":"18", // 币种精度
                "tokenStatus":"0", // 0: 主币 1:代币
                "mainSymbol":"ETH", //主币种单位
                "balance":"0", // 币种余额 
                "logo":"https://bipay-admin.oss-cn-hangzhou.aliyuncs.com/bipay-admin-release/coin-logo/ETH.png" // 币种log地址
            }
        ]
    }
    6.3.2 失败
    {
        "code":4005,
        "message":"BGS_ILLEGAL_PARAMETER"
    }

    回调接口状态说明

    状态 说明
    0 待审核
    1 审核成功
    2 审核驳回
    3 交易成功
    4 交易失败

    回调接口交易类型说明

    状态 说明
    1 充币回调
    2 提币回调

    验签说明

    为了保证商户传送到优盾的参数信息不被恶意篡改, 网关为商户接口提供Md5加密摘要认证。 商户可用基础加密参数: 时间戳、 随机数、 签名密钥、 请求明文参数按指定顺序排列进行Md5加密, 产生一个验签串sign, 商户请求网关接口时, 带上参数时间戳、 随机数、 请求明文参数、 sign作为参数。 网关拿到相应的参数以同样的方式进行签名验签。 同理, 网关请求商户也以同样的方式进行身份验证。

    sign=md5(body + key + nonce + timestamp)

    key为签名密钥,由网关分配给商户,加密字段顺序不能错误

    币种地址校验规则

    主币种类型 币种简称 币种英文名称 币种中文名称 地址前缀 地址长度限制区间
    0 BTC Bitcoin 比特币 1或者3 [26,36]
    60 ETH Ethereum 以太坊 0x [42]
    145 BCH Bitcoincash 比特币现金 1 [26,36]
    61 ETC EthereumClassic 以太坊经典 0x [42]
    2 LTC Litecoin 莱特币 L或者M [26,36]
    508 GX GX G [26,36]
    503 NBTC NBTC N 不限制
    99 STO STO 证券型通证发行 S 不限制
    5 DASH DASH 达世币 X [26,36]
    2301 QTUM QTUM 量子链币 Q [26,36]
    133 ZEC ZCash 大零币 t1 不限制
    144 XRP Ripple 瑞波币 r [34]
    2303 VDS Vollar Vollar V

    在线客服

    申请试用

    申请试用

    设置