接入指引

english document
中文文档

请求HOST

详见开户信息或咨询工作人员。

请求结构

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

通信协议

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

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

字符编码

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

参数格式

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

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

返回参数

字段	名称	说明
code	状态码	http状态码，此字段值只表明接口请求情况，不能说明业务参数无异常
msg	状态描述	接口调用结果描述
error	错误信息	异常信息
data	业务返回值	描述业务调用情况的返回值，具体请参照业务接口中每个接口的data值

通知机制

通知分为两种通知方式，因同步回调可能出现用户模拟操作，或在同步通知未进行跳转时，用户手动关闭浏览器等不可控情况，导致商户造成损失，我们强烈建议商户以异步通知结果来确认订单的支付结果。

同步回调

在用户支付成功，或者取消支付时，Starpago会将消费者的浏览器重定向到商户提供的returnurl上，并携带相关参数。
同步回调采用get方式跳转，相应的拼接参数，会对每个参数的值进行编码为UTF-8的URLencode处理，随后进行跳转。

异步回调

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

商户服务器接到请求后必须http响应200，并且打印输出success或者ok。如果商户反馈给 Starpago 的字符不是success这7个字符或者ok这2个字符，Starpago 服务器会不断重发通知，直到超过24小时47分钟。一般情况下，25小时以内完成9次重发通知（通知的间隔频率一般是：30s,2m,4m,10m,30m,1h,2h,6h,15h）。
某些情况下，商户的一笔订单可能会收到 Starpago 的多次通知，商户需对自己的逻辑进行检查，对于可能收到重复的成功或失败状态的订单通知能够进行唯一的业务处理。

签名机制

商户在调用 Starpago API接口时，需将请求参数中的业务参数，按照 Starpago 约定好的形式，获取到对应的签名字符串，并作为请求参数sign传递给Starpago。

Starpago进行返回参数组装时，也会按照此规则进行签名，并传递签名值。因不同的业务接口可能需要参与签名的字段不同，具体请参照业务接口中，各个接口的具体说明。

获取签名字符串：

请求参数json中的业务信息，按照key的Unicode进行排序。然后将参数以 key1=value1&key2=value2&key3=value3 的形式拼接，最后将商户密钥或应用密钥(不同的接口，签名时使用的密钥可能不相同，具体接口有说明)拼接至字符串最后，键名为‘key‘，键值为密钥值。我们暂且称拼接好的字符串为originStr

将originStr转化为UTF-8的byte数组后，使用sha256算法进行编码，再将编码后的数组转码为16进制的字符串。

在拼接字符串时，会过滤掉key或value为空的字符串的参数，此类参数不参与签名前的字符串拼接。
在请求参数与返回参数的签名中，出现extra字段时，签名时需要将extra的值转换为Map 集合，按照key的Unicode进行排序。然后将Map中参数以key1=value1&key2=value2&key3=value3 的形式拼接为新的字符串作为extra的值。
若其它参数值为对象，会将其转换为JSON字符串后再参与加密。

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

请求HOST#

请求结构#

通信协议#

字符编码#

参数格式#

返回参数#

通知机制#

同步回调#

异步回调#

签名机制#