-
Notifications
You must be signed in to change notification settings - Fork 1
JustPay JSON RPC 支付网关API
2014-10-27: 10/27/2014, 第一版BTCC比特币支付网关API发布.
2014-11-17: 添加了“btcReceived”返回参数; 更新“status”参数的描述.
目前BTCC比特币支付网关客户端示例代码如下：
PHP: https://github.com/BTCChina/btcchina-payment-api-php
Python:https://github.com/BTCChina/btcchina-payment-api-python
Java:https://github.com/BTCChina/btcchina-payment-api-java
Ruby: https://github.com/BTCChina/btcchina-payment-api-ruby
商家可以使用BTCC支付网关API接受比特币支付，而用户支付的比特币将由我们平台转为法定货币支付给商家。 商家的电商平台将用户的订单详情通过API交付给BTCC平台，用户在BTCC完成支付，而商家将在用户支付完成以后收到BTCC支付的法定货币。商家可以通过其在BTCC的账户查看所有订单详情。 商家如果要使用我们的支付API，需要联系BTCC平台来帮其创建具有使用支付功能权限的API密钥。需要的API密钥对如下：
- 访问密钥：用来确认商家身份信息。
- 秘密密钥：用来生成签名以保护商家发送的请求，以及用来确认返回信息的来源是真实可靠的来自于BTCC的。秘密密钥必须保密。 商家发送的请求过程与BTCC交易API的请求过程相同，欲获取更多细节信息，请参见交易API文档：
- http://btcchina.org/api-trade-documentation-en
所有的API请求方法都通过发送HTTP POST信息到以下链接完成：
商家使用createPurchaseOrder API方法在我们系统创建客户的购物订单，此函数返回一个https开头的URL地址，购物的客户通过这个URL地址来完成整个比特币支付过程。 请求方法: createPurchaseOrder
请求参数
| 名称 | 类型 | 必选？ | 描述 |
|---|---|---|---|
| price | number | 是 | 客户购买的商品价格. |
| currency | string | 是 | 客户购买商品时使用的货币种类，可以是[CNY],[USD],[SGD],[MYR],[BTC]. |
| notificationURL | string | 是 | 将订单状态返回给商家服务器的链接. 最大长度为255字符，必须以https开头. |
| returnURL | string | 否 | 用户完成支付以后返回的页面链接. 最大长度为255字符. 注意：用户完成支付以后，生成的支付订单ID会以以下参数形式附在重定向链接后：?purchaseorder_id=<PURCHASEORDER_ID>. |
| externalKey | string | 否 | 商家用来识别此购物订单的外部密钥. 可以是字母，数字以及下划线的组合，最大长度为255字符. 必须是唯一的. |
| itemDesc | string | 否 | 向客户展示的其将要购买的商品描述信息.最大长度为64k字节. |
| phoneNumber | string | 否 | 用户的手机号码. 客户在购买过程中需要使用手机来接收确认短信. |
| settlementType | number | 否 | 商家收款方式，支持两种模式. 默认值为0，款项将以比特币的形式直接转到商家的毕加索钱包里; 值为1时，款项会以法币形式依照合同规定，扣除手续费后，定时转给商家. 当以法币形式支付时，最小的比特币支付限额为0.0001个. |
请求响应
| 名称 | 类型 | 描述 |
|---|---|---|
| id | number | 唯一的订单号. |
| url | string | 用户将使用此返回链接完成比特币支付过程，链接是https开头的. 注意：商家可以在这个url尾部自行添加”&format=mbtc”或者”&format=bits”来以mBTC或者bits单位显示商品价格. |
| externalKey | string | 创建订单时商家传入的外部密钥参数. |
| price | number | 创建订单时商家传入的订单价格. |
| currency | string | 创建订单时商家传入的订单货币单位. |
| btcPrice | number | 与订单中商品价格等价的比特币数量. 如果订单中商品的货币单位不是比特币，那么这将是客户在购买商品时的等价比特币数量，兑换价格为当时BTCC的比特币市价. |
| creationTime | number | 电子发票生成时间，精确到毫秒. |
| expirationTime | number | 订单失效时间，精确到毫秒. 订单在创建后15分钟内有效，超过15分钟客户未支付则订单失效. |
| status | string | 订单状态. 提交时订单状态为“new”；当用户付完全款但比特币网络未达到两个确认时，订单状态为“unconfirmed”；当比特币网络两次确认完成，表示用户支付成功以后，订单状态为“paid”；如果用户在订单有效时间内未支付，则订单状态为“expired”；当订单出现任何错误时，订单状态为“error”. |
| itemDesc | string | 创建订单时商家传入的商品描述信息. |
| settlementType | number | 创建订单时商家传入的收款方式. |
| btcReceived | number | 用户已支付的比特币数量. |
商家使用getPurchaseOrder API方法来获取某一特定订单的详情。
请求参数
| 名称 | 类型 | 必选？ | 描述 |
|---|---|---|---|
| id | number | 是 | createPurchaseOrder方法返回的订单号. |
请求响应
与createPurchaseOrder方法的请求响应相同。
商家使用getPurchaseOrders API方法来获取符合查询条件的若干订单详情。
请求参数
| 名称 | 类型 | 必选？ | 描述 |
|---|---|---|---|
| limit | number | 否 | 获取订单数量的指定最大值. 默认值为1000，设置为null时将取回所有订单详情. |
| offset | number | 否 | 获取订单的起始偏移量. 默认值为0，当被设置时，limit参数不能为null. |
| fromDate | number | 否 | 获取创建时间不早于此时间的订单详情. 精确到毫秒，默认值为null. |
| toDate | number | 否 | 获取创建时间不晚于此时间的订单详情. 精确到毫秒，默认值为null. |
| status | string | 否 | 获取指定状态的订单详情. 默认值为null. |
| externalKey | string | 否 | 获取指定外部密钥的订单详情. 如果存在，将返回唯一的订单详情，默认值为null. |
请求响应
| 名称 | 类型 | 描述 |
|---|---|---|
| purchaseorder | array | 包含一组订单详情，每个订单详情格式与getPurchaseOrder返回值相同，默认以订单号升序排序. |
每当订单状态改变时，相同的JSON格式的响应会被发送到notificationURL链接。 商家的服务器必须返回HTTP响应编码200以表示通知发送成功，否则此通知将会在距上次通知发送以下时间段后被重新发送直到商家服务器返回HTTP响应200：5分钟后，10分钟后，1小时后和24小时后。 24小时以后，状态改变将不会再发送给商家服务器，但是商家可以通过API方法主动获取相关订单状态信息。 注意：订单转为“已过期”状态时不会通知商家服务器。 在发送状态改变通知时，HTTP头部会包含加密的签名。商家须检查HTTP头来确保收到的通知是可靠真实的。 头部的签名将被设置在“X_BTCChina_Signature”中。检查签名真伪的方法是：在POST体后添加商家的秘密密钥，然后使用sha1方法计算出整个字符串加密后的签名结果。例如： 你的秘密密钥是:
- 42e90cbe-08eb-4cbe-b8c7-8a4d9b26581a POST体为:
{
"id":"65","url":"https:\/\/api.btcchina.com\/purchaseorder\/pay?token=5bf85fee9885f65ca023020e8ca229b84fe3428a","externalKey":"","price":"0.00060000","currency":"BTC","btcPrice":"0.00060000","creationTime":1400068177,"expirationTime":1400069077,"status":"unconfirmed"
}
使用如下方法计算签名:
sha1( '{"id":"65","url":"https:\/\/api.btcchina.com\/purchaseorder\/pay?token=5bf85fee9885f65ca023020e8ca229b84fe3428a","externalKey":"","price":"0.00060000","currency":"BTC","btcPrice":"0.00060000","creationTime":1400068177,"expirationTime":1400069077,"status":"unconfirmed"}42e90cbe-08eb-4cbe-b8c7-8a4d9b26581a');
上述例子计算出来的签名结果如下:
1ecc0511ed0abd209f77e803124ae4a7d21bb789
BTCC支付网关支持实时推送订单状态改变的socket.io(websocket)机制。商户可以通过订阅我们的服务端来实现即时接收订单状态改变的通知。 通过以下方法订阅订单状态改变通知:
socket.emit(“subscribePurchaseorder”, <SIGNATURE & POSTDATA>);
在这里，SIGNATURE是商户请求体内的参数经过SHA1加密后的结果，附在请求的header里发送到服务器端；POSTDATA是请求体中的参数。 比如, 假如商户的支付秘钥如下：
- 访问秘钥: 24d958c8-6f1a-483a-afb1-e9400fbb16de
- 秘密秘钥: 36a958c8-6f1a-483a-afb1-e9400fbbb90d 那么postdata会类似以下格式：
{"tonce":"1414397556137000","accesskey":"24d958c8-6f1a-483a-afb1-e9400fbb16de","requestmethod": "post","id":"1414397556137000","method": "subscribePurchaseorder", "params": []};
那么对应的需要使用秘密秘钥SHA1加密的参数如下：
tonce=1414397556137000&accesskey=24d958c8-6f1a-483a-afb1-e9400fbb16de&requestmethod=post&id=1414397556137000&method=subscribePurchaseorder¶ms=;
商户可以参照BTCC的官方示例代码来了解如何具体使用socket.io来实现即时订阅订单状态改变信息。
到目前为止，我们只支持在线上产品网络里测试。 测试时，请将settlementType设置为0，即使用比特币结算到商家毕加索钱包。 2014-10-27: 10/27/2014, 第一版BTCC比特币支付网关API发布.
##BTCC比特币支付网关 v0.1.1 2014-11-17: 添加了“btcReceived”返回参数; 更新“status”参数的描述.
##支付网关客户端示例代码
目前BTCC比特币支付网关客户端示例代码如下：
PHP: https://github.com/BTCChina/btcchina-payment-api-php
Python:https://github.com/BTCChina/btcchina-payment-api-python
Java:https://github.com/BTCChina/btcchina-payment-api-java
Ruby: https://github.com/BTCChina/btcchina-payment-api-ruby
###介绍 商家可以使用BTCC支付网关API接受比特币支付，而用户支付的比特币将由我们平台转为法定货币支付给商家。 商家的电商平台将用户的订单详情通过API交付给BTCC平台，用户在BTCC完成支付，而商家将在用户支付完成以后收到BTCC支付的法定货币。商家可以通过其在BTCC的账户查看所有订单详情。 商家如果要使用我们的支付API，需要联系BTCC平台来帮其创建具有使用支付功能权限的API密钥。需要的API密钥对如下：
- 访问密钥：用来确认商家身份信息。
- 秘密密钥：用来生成签名以保护商家发送的请求，以及用来确认返回信息的来源是真实可靠的来自于BTCC的。秘密密钥必须保密。 商家发送的请求过程与BTCC交易API的请求过程相同，欲获取更多细节信息，请参见交易API文档：
- http://btcchina.org/api-trade-documentation-en
###API 详情 所有的API请求方法都通过发送HTTP POST信息到以下链接完成：
###创建购物订单：createPurchaseOrder 商家使用createPurchaseOrder API方法在我们系统创建客户的购物订单，此函数返回一个https开头的URL地址，购物的客户通过这个URL地址来完成整个比特币支付过程。 请求方法: createPurchaseOrder
请求参数
| 名称 | 类型 | 必选？ | 描述 |
|---|---|---|---|
| price | number | 是 | 客户购买的商品价格. |
| currency | string | 是 | 客户购买商品时使用的货币种类，可以是[CNY],[USD],[SGD],[MYR],[BTC]. |
| notificationURL | string | 是 | 将订单状态返回给商家服务器的链接. 最大长度为255字符，必须以https开头. |
| returnURL | string | 否 | 用户完成支付以后返回的页面链接. 最大长度为255字符. 注意：用户完成支付以后，生成的支付订单ID会以以下参数形式附在重定向链接后：?purchaseorder_id=<PURCHASEORDER_ID>. |
| externalKey | string | 否 | 商家用来识别此购物订单的外部密钥. 可以是字母，数字以及下划线的组合，最大长度为255字符. 必须是唯一的. |
| itemDesc | string | 否 | 向客户展示的其将要购买的商品描述信息.最大长度为64k字节. |
| phoneNumber | string | 否 | 用户的手机号码. 客户在购买过程中需要使用手机来接收确认短信. |
| settlementType | number | 否 | 商家收款方式，支持两种模式. 默认值为0，款项将以比特币的形式直接转到商家的毕加索钱包里; 值为1时，款项会以法币形式依照合同规定，扣除手续费后，定时转给商家. 当以法币形式支付时，最小的比特币支付限额为0.0001个. |
请求响应
| 名称 | 类型 | 描述 |
|---|---|---|
| id | number | 唯一的订单号. |
| url | string | 用户将使用此返回链接完成比特币支付过程，链接是https开头的. 注意：商家可以在这个url尾部自行添加”&format=mbtc”或者”&format=bits”来以mBTC或者bits单位显示商品价格. |
| externalKey | string | 创建订单时商家传入的外部密钥参数. |
| price | number | 创建订单时商家传入的订单价格. |
| currency | string | 创建订单时商家传入的订单货币单位. |
| btcPrice | number | 与订单中商品价格等价的比特币数量. 如果订单中商品的货币单位不是比特币，那么这将是客户在购买商品时的等价比特币数量，兑换价格为当时BTCC的比特币市价. |
| creationTime | number | 电子发票生成时间，精确到毫秒. |
| expirationTime | number | 订单失效时间，精确到毫秒. 订单在创建后15分钟内有效，超过15分钟客户未支付则订单失效. |
| status | string | 订单状态. 提交时订单状态为“new”；当用户付完全款但比特币网络未达到两个确认时，订单状态为“unconfirmed”；当比特币网络两次确认完成，表示用户支付成功以后，订单状态为“paid”；如果用户在订单有效时间内未支付，则订单状态为“expired”；当订单出现任何错误时，订单状态为“error”. |
| itemDesc | string | 创建订单时商家传入的商品描述信息. |
| settlementType | number | 创建订单时商家传入的收款方式. |
| btcReceived | number | 用户已支付的比特币数量. |
###获取某一订单信息：getPurchaseOrder 商家使用getPurchaseOrder API方法来获取某一特定订单的详情。
####请求方法: getPurchaseOrder
请求参数
| 名称 | 类型 | 必选？ | 描述 |
|---|---|---|---|
| id | number | 是 | createPurchaseOrder方法返回的订单号. |
请求响应
与createPurchaseOrder方法的请求响应相同。
###获取若干符合条件的订单信息：getPurchaseOrders 商家使用getPurchaseOrders API方法来获取符合查询条件的若干订单详情。
####请求方法: getPurchaseOrders
请求参数
| 名称 | 类型 | 必选？ | 描述 |
|---|---|---|---|
| limit | number | 否 | 获取订单数量的指定最大值. 默认值为1000，设置为null时将取回所有订单详情. |
| offset | number | 否 | 获取订单的起始偏移量. 默认值为0，当被设置时，limit参数不能为null. |
| fromDate | number | 否 | 获取创建时间不早于此时间的订单详情. 精确到毫秒，默认值为null. |
| toDate | number | 否 | 获取创建时间不晚于此时间的订单详情. 精确到毫秒，默认值为null. |
| status | string | 否 | 获取指定状态的订单详情. 默认值为null. |
| externalKey | string | 否 | 获取指定外部密钥的订单详情. 如果存在，将返回唯一的订单详情，默认值为null. |
请求响应
| 名称 | 类型 | 描述 |
|---|---|---|
| purchaseorder | array | 包含一组订单详情，每个订单详情格式与getPurchaseOrder返回值相同，默认以订单号升序排序. |
###订单状态改变通知以及Socket.io(Websocket)实现
###订单状态改变通知
每当订单状态改变时，相同的JSON格式的响应会被发送到notificationURL链接。 商家的服务器必须返回HTTP响应编码200以表示通知发送成功，否则此通知将会在距上次通知发送以下时间段后被重新发送直到商家服务器返回HTTP响应200：5分钟后，10分钟后，1小时后和24小时后。 24小时以后，状态改变将不会再发送给商家服务器，但是商家可以通过API方法主动获取相关订单状态信息。 注意：订单转为“已过期”状态时不会通知商家服务器。 在发送状态改变通知时，HTTP头部会包含加密的签名。商家须检查HTTP头来确保收到的通知是可靠真实的。 头部的签名将被设置在“X_BTCChina_Signature”中。检查签名真伪的方法是：在POST体后添加商家的秘密密钥，然后使用sha1方法计算出整个字符串加密后的签名结果。例如： 你的秘密密钥是:
- 42e90cbe-08eb-4cbe-b8c7-8a4d9b26581a POST体为:
{
"id":"65","url":"https:\/\/api.btcchina.com\/purchaseorder\/pay?token=5bf85fee9885f65ca023020e8ca229b84fe3428a","externalKey":"","price":"0.00060000","currency":"BTC","btcPrice":"0.00060000","creationTime":1400068177,"expirationTime":1400069077,"status":"unconfirmed"
}
使用如下方法计算签名:
sha1( '{"id":"65","url":"https:\/\/api.btcchina.com\/purchaseorder\/pay?token=5bf85fee9885f65ca023020e8ca229b84fe3428a","externalKey":"","price":"0.00060000","currency":"BTC","btcPrice":"0.00060000","creationTime":1400068177,"expirationTime":1400069077,"status":"unconfirmed"}42e90cbe-08eb-4cbe-b8c7-8a4d9b26581a');
上述例子计算出来的签名结果如下:
1ecc0511ed0abd209f77e803124ae4a7d21bb789
###订单状态改变通知Socket.io (Websocket)实现
BTCC支付网关支持实时推送订单状态改变的socket.io(websocket)机制。商户可以通过订阅我们的服务端来实现即时接收订单状态改变的通知。 通过以下方法订阅订单状态改变通知:
socket.emit(“subscribePurchaseorder”, <SIGNATURE & POSTDATA>);
在这里，SIGNATURE是商户请求体内的参数经过SHA1加密后的结果，附在请求的header里发送到服务器端；POSTDATA是请求体中的参数。 比如, 假如商户的支付秘钥如下：
- 访问秘钥: 24d958c8-6f1a-483a-afb1-e9400fbb16de
- 秘密秘钥: 36a958c8-6f1a-483a-afb1-e9400fbbb90d 那么postdata会类似以下格式：
{"tonce":"1414397556137000","accesskey":"24d958c8-6f1a-483a-afb1-e9400fbb16de","requestmethod": "post","id":"1414397556137000","method": "subscribePurchaseorder", "params": []};
那么对应的需要使用秘密秘钥SHA1加密的参数如下：
tonce=1414397556137000&accesskey=24d958c8-6f1a-483a-afb1-e9400fbb16de&requestmethod=post&id=1414397556137000&method=subscribePurchaseorder¶ms=;
商户可以参照BTCC的官方示例代码来了解如何具体使用socket.io来实现即时订阅订单状态改变信息。
##测试 到目前为止，我们只支持在线上产品网络里测试。 测试时，请将settlementType设置为0，即使用比特币结算到商家毕加索钱包。