@qzsy/unipay-sdk
v0.4.2
Published
统一支付网关服务端 TypeScript SDK
Keywords
Readme
@qzsy/unipay-sdk
统一支付网关的服务端 TypeScript SDK。其他应用只放 应用密钥标识 + 服务端密钥,由本包处理访问令牌、防重放键和 application/problem+json。
业务对接步骤、参数、出入包和 Agent 集成指令见 docs/业务对接.md,控制台可交互版在 /user/docs。
金额单位是 CNY 分。密钥和通知签名密钥只能放业务服务端,不要进浏览器或小程序。
安装
npm i @qzsy/unipay-sdk或 bun add @qzsy/unipay-sdk。
两条接入路径
托管收银台: 业务只建单,用户跳到网关页面选方式并付款。适合网站、多业务共用一个公众号支付目录。
直连调起: 业务自己的 H5 / 小程序 / App 调起支付。网关返回 next_action(微信 JSAPI / 小程序 / App、支付宝 trade_no / order_string)。这是微信统一下单的等价物,不必跳收银台。
import { UnifiedPay } from '@qzsy/unipay-sdk'
const pay = new UnifiedPay({
baseUrl: process.env.UNIFIEDPAY_BASE_URL!, // 例如 http://127.0.0.1:3000
clientId: process.env.UNIFIEDPAY_CLIENT_ID!,
clientSecret: process.env.UNIFIEDPAY_CLIENT_SECRET!,
})
// 路径 A:打开托管收银台
const { checkout } = await pay.createHostedCheckout({
intent: {
merchant_order_no: 'ord_1001',
amount: { value: 199 },
subject: '会员充值',
skus: [
{
image: 'https://shop.example.com/sku/member.png',
title: '会员月卡',
desc: '开通 30 天会员',
price: 199,
count: 1,
},
],
return_url: `https://shop.example.com/pay/result?order=ord_1001`,
notify_url: 'https://shop.example.com/webhooks/pay',
},
})
// 把 checkout.checkout_url 发给用户打开
// 路径 B:业务前端自己调起(小程序 / JSAPI / App)
const { attempt } = await pay.createDirectPayment({
intent: {
merchant_order_no: 'ord_1002',
amount: { value: 199 },
subject: '会员充值',
skus: [
{
image: 'https://shop.example.com/sku/member.png',
title: '会员月卡',
desc: '开通 30 天会员',
price: 199,
count: 1,
},
],
notify_url: 'https://shop.example.com/webhooks/pay',
},
payer: {
provider: 'WECHAT',
identifier: openid, // 业务后端用 code 换到的身份
},
attempt: {
provider: 'WECHAT',
interaction: 'MINI_PROGRAM',
},
})
// 把 attempt.next_action 交给前端:executeAction 或 wx.requestPayment / my.tradePay先在控制台登记回跳和通知的站点前缀。下单传完整 return_url / notify_url(可带查询参数),须与已登记地址同协议、同主机,路径落在前缀下。有 notify_url 时只投这一单指定地址,签名仍用匹配端点那把密钥。不传 URL 且应用只有一条登记时,网关用那一条。币种默认 CNY,订单默认 30 分钟过期。
写操作会自动带 Idempotency-Key。同一笔业务重试时请自己传入同一个键(不要含 :):
import { createIdempotencyKey } from '@qzsy/unipay-sdk'
await pay.createIntent(input, { idempotencyKey: createIdempotencyKey() })通知验签
网关请求头:webhook-id / webhook-timestamp / webhook-signature(v1, + HMAC-SHA256 base64)。
import { verifyWebhook } from '@qzsy/unipay-sdk'
const event = verifyWebhook({
secret: process.env.UNIFIEDPAY_WEBHOOK_SECRET!,
headers: request.headers,
rawBody: await request.text(),
})
if (event.type === 'com.unifiedpay.payment.succeeded.v1') {
// 先按 event.id 去重,再查自己的订单并履约
}验签只证明报文真实完整,不代替业务去重和查单。notify_url 即使带了查询参数,密钥也不变。
createRefund 也可传 notify_url;不传则用原单地址。公众号授权回跳用 oauth_return_url,规则与 return_url 相同。
其它常用方法
| 方法 | 对应接口 |
| --- | --- |
| capabilities | GET /api/v1/payment-capabilities |
| createIntent / getIntent / listIntents | /api/v1/payment-intents |
| createDirectPayment | 建意图 + 可选导入身份 + 发起尝试,返回 next_action |
| createCheckoutSession | POST /api/v1/checkout-sessions |
| createAttempt / getAttempt | 支付尝试 |
| cancelIntent / reverseAttempt | 关单 / 付款码撤销 |
| createRefund / getRefund | 退款 |
| listEscrowOrders / getEscrowOrder | 担保单 |
| releaseEscrowOrder | 确认收货:释放担保并触发分账 |
| listSettlements / getSettlement | 结算/分账单及逐接收方明细 |
| listSplitReturns | 分账回退流水 |
| readCheckout | 用收银台只读令牌查状态 |
担保释放与分账
平台模式收单时,资金先冻结在二级商户账户;业务确认收货 / 服务完成后调 releaseEscrowOrder,网关在释放时完成平台佣金、供应商分成和商家结算:
const page = await pay.listEscrowOrders({ merchant_order_no: 'SO-1001' })
const escrow = page.items[0]
if (!escrow) throw new Error('担保单不存在或未开启担保')
const { settlement } = await pay.releaseEscrowOrder(escrow.id, {
idempotencyKey: `release_${escrow.id}`,
})
// settlement.receivers: 平台佣金 / 供应商 / 商家结算,金额合计等于订单金额
// status=PROCESSING 时不要当成功,等 webhook 或轮询
const latest = await pay.getSettlement(settlement.id)- 释放需要
escrow:write,查询需要escrow:read。 - 首版只支持整笔结清;部分释放会返回业务错误。
- 商户未开通担保 / 分账权限时没有担保单,
listEscrowOrders为空,releaseEscrowOrder返回 404。 - 已释放订单退款,平台佣金会自动回退(
listSplitReturns可查);供应商分成目前不自动回退。 releaseEscrowOrder幂等:已有处理中的结算单会直接返回,不会重复分账。
浏览器 / 小程序侧用 @qzsy/unipay-sdk/browser:openCheckout 打开托管页;executeAction(next_action) 按 sdk 调起微信 JSAPI、wx.requestPayment、支付宝 H5 / my.tradePay。App 用 createDirectPayment,interaction: 'APP_SDK',Android 和鸿蒙传 environment: 'ANDROID_APP',不要传 payer。WECHAT_APP 的 app_id / partner_id / prepay_id / package_value / nonce_str / timestamp / signature 交给 fluwx;ALIPAY_APP 的 order_string 原样交给 tobias。浏览器里对这两种参数会返回 UNSUPPORTED。客户端回调不等于到账。不要把 clientSecret 带到前端。
微信内 H5 若要在业务自己的页面调 JSAPI,该页必须在微信支付授权目录里;否则请走托管收银台。小程序和 App 没有这个限制。
集团 SaaS(/api/v1/group)
集团级凭据(group:read / group:write,由网关运营签发)可以读整个租户的数据,并代门店主体开通账户与权限;集团凭据不绑定应用。
import { GroupClient } from '@qzsy/unipay-sdk'
const group = new GroupClient({
baseUrl: 'https://pay.example.com',
clientId: process.env.GROUP_CLIENT_ID!,
clientSecret: process.env.GROUP_CLIENT_SECRET!,
})
// 总管理员代门店操作时上报操作人,网关会写进审计日志与审批单
const operator = { id: 'usr_admin_1', name: 'Group Admin', site: 'store_hz_01' }
const { items: entities } = await group.listEntities()
const statements = await group.listStatements({ scope: 'STORE', store_code: 'store_hz_01' })
const snapshot = await group.getSnapshot()
// 建主体 + 建应用 + 绑通道 + 进件
const { entity } = await group.createEntity(
{ name: '门店一', legal_name: '门店一有限公司', license_no: '91330100MA2H8XK21P' },
{ operator },
)
const { application, credential } = await group.createApplication(
{ entity_id: entity.id, name: '门店一收银台', slug: 'store-1' },
{ operator },
)
await group.bindApplicationChannel(
{ application_id: application.id, provider: 'WECHAT', channel_account_id: 'ca_xxx' },
{ operator },
)
await group.createMerchantAccount(
{ provider: 'WECHAT', merchant_entity_id: entity.id, materials: { contact_name: '张三' } },
{ operator },
)
// 申请分账权限,等平台运营审批
const approval = await group.applyEscrowPermission('mpa_xxx', { operator })
// 佣金转账走普通付款接口,带上门店与来源订单便于对账
await group.createPayout({
scene_key: 'commission',
merchant_payout_no: 'po_20261116_1',
amount: { value: 1234, currency: 'CNY' },
payee: { type: 'WECHAT_OPENID', id: 'o_xxx', app_id: 'wx1234567890abcdef' },
remark: '11 月佣金',
site_code: 'store_hz_01',
source_order_nos: ['REVIEW-1001'],
})| 方法 | 对应接口 |
| --- | --- |
| getOverview / listEntities / listApplications / listChannelAccounts / listSplitRules | G-1 ~ G-5 读接口 |
| listStatements / getStatement / downloadStatementCsv | G-6 账单(组织 / 主体 / 门店) |
| listPaymentIntents / getSnapshot | G-7 / G-8 |
| listGroupPayouts / getGroupPayout | G-9 / G-10 佣金付款 |
| createEntity / createApplication / bindApplicationChannel / createMerchantAccount | W-1 ~ W-4 代门店开通 |
| applyEscrowPermission / getEscrowApplication | W-5 / W-6 分账权限申请 |
写操作必须带幂等键:SDK 会自动生成 Idempotency-Key,重试时请传入同一个键。
错误
失败会抛 GatewayError:code、message(或 problem.detail)、retryable、requestId。retryable === true 时只能用同一防重放键 / 同一业务单号重试,不能另开一笔扣款。
本地试跑
开发服务起来后:
UNIFIEDPAY_CLIENT_SECRET=演示服务端密钥 bun packages/sdk/examples/checkout.ts
UNIFIEDPAY_CLIENT_SECRET=演示服务端密钥 bun packages/sdk/examples/direct-pay.ts密钥在管理端「支付网关 → 开发者中心」复制。本机优先 http://127.0.0.1:3000;若只监听了 IPv6,改用 http://localhost:3000。
