商家/服务商如需在用户在支付宝卡包中打开会员卡时，展示自行生成的动态二维码/条形码，可根据本文指引集成动态发码功能。

名词解释

**动态码：**指码值实时生成、只在一定时间内有效、失效后重新发码更新的扫码核销方式。动态码按展示类型可分为动态条形码和动态二维码，一般由支付宝自动发码、核销。

**商户动态码：**指由外部商户自主发码的动态码扫码核销方式，码值、有效期等都由外部商家自主生成和控制。

业务流程

商户动态码的生成和更新采用 支付宝通知商户发码，商户回调支付宝接口更新码值 的方式。整体交互流程大致如下图：

流程上可以分为以下两个阶段：

**通知阶段：**支付宝访问预设的商家系统地址通知商户发码，商家系统返回 ack 应答，告知支付宝收到了发码通知；

**发码阶段：**商家系统生成码值、码过期时间等动态码信息，商家系统调用支付宝开放接口，回传动态码值。

接入流程

交互时序图

第一步：模板配置

商家/服务商需在调用 alipay.marketing.card.template.create（会员卡模板创建）时：

指定为 write_off_type（会员卡核销类型）为 mdbarcode（商户动态条形码）或 mdqrcode（商户动态二维码），即：

write_off_type=mdbarcode，展示商户动态条形码。

write_off_type=mdqrcode，展示商户动态二维码。

在 mdcode_notify_conf（商户动态码通知参数配置）中配置 url（接收发码通知的 https 链接地址）及 ext_params（自定义通知参数）。

示例代码

{
  "write_off_type":"qrcode",
  "mdcode_notify_conf":{
    "url":"https://www.exp-test.com/mcard/dynamicCode",
    "ext_params":"{\"EventType\":\"dynamicCode\",\"MsgType\":\"event\"}"
  }
}

其中关键配置字段的释义如下：

参数	描述	说明	示例
write_off_type	卡包详情页面中展现出的卡码（可用于扫码核销）	展示商家自主生成动态码值（码值、时效性都由商户控制）时，支持：mdqrcode：商户动态二维码，扫码得商户自主传入的码值。mdbarcode：商户动态条码，扫码得商户自主传入的码值。	mdqrcode
mdcode_notify_conf	商户动态码通知参数配置。当 write_off_type 指定为商户动态码 mdbarcode 或 mdqrcode 时必填。	在此字段配置用户打开会员卡时，支付宝通知商户生成动态码（发码）的通知地址及自定义参数通知参数。	-
L url	通知商户发码的 url 地址，必填	只支持 https，post 请求	`https://www.exp-test.com/mcard/dynamicCode`
L ext_params	通知请求自定义参数，选填。	json 格式，通知请求中的商户自定义参数。	{"EventType":"dynamicCode","MsgType":"event"}

商家/服务商完成动态码模板配置后，可根据基础功能指引完成给用户开取会员卡操作。

第二步：通知应答

支付宝通知

当用户在支付宝 APP 内打开会员卡需要加载动态码时，支付宝会向 第一步：模板配置 中 mdcode_notify_conf#url 指定的 https 地址，以下列参数提交 post 请求：

参数	描述	示例
FromAlipayUserId	支付宝uid	2088283746283746
BizCardNo	卡号，支付宝业务卡号。这里是 alipay.marketing.card.open(会员卡开卡)接口返回的 `card_info#biz_card_no`。	000001
CreateTime	时间戳	1405943673657
模板配置的 ext_params	商户自定义参数	"EventType:"dynamicCode","MsgType":"event"
sign	RSA2 算法签名，用于商户端验签，确认请求来源为支付宝。	-

以上文中的模板配置 mdcode_notify_conf 为例，当支付宝用户（用户 ID：2088283746211111）打开会员卡（卡号：123456789）时，支付宝将向 https://www.exp-test.com/mcard/dynamicCode 发起 post 请求，提交以下参数：

