比特币BTC支付API接口中文文档

随着经济全球化和数字经济的迅猛发展，数字资产早已变成了投资客积累财富的重要标志。对于长线存储虚拟货币的交易所、项目方、个人来说，钱包系统成为存储、管理数字资产、发展业务不可或缺的工具。

接踵而来的是，行业竞争愈演愈烈，全球区块链钱包如雨后春笋般涌现，产品数量达近千种。

一个匿名的诞生神话，一个爆炸性的愿景，不可否认的吸引力，一个由数学治理的全新经济模型——比特币作为虚拟货币的开山鼻祖，也是当前占据市值和流量之王，更是交易中的核心币种，钱包的价值存在，在数字货币市场中占据着主导作用。

比特币在交易所市场中的活跃，带动了交易所、项目方对于比特币支付API接口的需求。

如何理解API?

常见解释：API，英文可翻译为应用程序编程接口。指一些预先定义的函数，为应用程序与开发人员提供基于某软件或硬件得以访问一组例程的能力，但又不需要访问源代码，或者去了解内部工作机制的细节。

如果上述解释比较晦涩难懂，不妨用一个小故事来理解：

开发团队A开发了软件A，开发团队 B正在研发软件B。某一天，开发团队B打算调用软件A的部分功能来用，但是他们又不想从头看一遍软件A的源码和功能实现过程，怎么办呢？

开发团队A想到了个好办法：我们把软件A里你需要的功能打包好，写成一个函数。你按照我说的流程，把这个函数放在软件B里，就能直接用我的功能了！

在这里，API指的就是开发团队A说的那个函数。

什么是支付接口？

意指一个集成的开发接口程序，接口能够包含各种通道，对接后，可实现多种支付通道功能。

比如全球首款区块链交易所钱包对接开放平台，优盾钱包，提供比特币_以太坊_USDT_EOS_XRP等主流erc20代币对接交易所钱包充提币、转账支付归集API/RPC的php/java接口开发解决方案。

比特币BTC支付API接口中文文档

详细的比特币支付API接口文档如下：

原文链接：https://www.uduncloud.com/gateway-interface

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 参数说明

参数类型是否必填说明备注
timestampString是时间戳见 验签说明
nonceString是随机数见 验签说明
signString是签名见 验签说明
bodyString是消息内容json字符串，格式如下

[

    {

     “merchantId”:”300015″,

     “coinType”:520,

     “callUrl”:”http://localhost:8080/callBack”

    }

]

1.2.2.2 body参数字段

body参数名类型是否必填说明
merchantIdString是商户号
coinTypeInteger是主币种编号，见 附录一
callUrlString是回调地址，通过该接口创建的地址，以后关于该地址的充币信息会通过您指定的回调地址通知您。具体示例见 交易回调接口
walletIdString否钱包编号,默认根据主钱包生成地址
aliasString否地址别名

1.2.2.3 示例

