@celljs/alipay 4.6.1 → 4.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.zh-cn.md +110 -0
- package/package.json +4 -4
package/README.zh-cn.md
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Cell - 支付宝组件
|
|
2
|
+
|
|
3
|
+
在依赖中添加 `@celljs/alipay` 以使用 [支付宝](https://opendocs.alipay.com/open/00a0ut) 接收支付:一个可注入的 `AlipayClient` 对网关请求进行签名(RSA2)、验证响应的签名并构建页面、WAP 和 App 支付,而通知端点则验证异步通知并交给你的处理器处理。支持公钥模式和证书模式。它使用 Node 的 `crypto` 和 `fetch`,没有第三方依赖。
|
|
4
|
+
|
|
5
|
+
```yaml
|
|
6
|
+
# cell.yml: 配置默认仅限服务端;从环境变量获取凭证
|
|
7
|
+
alipay:
|
|
8
|
+
appId: ${env.ALIPAY_APP_ID}
|
|
9
|
+
privateKey: ${env.ALIPAY_PRIVATE_KEY} # 应用私钥: PEM、base64(PKCS#8 或 PKCS#1)或文件路径
|
|
10
|
+
alipayPublicKey: ${env.ALIPAY_PUBLIC_KEY} # 支付宝公钥(公钥模式)
|
|
11
|
+
notifyUrl: https://shop.example.com/alipay/notify
|
|
12
|
+
# gateway: https://openapi-sandbox.dl.alipaydev.com/gateway.do # 沙箱环境
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
import { Autowired } from '@celljs/core';
|
|
17
|
+
import { Body, Controller, Post } from '@celljs/mvc/lib/node';
|
|
18
|
+
import { AlipayClient, AlipayNotification, AlipayNotificationHandler } from '@celljs/alipay';
|
|
19
|
+
|
|
20
|
+
@Controller('orders')
|
|
21
|
+
export class OrderController {
|
|
22
|
+
@Autowired(AlipayClient)
|
|
23
|
+
protected readonly alipay: AlipayClient;
|
|
24
|
+
|
|
25
|
+
@Post('page') // 电脑网站支付: 重定向浏览器到该 URL
|
|
26
|
+
page(@Body() order: { id: string }) {
|
|
27
|
+
return { url: this.alipay.pagePay({ out_trade_no: order.id, total_amount: '88.88', subject: 'Cell T-shirt' }, { return_url: 'https://shop.example.com/paid' }) };
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
@Post('qr') // 当面付扫码: 显示 qr_code 作为二维码
|
|
31
|
+
async qr(@Body() order: { id: string }) {
|
|
32
|
+
const { qr_code } = await this.alipay.precreate({ out_trade_no: order.id, total_amount: '88.88', subject: 'Cell T-shirt' });
|
|
33
|
+
return { qr_code };
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
@AlipayNotificationHandler(['TRADE_SUCCESS', 'TRADE_FINISHED'])
|
|
38
|
+
export class PaidHandler implements AlipayNotificationHandler {
|
|
39
|
+
async handle(notification: AlipayNotification) {
|
|
40
|
+
// out_trade_no, trade_no, total_amount... 如支付宝发送,签名已验证
|
|
41
|
+
// 仅标记一次订单已支付:同一通知可能多次到达
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## 客户端
|
|
47
|
+
|
|
48
|
+
`biz_content` 使用支付宝文档中的字段名(蛇形命名);金额是元的字符串(`'88.88'`)。支付方法默认 `notify_url` 为 `alipay.notifyUrl`;第二个参数设置其他常见参数(`return_url`、`app_auth_token` 等)。
|
|
49
|
+
|
|
50
|
+
| 方法 | API |
|
|
51
|
+
| --- | --- |
|
|
52
|
+
| `pagePay(request, { httpMethod?, return_url? })` | alipay.trade.page.pay(电脑网站支付):重定向到的 URL,或带 `httpMethod: 'POST'` 时是自提交的 HTML 表单 |
|
|
53
|
+
| `wapPay(request, options?)` | alipay.trade.wap.pay(手机网站支付),结果相同 |
|
|
54
|
+
| `appPay(request)` | alipay.trade.app.pay(App 支付):App SDK 的订单字符串 |
|
|
55
|
+
| `precreate(request)` → `{ qr_code }` | alipay.trade.precreate(当面付扫码) |
|
|
56
|
+
| `create(request)` → `{ trade_no }` | alipay.trade.create(JSAPI / 小程序,`buyer_id` 或 `buyer_open_id`);页面调用 `my.tradePay({ tradeNO })` |
|
|
57
|
+
| `query(query)` / `close(query)` | alipay.trade.query / alipay.trade.close |
|
|
58
|
+
| `refund(request)` / `queryRefund(query)` | alipay.trade.refund / alipay.trade.fastpay.refund.query;部分退款时给 `out_request_no` |
|
|
59
|
+
| `billDownloadUrl({ bill_type, bill_date })` | alipay.data.dataservice.bill.downloadurl.query |
|
|
60
|
+
| `execute(method, biz?, options?)` | 其他任何 API:返回 `<method>_response` |
|
|
61
|
+
| `pageExecute(method, biz?, options?)` / `sdkExecute(method, biz?, options?)` | 其他任何浏览器或 App SDK API |
|
|
62
|
+
| `verifyNotification(params)` | 验证在你自己的路由上收到的通知 |
|
|
63
|
+
|
|
64
|
+
响应的 `code` 不是 `10000` 时会用 `CELL_ALIPAY_API_ERROR` 拒绝;`detail` 是响应(`sub_code: 'ACQ.TRADE_NOT_EXIST'` 等)。响应的签名在其 JSON 文本上检查,如支付宝发送的。
|
|
65
|
+
|
|
66
|
+
## 通知
|
|
67
|
+
|
|
68
|
+
端点是 `POST /alipay/notify`(`alipay.notification.url`,在 `server.path` 下);将其绝对 URL 设置为 `notifyUrl`。它在请求体解析和认证之前运行,验证表单的签名和 `app_id` 是否是该应用的,然后按 `trade_status`(`WAIT_BUYER_PAY`、`TRADE_SUCCESS`、`TRADE_FINISHED`、`TRADE_CLOSED`;没有时用 `notify_type`)运行对应的 `@AlipayNotificationHandler` 组件,再运行没有指定类型的处理器(依次执行)。当所有处理器都成功时返回 `success`,否则返回 `fail`(签名错误时 400,处理器抛出异常时 500),所以支付宝会在稍后重新发送通知:处理器必须是幂等的。部分退款作为通知到达,带有 `refund_fee` 和 `gmt_refund`。
|
|
69
|
+
|
|
70
|
+
通知仅说明发生的事情:发货前检查 `total_amount` 是否与订单相符。
|
|
71
|
+
|
|
72
|
+
## 证书模式
|
|
73
|
+
|
|
74
|
+
用证书创建的应用(公钥证书)给三个证书而不是 `alipayPublicKey`(PEM 文本或文件路径):
|
|
75
|
+
|
|
76
|
+
```yaml
|
|
77
|
+
alipay:
|
|
78
|
+
appId: ${env.ALIPAY_APP_ID}
|
|
79
|
+
privateKey: ${env.ALIPAY_PRIVATE_KEY}
|
|
80
|
+
appCert: certs/appCertPublicKey_2021000000000001.crt
|
|
81
|
+
alipayPublicCert: certs/alipayCertPublicKey_RSA2.crt
|
|
82
|
+
alipayRootCert: certs/alipayRootCert.crt
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
请求携带 `app_cert_sn` 和 `alipay_root_cert_sn`,如支付宝 SDK 计算的;用另一支付宝证书签名的响应被拒,所以当支付宝更新时替换 `alipayPublicCert`。
|
|
86
|
+
|
|
87
|
+
## 配置
|
|
88
|
+
|
|
89
|
+
```yaml
|
|
90
|
+
alipay:
|
|
91
|
+
gateway: https://openapi.alipay.com/gateway.do
|
|
92
|
+
timeout: 10000 # 毫秒,每个请求的超时
|
|
93
|
+
notification:
|
|
94
|
+
enabled: true
|
|
95
|
+
url: /alipay/notify
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## 错误
|
|
99
|
+
|
|
100
|
+
失败是 `AlipayError`,有一个稳定的 `code` 和 `hint`:
|
|
101
|
+
|
|
102
|
+
| 代码 | 何时 |
|
|
103
|
+
| --- | --- |
|
|
104
|
+
| `CELL_ALIPAY_NOT_CONFIGURED` | `appId` 或 `privateKey` 缺失,或既没有 `alipayPublicKey` 也没有全部三个证书 |
|
|
105
|
+
| `CELL_ALIPAY_API_ERROR` | 响应的 `code` 不是 `10000`:`detail.sub_code` 说明原因 |
|
|
106
|
+
| `CELL_ALIPAY_HTTP_ERROR` | 网关返回 HTTP 错误或不是 JSON |
|
|
107
|
+
| `CELL_ALIPAY_SIGNATURE_INVALID` | 响应或通知未由支付宝签名 |
|
|
108
|
+
| `CELL_ALIPAY_APP_ID_MISMATCH` | 通知是给另一应用的 |
|
|
109
|
+
|
|
110
|
+
不支持内容加密(`encrypt_key`、AES)。
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@celljs/alipay",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.8.0",
|
|
4
4
|
"description": "Alipay OpenAPI for Cell: signed gateway requests, page, WAP, App, QR code and JSAPI payments, refunds and verified notifications",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"cell-component",
|
|
@@ -35,9 +35,9 @@
|
|
|
35
35
|
"watch": "tsc -b -w --preserveWatchOutput"
|
|
36
36
|
},
|
|
37
37
|
"dependencies": {
|
|
38
|
-
"@celljs/core": "4.
|
|
39
|
-
"@celljs/http": "4.
|
|
40
|
-
"@celljs/web": "4.
|
|
38
|
+
"@celljs/core": "4.8.0",
|
|
39
|
+
"@celljs/http": "4.8.0",
|
|
40
|
+
"@celljs/web": "4.8.0"
|
|
41
41
|
},
|
|
42
42
|
"publishConfig": {
|
|
43
43
|
"access": "public"
|