{
  "FromAlipayUserId":"2088283746211111",
  "BizCardNo":"123456789",
  "CreateTime":"1405943673657",
  "EventType":"dynamicCode", // 模板配置的 ext_params
  "MsgType":"event", // 模板配置的 ext_params
  "sign":"签名内容"
}

注意：

支付宝出口网关系统会对所有对外的请求参数使用 RSA2 算法进行加签，即 post 提交的参数中还包含额外的参数 sign 存储签名，商户系统收到请求后使用公钥进行验签，以保证收到的请求是来至支付宝的合法请求（验签示例参见 附录：接收支付宝通知的 Java 代码示例）。

支付宝通知验签使用的 ALIPAY_PUBLIC_KEY（支付宝公钥）固定为：

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAk77oKO0IH0xekleDcIaAr5wHGJCQ9ICuiWPRYuPlVYsrslSx2NLo06VK34cnrXNFAMSJZPyyeak8iaqxdRfmn59UkHljIVLVQXi3CWnpmlGavluUrIcklM04b7UUiTbb3/T9N2ubwvIB1/sPH4DcYi83jM3M1YlD40fWe7He+6pMdcLGTAuF/8U5uTT6x26FUDGruvv7mPfeZDdqZrT/F1kpZgU+GULgvL9RZTuaJqwXWwTO9bWx4Hlp3EP6KrfFiV2lTUvoXD/zDn/wPX0/E5I336UVJPzgNg/u+qvpKRibBf4+APv0s93u2Zhe8q66VpJ/Nt4fLsGbRRz7UJb+zwIDAQAB

商户应答

商户系统收到通知后不直接返回动态码，只返回应答表明已经收到该请求。返回的格式如下：

参数	描述	示例
ToUserId	支付宝uid	2088283746283746
MsgType	消息类型（结果码）	`ack`：成功。`fail`：失败，异常情况。
CreateTime	时间戳	1406165628612

返回给支付宝的应答使用 text/xml;charset=GBK 格式。格式示例：

<alipay>
    <response>
        <ToUserId><![CDATA[2088283746283746]]></ToUserId>
        <MsgType><![CDATA[ack]]></MsgType>
        <CreateTime>![CDATA[1406165628612]]</CreateTime>
    </response>
</alipay>

第三步：动态码回传

商家/服务商收到支付宝通知后，需调用 alipay.marketing.card.update（会员卡更新）接口回传自行生成的动态码。

通用参数参见接口文档，商家/服务商需在 card_info#mdcode_info 字段传入动态码信息。

参数	描述	示例
card_info	需要修改的最新卡信息。	-
L mdcode_info	商户动态码回传信息。只用于当 write_off_type 核销类型为 mdbarcode 或 mdqrcode 时，商户调用卡更新接口回传动态码。	-
LL code_status	结果码，当前发码状态。枚举支持：SUCCESS：支付宝会在动态码失效时间之后再发起通知让商户重新发码。FAIL_RETRY：本次发码失败，需支付宝重新发起通知。FAIL_NOT_RETRY：本次发码失败，且当前时间重试通知也无法解决发码问题，支付宝可间隔一段时间后再重试。	SUCCESS
LL code_value	动态码值。code_status 为 SUCCESS 时必填。	123456789
LL expire_time	动态码失效时间，yyyy-MM-dd HH:mm:ss。code_status 为 SUCCESS 时必填。	2022-03-01 12:29:34
LL time_stamp	时间戳。即商户调接口回传动态码时刻对应的 long 类型时间戳，用于区分不同的发码请求。	1405943673657

示例代码

{
  "card_info":{
    "mdcode_info":{
      "code_status":"SUCCESS",
      "code_value":"123456789",
      "expire_time":"2022-03-01 12:29:34",
      "time_stamp":"1405943673657"
    }
  }
}

商户动态发码

名词解释#

业务流程#

接入流程#

交互时序图#

第一步：模板配置#

第二步：通知应答#

支付宝通知#

商户应答#

第三步：动态码回传#

示例代码#

附录：接收支付宝通知的 Java 代码示例#