PAYATHON 2026

Miva Merchant 支付模块如何获取订单与账单变量

支付小周

结论

在支付模块的授权、扣款等回调函数中，优先使用 Miva Merchant 传入的 order 和 amount 参数：

  • 当前交易金额：l.amount
  • 订单总额：l.order:total，仅在确实需要完整订单金额时读取
  • 账单地址：l.order:bill_addr
  • 账单邮编：l.order:bill_zip
  • 账单邮箱：l.order:bill_email

不要依赖结账页面中的全局变量。后台扣款、订单管理、支付重试等流程未必有对应的页面上下文。

代码示例

支付授权函数通常可以这样读取相关数据：

<MvFUNCTION
    NAME="PaymentModule_Authorize"
    PARAMETERS="module var, order var, amount number"
    STANDARDOUTPUTLEVEL=""
>
    <MvASSIGN NAME="l.payment_amount" VALUE="{ l.amount }">
    <MvASSIGN NAME="l.order_total"    VALUE="{ l.order:total }">

    <MvASSIGN NAME="l.billing_address" VALUE="{ l.order:bill_addr }">
    <MvASSIGN NAME="l.billing_zip"     VALUE="{ l.order:bill_zip }">
    <MvASSIGN NAME="l.billing_email"   VALUE="{ l.order:bill_email }">

    <!-- 在这里构造并发送支付网关请求 -->

    <MvFUNCTIONRETURN VALUE="{ 1 }">
</MvFUNCTION>

其中，l. 表示函数局部变量。函数参数名可以修改，但后续引用必须与参数声明一致。

amount 和 order:total 的区别

处理支付时，通常应使用回调函数传入的 amount：

<MvASSIGN NAME="l.gateway_amount" VALUE="{ l.amount }">

不要假定每笔交易的金额都等于：

l.order:total

首次全额授权时，两者可能相同。但在部分扣款、追加扣款、退款或其他订单管理操作中，它们可能不同：

  • l.amount 是当前支付操作需要处理的金额。
  • l.order:total 是订单记录中的总金额。

因此，提交给支付网关的金额通常取自 l.amount。只有业务逻辑明确需要完整订单金额时，才读取 l.order:total。

获取完整账单地址

bill_addr 通常只有街道地址。如果支付网关需要完整的账单信息，还可能要读取以下字段：

<MvASSIGN NAME="l.bill_first_name" VALUE="{ l.order:bill_fname }">
<MvASSIGN NAME="l.bill_last_name"  VALUE="{ l.order:bill_lname }">
<MvASSIGN NAME="l.bill_company"    VALUE="{ l.order:bill_comp }">
<MvASSIGN NAME="l.bill_address"    VALUE="{ l.order:bill_addr }">
<MvASSIGN NAME="l.bill_city"       VALUE="{ l.order:bill_city }">
<MvASSIGN NAME="l.bill_state"      VALUE="{ l.order:bill_state }">
<MvASSIGN NAME="l.bill_zip"        VALUE="{ l.order:bill_zip }">
<MvASSIGN NAME="l.bill_country"    VALUE="{ l.order:bill_cntry }">
<MvASSIGN NAME="l.bill_email"      VALUE="{ l.order:bill_email }">
<MvASSIGN NAME="l.bill_phone"      VALUE="{ l.order:bill_phone }">

这些字段是否存在、是否有值，取决于商店配置、结账表单和所用的 Miva Merchant 模块 API 版本。正式使用前，需要根据目标版本核对支付模块接口定义和订单结构。

安全读取与校验

邮箱、邮编和地址不一定有值。构造网关请求前，可以先进行基本检查：

<MvIF EXPR="{ NOT ISNULL l.order:bill_email }">
    <MvASSIGN NAME="l.billing_email" VALUE="{ l.order:bill_email }">
<MvELSE>
    <MvASSIGN NAME="l.billing_email" VALUE="">
</MvIF>

<MvIF EXPR="{ NOT ISNULL l.order:bill_zip }">
    <MvASSIGN NAME="l.billing_zip" VALUE="{ l.order:bill_zip }">
<MvELSE>
    <MvASSIGN NAME="l.billing_zip" VALUE="">
</MvIF>

还要注意：

  • 直接使用支付回调传入的订单结构，不要根据表单参数重新拼装账单资料。
  • 按支付网关的要求，对发送的文本进行 URL、JSON 或 XML 编码。
  • 不要在普通日志中记录完整账单地址、支付凭据、卡号或安全码。
  • 返回值和错误信息必须符合当前 Miva Merchant 支付模块接口的约定。
  • PaymentModule_Authorize 的具体函数签名可能随模块 API 代际变化。如果现有模块模板中的参数声明不同，应以模板实际传入的 order 和金额参数为准。

备注：内容仅供参考。