# API開發(fā)文檔
## 1. 開發(fā)文檔簡(jiǎn)介
本文閱讀對(duì)象：使用【支付系統(tǒng)】的商戶自服務(wù)系統(tǒng)的技術(shù)架構(gòu)師谭贪、研發(fā)工程師纲缓、系統(tǒng)運(yùn)維工程師怠苔。通過本文檔蟹倾，商戶可了解【支付系統(tǒng)】接入的技術(shù)、接入的產(chǎn)品業(yè)務(wù)譬巫、接入的流程帚桩、接入規(guī)范等信息供嚎，以便于商戶順利完成接入工作纤怒。
## 2. 簽名算法
為了保證交易雙方（商戶和平臺(tái)）的身份和數(shù)據(jù)安全，開發(fā)者在調(diào)用接口前天通，需要配置雙方密鑰泊窘，對(duì)交易數(shù)據(jù)進(jìn)行雙方校驗(yàn)。密鑰包含商戶應(yīng)用私鑰（APP_PRIVATE_KEY）和商戶應(yīng)用公鑰（APP_PUBLIC_KEY）。生成密鑰后烘豹，開發(fā)者需要在商戶后臺(tái)獲取平臺(tái)公鑰（PLATFORM_PUBLIC_KEY）應(yīng)用在代碼中瓜贾，對(duì)請(qǐng)求內(nèi)容進(jìn)行簽名。
【注】平臺(tái)的簽名方案與支付寶的簽名方案一樣携悯，采用RSA2簽名算法（RSA與RSA2簽名算法的區(qū)別祭芦，可參考：[https://docs.open.alipay.com/291/106115/](https://docs.open.alipay.com/291/106115/)），在對(duì)參數(shù)進(jìn)行簽名和異步回調(diào)的驗(yàn)簽時(shí)憔鬼，可直接使用支付寶提供的SDK進(jìn)行簽名和驗(yàn)簽龟劲。
簽名時(shí)字符集使用UTF-8，簽名方式使用RSA2轴或。
## 2.1. 生成密鑰
在商戶后臺(tái)【API管理】【API開發(fā)文檔】中昌跌，點(diǎn)擊【生成秘鑰】，獲取【商戶公鑰】和【商戶私鑰】
生成密鑰對(duì)之后照雁，請(qǐng)商戶保存好【平臺(tái)公鑰】和【商戶私鑰】蚕愤。若商戶忘記秘鑰或者由于某種原因?qū)е滤借€泄漏，請(qǐng)重新生成密鑰饺蚊。平臺(tái)不會(huì)保存商戶的私鑰萍诱，僅在生成時(shí)展示一次，請(qǐng)妥善保存
【商戶私鑰】用于生成請(qǐng)求簽名
【平臺(tái)公鑰】用于對(duì)平臺(tái)的異步回調(diào)的驗(yàn)簽
## 2.2. SDK
推薦使用支付寶SDK進(jìn)行簽名和驗(yàn)簽污呼，
支付寶的SDK的下載地址：[https://docs.open.alipay.com/54/103419/](https://docs.open.alipay.com/54/103419/)
## 2.3. 生成請(qǐng)求簽名
**Java版本的加簽方法**
生成簽名方（通常為商戶）首先對(duì)需要參與簽名的參數(shù)放入一個(gè)字符串?dāng)?shù)組 signFields裕坊，把參數(shù)和值放入一個(gè)對(duì)象或 map 中，使用 JSONObject 把這個(gè)對(duì)象轉(zhuǎn)化成 json 對(duì)象曙求。然后構(gòu)建簽名原文碍庵，在構(gòu)建簽名原文時(shí)，我們需把參數(shù)按照字典（比如a,b,c）順序排序悟狱，具體排序方法直接調(diào)用 JAVA 的 Arrays.sort 方法静浴。 然后使用 RSA 的私鑰對(duì)簽名原文進(jìn)行簽名。
```
/**
@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版本的加簽方法**
生成簽名方（通常為商戶）首先對(duì)需要參與簽名的參數(shù)放入數(shù)組中，調(diào)用支付寶提供的AopClient的rsaSign方法
```
$aop = new AopClient();
$aop->postCharset = "UTF-8";
$aop->alipayrsaPublicKey = $serverPublicKey; // 平臺(tái)公鑰
$aop->rsaPrivateKey = $clientPrivateKey; // 商戶私鑰
// 私鑰加簽
$sign = $aop->rsaSign($params, "RSA2");
```
2.4. 驗(yàn)證通知中的簽名
**Java版本的驗(yàn)簽方法：**
驗(yàn)簽方（商戶）和生產(chǎn)簽名方一樣先生成簽名原文浴麻，然后使用 RSA 的公鑰（平臺(tái)公鑰）生成簽名方傳入的簽名得问，把簽名原文對(duì)生成簽名方傳入的簽名進(jìn)行驗(yàn)證，驗(yàn)證結(jié)果為 true 則說明驗(yàn)證成功软免，否則未通過宫纬。
```
/** rsaCheckV1 此方法會(huì)去掉sign_type做驗(yàn)簽
@param params 參數(shù)列表(包括待驗(yàn)簽參數(shù)和簽名值sign) key-參數(shù)名稱 value-參數(shù)值
@param publicKey 驗(yàn)簽公鑰
@param charset 驗(yàn)簽字符集，使用 UTF-8
@param sign_type 驗(yàn)簽方式膏萧，使用 RSA2
**/
boolean AlipaySignature.rsaCheckV1(Map<String, String> params, String publicKey, String charset, String sign_type)
```
**PHP版本的驗(yàn)簽方法：**
```
$aop = new AopClient();
$aop->alipayrsaPublicKey = $serverPublicKey; // 平臺(tái)公鑰
$verify = $serverAop->rsaCheckV1($params, "", "RSA2");
```
## 3. 請(qǐng)求支付接口
**簡(jiǎn)要描述：** 發(fā)起付款接口(必用接口)?
**跳轉(zhuǎn)支付頁接口URL：**
- 請(qǐng)求方式：POST
- 請(qǐng)求地址：https://www.shenzhou988.com/pay/order/cashier.do
- 使用方法：用表單post的方式漓骚，post參數(shù)并跳轉(zhuǎn)到此網(wǎng)址蝌衔，顯示我們的支付頁。
參數(shù)：
參數(shù)名 | 必選 | 類型 | 參與簽名 | 說明 | 示例值
---|---|---|---|---|---|---|---|---|---|---
memberid| 是| string| 是| 商戶商戶號(hào) |1910123456
appid |是 |string |是 |商戶APPID |20191019080908
bankcode| 是| string| 是| 支付渠道編碼| 103
orderid |是| string| 是 |商戶生成的訂單號(hào)| C2019101908105340685
applydate| 是| string |是 |訂單創(chuàng)建時(shí)間蝌蹂，時(shí)間格式： 2019-10-26 18:18:18 |2019-10-01 18:18:18
amount| 是| float| 是 |交易金額,單位：元精確小數(shù)點(diǎn)后2位 |10.00
notify_url |是 |string |是| 異步通知地址| http://xx.com/
return_url |是 |string |是| 支付成功后網(wǎng)頁自動(dòng)跳轉(zhuǎn)地址 http://xx.com/|
productname |是| string |否| 商品名稱| VIVO手機(jī)膜
sign |是 |string |否| 簽名結(jié)果
attach| 否 |string |否| 用戶附加數(shù)據(jù)|
> 注：
>1. 支付渠道編碼噩斟，請(qǐng)登錄商戶中心，API管理通道費(fèi)率中孤个，查看支付渠道對(duì)應(yīng)的渠道編碼;
>2. 商戶生成的訂單號(hào)剃允，可為字母、數(shù)字的組合齐鲤，訂單號(hào)不可重復(fù)斥废，字符長(zhǎng)度不可超過20
>3. 用戶附加數(shù)據(jù)，當(dāng)商戶傳此數(shù)據(jù)時(shí)佳遂，異步通知時(shí)會(huì)原樣返回
## 四营袜、支付成功的回調(diào)信息
**簡(jiǎn)要描述：**
回調(diào)參數(shù)說明?
請(qǐng)求方式：POST
返回參數(shù)：
header 1 | header 2
---|---
row 1 col 1 | row 1 col 2
row 2 col 1 | row 2 col 2
參數(shù)名 | 必選 | 參與簽名 | 類型 | 說明
---|---|---|---|---
memberid|是|是|string|商戶ID
appid|是|是|string|商戶APPID
bankcode|是|是|string|支付渠道編碼
amount|是|是|string|訂單金額
amount_true|是|是|string|訂單實(shí)付金額
sys_orderid|是|是|string|系統(tǒng)交易單號(hào)
orderid|是|是|string|商戶訂單號(hào)
datetime|是|是|string|YmdHis格式，例：20191020181818
status|是|是|float|SUCCESS 成功丑罪， FAILURE 失敗
sign|是|否|string|RSA簽名荚板，使用平臺(tái)公鑰驗(yàn)簽
attach|否|否|string|若商戶提交訂單時(shí)有傳，則會(huì)原樣返回
**回調(diào)參數(shù)示例**
```
{
? ? "memberid":'10001',
? ? "appid": '2019109121323254555',
? ? "bankcode": '103',
? ? "amount" : '100.00',
? ? "amount_true" : '99.99',
? ? "orderid" : 'C0000000000123',
? ? "sys_orderid" : '20191090934823055834',
? ? "datetime": '20191020181818',
? ? "status" : 'SUCCESS',
? ? "sign" : 'xxxxxxxxxxxxxxxxxxxxxx',
}
```
接收回調(diào)成功吩屹，必須返回 'success' 字符串跪另，否則回調(diào)不成功
```
<?php
//返回成功的信息
echo 'success';
```
