Skip to content

k.payment ​

第三方支付集成。

概述 ​

k.payment 提供支付请求创建、支付状态查询、支付请求记录读取等能力。使用前需要先在站点 CMS 服务集成 · Payment 中启用并配置对应支付方式。

charge() 会写入站点内置 PaymentRequest;若传入 Commerce order,支付成功后由内建 callback 更新订单。不要默认自建一套平行支付表。

如何选择支付方式 ​

用户目标推荐 APInextAction 形态
微信扫码 / PC 二维码k.payment.wechatrenderHtml
微信手机浏览器 H5k.payment.weChatH5redirectUrl → 见 微信 H5 流程
微信内置浏览器k.payment.wechatJsApiresponseData(需 openId)
支付宝网页收银台k.payment.alipayFormrenderHtml
支付宝 H5k.payment.alipayH5renderHtml
PayPal Checkoutk.payment.paypalCheckoutredirect / renderHtml
Stripe 托管页k.payment.stripeCheckoutredirect / renderHtml
Stripe 站内卡支付k.payment.stripepaid 或 3DS redirectUrl

支付方式文档 ​

文档API
支付宝k.payment.alipayApp、k.payment.alipayForm、k.payment.alipayH5
微信支付k.payment.wechat、k.payment.wechatApp、k.payment.weChatH5、k.payment.wechatJsApi
PayPalk.payment.paypalCheckout、k.payment.paypalForm
Stripek.payment.stripeCheckout、k.payment.stripe
Squarek.payment.square
Pay.NLk.payment.paynlCheckout
TwoCheckoutk.payment.twoCheckout
MoneyBoxsk.payment.moneyBoxs

多货币注意 ​

k.commerce.currency.list() 返回站点已配置货币;每个 provider 还有 supportedCurrency。发起支付前应取两者交集。微信 / 支付宝通常仅 CNY。

getRequest() ​

根据 requestId 获取支付请求记录。

ts
k.api.get(() => {
    const request = k.payment.getRequest('request-id')
    return {
        id: request.id,
        paid: request.paid,
        failed: request.failed,
        paymentMethod: request.paymentMethod,
        order: request.order
    }
})

参数:

参数类型必填说明
requestIdstring是charge() 返回的支付请求 ID

返回: PaymentRequest

通用属性 ​

每个支付方式对象都包含以下基础属性。

属性类型说明
namestring支付方式内部名称
displayNamestring展示名称
iconstring图标地址或内容
iconTypestring图标类型
supportedCurrencystring[]支持的货币
contextobject当前支付上下文
settingobject该支付方式的站点配置

通用流程 ​

ts
k.api.get(() => {
    const product = k.commerce.product.get('test-product')
    const cartId = k.commerce.cart.create()

    k.commerce.cart.addOrUpdateLine(cartId, product.variants[0].id, 1)
    k.commerce.cart.updateContact(cartId, 'customer@example.com')

    const order = k.commerce.order.create(cartId, {
        address: { firstName: 'Test', phone: '13800138000' } as any
    })

    const charge = k.payment.alipayForm.charge({
        name: product.title,
        description: 'Order payment',
        totalAmount: order.totalAmount,
        currency: 'CNY',
        order: order.id,
        returnUrl: `/__paymentCallback?orderId=${order.id}`,
        callbackCodeName: 'PaymentCallback'
    })

    k.logger.information('Payment.Info', `requestId: ${charge.requestId}, orderId: ${order.id}`)

    // 保存 requestId,供支付回调按订单查询
    k.DB.keyValue.set(`payment:${order.id}`, charge.requestId)

    k.response.renderView(charge.nextAction.renderHtml)
})

支付回调示例 ​

returnUrl 是支付完成后的跳转地址。可以在地址上携带订单 ID,再用下单时保存的 requestId 查询真实支付状态。

ts
k.api.get(() => {
    const orderId = k.request.queryString.get("orderId")
    if (!orderId) {
        k.response.json({ code: -1, msg: 'order ID is not found' })
        return k.api.httpCode(400)
    }

    // 取回创建支付时保存的 requestId
    const saved = k.DB.keyValue.get(`payment:${orderId}`)
    const requestId = saved ? saved.toString() : null
    if (!requestId) {
        k.response.json({ code: -1, msg: 'payment request ID is not found' })
        return k.api.httpCode(400)
    }

    const status = k.payment.alipayForm.checkStatus(requestId)
    if (status?.paid) {
        k.response.redirect(`/order/${orderId}`)
        return
    }

    k.response.redirect('/payment-failed')
})

ChargeResponse ​

属性类型说明
paidboolean是否已支付
requestIdany支付请求 ID,后续查询状态时使用
paymentMethodReferenceIdstring第三方支付侧引用 ID
nextActionNextAction下一步动作

NextAction ​

属性类型说明
typestring动作类型,如跳转、渲染 HTML、二维码等
redirectUrlstring需要重定向时的目标地址
renderHtmlstring需要渲染到页面上的 HTML
responseDatastring第三方返回的原始响应数据,常用于二维码或客户端 SDK 参数

PaymentStatusResponse ​

属性类型说明
hasResultboolean是否已有查询结果
paidboolean是否支付成功
failedboolean是否支付失败
statusPaymentStatus支付状态
messagestring状态消息

PaymentStatus 可为:NotAvailable、Authorized、Pending、Paid、Cancelled、Rejected。

PaymentRequest ​

属性类型说明
idany支付请求 ID
descriptionstring支付描述
totalAmountnumber金额
currencystring货币
orderstring关联的 Commerce 订单 ID
paymentMethodstring支付方式
paidboolean是否已支付
failedboolean是否失败
callbackCodeNamestring支付完成后执行的回调代码名称
referenceIdstring第三方引用 ID
returnUrlstring支付完成跳转地址
cancelUrlstring取消支付跳转地址
additionalRecord<string, any>支付方式附加数据
cardCard卡信息
creationDateDate创建时间
lastModifiedDate最后修改时间
namestring支付名称