接入指引

对接前准备工作说明

公私钥申请路径

账户管理->APIKey管理->新建

正式上线阶段, 我方强烈建议贵方绑定服务器IP地址, 未绑定IP地址的 APIKey 仅能使用15天, 修改 APIKey 绑定服务器 IP 后重新生效。

系统公钥(System PublicKey)

03029c655932f22aee81034d109795fbd7e23ca173ca27e195091d434e593a2e0f

公私钥&系统公钥使用说明

请求域名

https://payment.tarspay.com

请求结构

通过向 Tarspay API 的服务端地址发送 HTTP POST 请求，并按照请求结构在 HTTP body 和 HTTP header 中加入相应请求参数来完成，Tarspay 系统根据请求参数来响应返回参数。

通信协议

为了更高的安全性，Tarspay API接口仅支持通过HTTPS通道进行请求通信。在调用 Tarspay 系统API时，需要遵循以下安全要求：

所有的请求必须使用SSL，否则请求将被拒绝仅支持 TLS 1.2 or TLS 1.1， SSLv3 and TLS 1.0 不被支持商户系统与 Tarspay 系统通信，使用签名验证来确保通信信息完整及通信安全，见(签名机制)。

字符编码

请求及返回结果都使用UTF-8字符集进行编码。

参数格式

请求参数及返回参数均使用JSON格式。

Content-Type: application/json;charset=utf-8

返回参数

{
   "code":0,
   "msg":"SUCCESS",
   "data":{
       ...
   }
}

字段	类型	说明
code	integer	0表示请求成功,非0表示失败
data	object	描述业务调用情况的返回值，具体请参照业务接口中每个接口的data值
msg	string	响应消息

通知机制

Tarspay 会将消费者支付结果的消息通过服务器端发送到商户提供的 notifyUrl 上，并携带相关参数，以POST形式提交。商户需要对结果信息进行签名验证，以防止伪造的通知信息；且必须对返回结果中的订单状态做判断，以确定订单状态。

商户服务器接到请求后必须 HTTP 响应200，并且打印输出OK字符串。如果商户反馈给 Tarspay 的字符不是OK字符，Tarspay 服务器会不断重发通知。

某些情况下，商户的一笔订单可能会收到 Tarspay 的多次通知，商户需对自己的逻辑进行检查，对于可能收到重复的成功或失败状态的订单通知能够进行唯一的业务处理。

签名机制

商户在调用 Tarspay API接口时，需将请求方法,请求路径,请求时间戳以及业务参数，按照 Tarspay 约定好的形式，获取到对应的签名字符串，并作为请求头参数X-API-SIGNATURE传递给 Tarspay。

⚠️特别说明:空值不参与签名，请不要将空值的键值对加入到 PARAMS 字符串中！！！

签名前准备的数据如下：
HTTP_METHOD + "|" + HTTP_REQUEST_PATH + "|" + TIMESTAMP + "|" + PARAMS连接完成后，对数据进行 ECDSA 签名，签名后的 bytes 进行 Hex 编码。

HTTP_METHOD：

POST

HTTP_REQUEST_PATH：

例如创建代收订单接口:
https://payment.tarspay.com/api/pay/unifiedOrder 的请求路径是 /api/pay/unifiedOrder

TIMESTAMP：

访问 API 时的 UNIX EPOCH 时间戳 (精确到毫秒)

PARAMS：

先将 key 按照字母排序，然后进行 url 参数化，即 password=password username=username 因为 p 在字母表中的排序在 u 之前，所以 password 要放在 username 之前，然后使用 & 进行连接，即： password=password&username=username 请求参数，POST, GET 都一样，需要把所有参数都拿出来，签名规则如下：所有请求的 key 按照字母顺序排序，然后以key=value（value值无需urlencode）形式拼接，并使用 & 连接。

注意：业务字段并非固定不变，所有业务字段均参与签名，建议动态处理，以应对可能的字段增减。

完整示例

对于如下的请求：

HTTP_METHOD	HTTP_REQUEST_PATH	TIMESTAMP
POST	/api/v1/test	1537498830736

PARAMS

Parameter	value
amount	100
price	100

签名前的准备数据如下：
1、设所有发送或者接收到的数据为集合M，将集合M内非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成字符串：

提示：content不需要URLEncode

2、将拼接的字符串content 与方法请求信息 MERTHOD 、URL和NONCE以"|"分隔拼接成新的字符串：

3、使用您生成的私钥（PrivateKey），对拼接成的数据使用私钥进行 ECDSA 签名，并对二进制结果进行 Hex 编码, 即生成了用于向 API 服务器进行验证的最终签名

将 Api key, nonce和右边生成的 signature 按上面的名称放入Header中, 即可通过签名验证

Tarspay 验签公钥可以在 "Web 管理界面 - 账户管理 - apikey" 页面获取

签名工具参考

java

Maven依赖

<dependency>
  <groupId>org.bouncycastle</groupId>
  <artifactId>bcprov-jdk15on</artifactId>
  <version>1.64</version>
  <scope>compile</scope>
</dependency>

对接前准备工作说明

公私钥申请路径

系统公钥(System PublicKey)

公私钥&系统公钥使用说明

请求域名

请求结构

通信协议

字符编码

参数格式

返回参数

通知机制

签名机制

HTTP_METHOD：

HTTP_REQUEST_PATH：

TIMESTAMP：

PARAMS：

完整示例

签名工具参考

java

Maven依赖

签名工具类

Utils

回调示例

php demo

接入指引

对接前准备工作说明#

公私钥申请路径#

系统公钥(System PublicKey)#

公私钥&系统公钥使用说明#

请求域名#

请求结构#

通信协议#

字符编码#

参数格式#

返回参数#

通知机制#

签名机制#

HTTP_METHOD：#

HTTP_REQUEST_PATH：#

TIMESTAMP：#

PARAMS：#

完整示例#

签名工具参考#

java#

Maven依赖#

签名工具类#

Utils#

回调示例#

php demo#

对接前准备工作说明

公私钥申请路径

系统公钥(System PublicKey)

公私钥&系统公钥使用说明

请求域名

请求结构

通信协议

字符编码

参数格式

返回参数

通知机制

签名机制

HTTP_METHOD：

HTTP_REQUEST_PATH：

TIMESTAMP：

PARAMS：

完整示例

签名工具参考

java

Maven依赖

签名工具类

Utils

回调示例

php demo