{

    “timestamp”: 1535005047,

    “nonce”: 10000,

    “sign”: “a230def43c1a12b14393880a28d4e005”,

    “body”: “[{\”merchantId\”:\”300015\”,\”coinType\”:520,\”callUrl\”:\”http://localhost:8080/callBack\”}]” 

}

1.2.3 返回状态码表

code解释
200成功
4005非法参数
4001商户不存在
4169商户已禁用
4162签名错误
4175钱包编号错误
4017商户没有创建钱包
4176钱包未添加支持该币种
4166商户没有配置套餐
4168商户地址达到上限
4045币种信息错误
-1获取地址失败

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 参数说明

参数类型是否必填说明备注
timestampString是时间戳见 验签说明
nonceString是随机数见 验签说明
signString是签名见 验签说明
bodyString是消息内容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业务id，必须保证该字段在系统内唯一，如果重复，则该笔审核钱包不会接收。
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成功
4005非法参数
4598传入body中的list对象中的所有merchantId必须保持一致
4001商户不存在
4169商户已被禁用
4183到账地址异常
4193EOS金额小数点后超过4位长度
4034未找到该币种信息

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 参数说明

参数类型是否必填说明备注
timestampString是时间戳见 验签说明
nonceString是随机数见 验签说明
signString是签名见 验签说明
bodyString是消息内容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参数名称类型是否必填说明
merchantIdString是商户号
addressString是提币地址
mainCoinTypeString是主币种编号，见 附录一
coinTypeString是子币种编号，见 附录一
amountString是交易数量
callUrlString是回调地址,提币（审核、交易）结果将通过该地址进行回调，具体示例见 交易回调接口
businessIdString是业务id，必须保证该字段在系统内唯一，如果重复，则该笔提币钱包将不会进行接收
memoString否备注,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商户不支持该币种

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 参数说明

参数类型是否必填说明备注
timestampString是时间戳见 验签说明
nonceString是随机数见 验签说明
signString是签名见 验签说明
bodyString是消息内容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参数名称类型说明
addressString地址
amountString交易数量，根据币种精度获取实际金额，实际金额=amount/pow(10,decimals)，即实际金额等于amount除以10的decimals次方
feeString矿工费，根据币种精度获取实际金额，实际金额获取同上
decimalsString币种精度
coinTypeString子币种编号,见 附录一
mainCoinTypeString主币种编号,见 附录一
businessIdString业务编号，提币回调时为提币请求时传入的，充币回调无值
blockHighString区块高度
statusInteger状态，见 回调接口状态说明
tradeIdString交易流水号
tradeTypeInteger交易类型,见 回调接口交易类型说明
txidString区块链交易哈希
memoString备注，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 参数说明

参数类型是否必填说明备注
timestampString是时间戳 
nonceString是随机数 
signString是签名 
bodyString是消息内容JSON字符串，格式如下

{

    “merchantId”:200000,

    “mainCoinType”:”206″,

    “address”:”DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW”

}

5.2.2.2 body参数说明

body参数名称类型是否必填说明
merchantIdLong是商户号
mainCoinTypeString是主币种编号，见 附录一
addressString是需校验的地址

5.2.2.2 示例

{

    “timestamp”: 1535005047,

    “nonce”: 100000,

    “sign”: “e1bee3a417b9c606ba6cedda26db761a”,

    “body”: “[{\”merchantId\”:200000,\”mainCoinType\”:\”206\”,\”address\”:\”DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW\”}]”

5.2.3 返回状态码表

code解释
200成功
4005非法参数
4162签名错误
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 参数说明

参数类型是否必填说明
timestampString是时间戳
nonceString是随机数
signString是签名
bodyString是消息内容

6.2.2.2 body参数说明

body参数名称类型是否必填说明
merchantIdLong是商户号
showBalanceBoolean是是否查询余额，false不获取，true获取

6.2.2.3 示例

{

    “timestamp”: 1535005047,

    “nonce”: 100000,

    “sign”: “e1bee3a417b9c606ba6cedda26db761a”,

    “body”: “{\”merchantId\”:\”200032\”,\”showBalance\”:true}”

}

6.2.3 返回状态码表

状态码解释
200成功
4005body参数错误

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”

}

附录一

主币种编号子币种编号币种简称币种英文名币种中文名称精度
00BTCBitcoin比特币8
6060ETHEthereum以太坊18
031USDTTether USD泰达币8
520520CNTCNT测试币18
55DASHDASH达世币8
133133ZECZEC大零币8
145145BCHBitcoincash比特币现金8
6161ETCEthereum Classic以太坊经典18
22LTCLTC莱特币8
23012301QTUMQTUM量子链币8
502502GCCGalaxyChain 8
60合约地址eth代币eth代币 根据代币具体情况而定
144144XRPRipple瑞波币6
194194EOSEOS柚子币4
194194EOSEOS柚子币4
23042304IOTEIOTEIOTE8
23032303VDSVollarVollar币8

回调接口状态说明

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

回调接口交易类型说明

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

验签说明

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

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

key为接口授权码APIKEY，由网关分配给商户，加密字段顺序不能错误

币种地址校验规则

主币种类型币种简称币种英文名称币种中文名称地址前缀地址长度限制区间
0BTCBitcoin比特币1或者3[26,36]
60ETHEthereum以太坊0x[42]
145BCHBitcoincash比特币现金1[26,36]
61ETCEthereumClassic以太坊经典0x[42]
2LTCLitecoin莱特币L或者M[26,36]
508GXGX G[26,36]
503NBTCNBTC N不限制
99STOSTO证券型通证发行S不限制
5DASHDASH达世币X[26,36]
2301QTUMQTUM量子链币Q[26,36]
133ZECZCash大零币t1不限制
144XRPRipple瑞波币r[34]

第三方比特币支付接口的出现，告别了繁琐冗杂的支付通道接入流程，为多种通道提供了支付接口集成，将数字资产管理与业务相结合, 帮助企业快速实现数字资产接入。

作者： 执着小钟

执着小钟

发表评论