# API开发文档
## 1. 开发文档简介
本文阅读对象：使用【支付系统】的商户自服务系统的技术架构师、研发工程师、系统运维工程师。通过本文档，商户可了解【支付系统】接入的技术、接入的产品业务、接入的流程、接入规范等信息，以便于商户顺利完成接入工作。
## 2. 签名算法
为了保证交易双方（商户和平台）的身份和数据安全，开发者在调用接口前，需要配置双方密钥，对交易数据进行双方校验。密钥包含商户应用私钥（APP_PRIVATE_KEY）和商户应用公钥（APP_PUBLIC_KEY）。生成密钥后，开发者需要在商户后台获取平台公钥（PLATFORM_PUBLIC_KEY）应用在代码中，对请求内容进行签名。
【注】平台的签名方案与支付宝的签名方案一样，采用RSA2签名算法（RSA与RSA2签名算法的区别，可参考：[https://docs.open.alipay.com/291/106115/](https://docs.open.alipay.com/291/106115/)），在对参数进行签名和异步回调的验签时，可直接使用支付宝提供的SDK进行签名和验签。
签名时字符集使用UTF-8，签名方式使用RSA2。
## 2.1. 生成密钥
在商户后台【API管理】【API开发文档】中，点击【生成秘钥】，获取【商户公钥】和【商户私钥】
生成密钥对之后，请商户保存好【平台公钥】和【商户私钥】。若商户忘记秘钥或者由于某种原因导致私钥泄漏，请重新生成密钥。平台不会保存商户的私钥，仅在生成时展示一次，请妥善保存
【商户私钥】用于生成请求签名
【平台公钥】用于对平台的异步回调的验签
## 2.2. SDK
推荐使用支付宝SDK进行签名和验签，
支付宝的SDK的下载地址：[https://docs.open.alipay.com/54/103419/](https://docs.open.alipay.com/54/103419/)
## 2.3. 生成请求签名
**Java版本的加签方法**
生成签名方（通常为商户）首先对需要参与签名的参数放入一个字符串数组 signFields，把参数和值放入一个对象或 map 中，使用 JSONObject 把这个对象转化成 json 对象。然后构建签名原文，在构建签名原文时，我们需把参数按照字典（比如a,b,c）顺序排序，具体排序方法直接调用 JAVA 的 Arrays.sort 方法。 然后使用 RSA 的私钥对签名原文进行签名。
```
/**
@param content 待签名字符串
@param privateKey 加签私钥
@param charset 加签字符集，使用 UTF-8
@param sign_type 签名方式，使用 RSA2
**/
String AlipaySignature.rsaSign(String content, String privateKey, String charset, String sign_type)
```
**PHP版本的加签方法**
生成签名方（通常为商户）首先对需要参与签名的参数放入数组中，调用支付宝提供的AopClient的rsaSign方法
```
$aop = new AopClient();
$aop->postCharset = "UTF-8";
$aop->alipayrsaPublicKey = $serverPublicKey; // 平台公钥
$aop->rsaPrivateKey = $clientPrivateKey; // 商户私钥
// 私钥加签
$sign = $aop->rsaSign($params, "RSA2");
```
2.4. 验证通知中的签名
**Java版本的验签方法：**
验签方（商户）和生产签名方一样先生成签名原文，然后使用 RSA 的公钥（平台公钥）生成签名方传入的签名，把签名原文对生成签名方传入的签名进行验证，验证结果为 true 则说明验证成功，否则未通过。
```
/** rsaCheckV1 此方法会去掉sign_type做验签
@param params 参数列表(包括待验签参数和签名值sign) key-参数名称 value-参数值
@param publicKey 验签公钥
@param charset 验签字符集，使用 UTF-8
@param sign_type 验签方式，使用 RSA2
**/
boolean AlipaySignature.rsaCheckV1(Map<String, String> params, String publicKey, String charset, String sign_type)
```
**PHP版本的验签方法：**
```
$aop = new AopClient();
$aop->alipayrsaPublicKey = $serverPublicKey; // 平台公钥
$verify = $serverAop->rsaCheckV1($params, "", "RSA2");
```
## 3. 请求支付接口
**简要描述：** 发起付款接口(必用接口)
**跳转支付页接口URL：**
- 请求方式：POST
- 请求地址：https://www.shenzhou988.com/pay/order/cashier.do
- 使用方法：用表单post的方式，post参数并跳转到此网址，显示我们的支付页。
参数：
参数名 | 必选 | 类型 | 参与签名 | 说明 | 示例值
---|---|---|---|---|---|---|---|---|---|---
memberid| 是| string| 是| 商户商户号 |1910123456
appid |是 |string |是 |商户APPID |20191019080908
bankcode| 是| string| 是| 支付渠道编码| 103
orderid |是| string| 是 |商户生成的订单号| C2019101908105340685
applydate| 是| string |是 |订单创建时间，时间格式： 2019-10-26 18:18:18 |2019-10-01 18:18:18
amount| 是| float| 是 |交易金额,单位：元精确小数点后2位 |10.00
notify_url |是 |string |是| 异步通知地址| http://xx.com/
return_url |是 |string |是| 支付成功后网页自动跳转地址 http://xx.com/|
productname |是| string |否| 商品名称| VIVO手机膜
sign |是 |string |否| 签名结果
attach| 否 |string |否| 用户附加数据|
> 注：
>1. 支付渠道编码，请登录商户中心，API管理通道费率中，查看支付渠道对应的渠道编码;
>2. 商户生成的订单号，可为字母、数字的组合，订单号不可重复，字符长度不可超过20
>3. 用户附加数据，当商户传此数据时，异步通知时会原样返回
## 四、支付成功的回调信息
**简要描述：**
回调参数说明
请求方式：POST
返回参数：
header 1 | header 2
---|---
row 1 col 1 | row 1 col 2
row 2 col 1 | row 2 col 2
参数名 | 必选 | 参与签名 | 类型 | 说明
---|---|---|---|---
memberid|是|是|string|商户ID
appid|是|是|string|商户APPID
bankcode|是|是|string|支付渠道编码
amount|是|是|string|订单金额
amount_true|是|是|string|订单实付金额
sys_orderid|是|是|string|系统交易单号
orderid|是|是|string|商户订单号
datetime|是|是|string|YmdHis格式，例：20191020181818
status|是|是|float|SUCCESS 成功， FAILURE 失败
sign|是|否|string|RSA签名，使用平台公钥验签
attach|否|否|string|若商户提交订单时有传，则会原样返回
**回调参数示例**
```
{
"memberid":'10001',
"appid": '2019109121323254555',
"bankcode": '103',
"amount" : '100.00',
"amount_true" : '99.99',
"orderid" : 'C0000000000123',
"sys_orderid" : '20191090934823055834',
"datetime": '20191020181818',
"status" : 'SUCCESS',
"sign" : 'xxxxxxxxxxxxxxxxxxxxxx',
}
```
接收回调成功，必须返回 'success' 字符串，否则回调不成功
```
<?php
//返回成功的信息
echo 'success';
```
