基本

简介

介绍

API开放平台将我们的服务和信息以 RESTful HTTP 的方式开放给我们的商家。如果您希望添加特定功能,请单击上方的“联系人”菜单项联系我们,如果需求请求开发超过一定次数,我们将考虑加入features分支开发该需求。

API设置

唯一需要的设置是转到“API接入”页面并生成一个API密钥。您将获得一个用于验证API调用的私钥和公钥。确保您不与任何第三方共享您的私钥!

认证方式

每个API调用都有一个使用您的私钥生成的SHA-512 HMAC签名。我们的服务器会生成自己的HMAC签名,并将其与API调用者的签名进行比较。如果它们不匹配,则将放弃API调用。HMAC签名作为称为“sign”的字段发送。
  1. 对所有字段除sign外,进行字典排序
  2. 所有请求参数编码成json string,用您的私钥照上述方式签名
  3. 注意每个字段都应该是string型,如果字段里出现integer情况,也需要转成string型
  4. 如果请求字段里有对象,则也需要转成json string,并且转成json string 时输入 JSON_UNESCAPED_UNICODE,JSON_UNESCAPED_SLASHES 两个参数

API响应

API将返回包含1个或2个元素的数组:“status”和“msg”。结果将始终有一个“status”字段。如果其值为“0”(integer),则说明该API调用成功,否则将包含“msg”错误消息。如果有数据要返回给您,它将作为数组存储在“data”元素中。

使用API接受付款

使用API接受付款,我们采用可变价格收款:给您一个地址,接收到的所有款项都会存入您的钱包,如果您设置了IPN URL,则会将付款通知您的服务器(与此同时,您还需要设置IPN PWD,否则也不会通知您的服务器)。买方可以根据需要发送任意数量的款项。

示例代码

curl --request POST \
--url https://{host}/api/v1/submit_trans \
--header 'Content-Type: application/json' \
--data '{"sign": "42306036e6345609e5c4edd6bc830c4bfc9575d306a4d2950d3611e29ee798267953f010cba0f7471842c0f27e83e59018ea01c345f82be07c3e5f148c822dbc","pubkey": "0b6dbe660366b5a8b3ccbfeec373eeec1567b89a96fe0c5ef502091cc8249c42","item_name": "手机","state": "1001"}'

付款请求

创建交易

系统把创建交易的能力以API的形式开放给商家,使您能用更灵活的方式集成开发支付功能。此API用于创建商家自己的自定义结帐页面,因此买家不必离开商家的网站即可完成付款。
接口说明
请求路径 https://{host}/api/v1/submit_trans
请求方式 POST
Content-Type application/json
字符编码 UTF-8

请求参数说明

参数 类型 备注
sign string 签名
pubkey string 系统分配的公钥
item_name string (可选)此交易的商品名
state string (可选)此交易的code码,该code码将在回调时通知给商家,用于商家识别订单

响应参数说明

参数 类型 备注
status integer 系统状态码,=0为操作成功,>0为操作失败,msg有相关错误说明
msg string 当status>0时,错误说明信息(该字段在status=0时返回交易TXID)
data object 交易实体对象
expired_at datetime 交易过期时间,过期后订单结束,不再回调通知

请求示例

{
	"sign": "42306036e6345609e5c4edd6bc830c4bfc9575d306a4d2950d3611e29ee798267953f010cba0f7471842c0f27e83e59018ea01c345f82be07c3e5f148c822dbc",
	"pubkey": "0b6dbe660366b5a8b3ccbfeec373eeec1567b89a96fe0c5ef502091cc8249c42",
	"item_name": "手机",
	"state": "1001"
}

查询交易

查询交易能力开放是为了商家更好的控制自己的自定义结帐页面,前端可以采取轮询的方式请求此接口,以获得订单实时状态。也可以通过此接口获取到的过期时间设置定时器,定时关闭订单以达到控制交易的效果。
接口说明
请求路径 https://{host}/api/v1/query_trans
请求方式 GET
Content-Type N/A
字符编码 UTF-8

请求参数说明

参数 类型 备注
sign string 签名
pubkey string 系统分配的公钥
uniqid string(uuid) 交易的TXID

响应参数说明

参数 类型 备注
status integer 系统状态码,=0为操作成功,>0为操作失败,msg有相关错误说明
msg string 当status>0时,错误说明信息(该字段在status=0时返回交易TXID)
data object 交易实体对象
expired_at datetime 交易过期时间,过期后订单结束,不再回调通知

请求示例

https://{host}/api/v1/query_trans?sign=42306036e6345609e5c4edd6bc830c4bfc9575d306a4d2950d3611e29ee798267953f010cba0f7471842c0f27e83e59018ea01c345f82be07c3e5f148c822dbc&pubkey=0b6dbe660366b5a8b3ccbfeec373eeec1567b89a96fe0c5ef502091cc8249c42&uniqid=3a6765db-5d2c-4907-8e32-36dbb5e31170

回调地址(IPN)

介绍

当您收到付款时,IPN系统将通知您的服务器。这是将我们的付款集成到您的软件中以自动完成订单,统计,判断用户付款等等最简单的方法。它通过一个 HTTP POST 请求将通知数据以”application/json”形式发送到您的服务器配置的URL上。我们请求的频率为1分钟1次,直到达到10次上限或您的服务器返回json里包含status=”OK”(区分大小写)才停止请求。或者是在此订单结束时,也将终止该订单的请求。

通知包含字段

参数 类型 备注
pwd string 商家在后台设置的通知密码
accounts float 此交易的一次(本条通知包含一次转账)到账金额
total float 此交易的累计到账金额
hash string 此交易此次通知的TXID(用于验证您的软件系统是否重复处理收款凭据)
transaction_id uuid 此交易TXID(用于验证您的软件系统是否重复处理交易订单)
state string 此交易的商家自定义信息,原封不动的返回(用于商家自定义处理)

IPN设置

商家登录后,在”我的面板” -> “安全设置”中,设置好 “及时支付通知回调密码” 和“及时支付通知回调链接” 两项,为了系统安全,两项都是必须,否则系统不会推送通知。

验证IPN

  1. 认准我们的官方域名或IP。来源不明的域名与IP过滤掉。
  2. 验证数据字段“pwd”:商家在后台设置的密码是否匹配

技术参数

交易相关

商家注册后,系统会为商家分配20个钱包地址池以供商家的客户使用,商家在登录后点击“获取地址”按钮同样消耗地址池里的钱包地址。所以这意味着,在订单规定的交易时间内(15分钟),最多产生交易20笔。超出后“获取地址”和API接口都将获取不到地址从而服务不可用。15分钟后,前面交易结束地址将得到释放,服务恢复可用。如果您有更高的并发需求,请联系官方进行扩大地址池容量或者进行嵌入开发。推荐嵌入开发彻底突破限制,商家自己掌控并发性能与数据。目前仅支持地址类型为ERC20

  1. {host}地址
    • 测试环境:47.56.227.97
    • 正式环境:www.payinchain.com