更新时间：2024-11-12 17:53:14文档更新记录 >集成工具收藏订阅更新我的文档设置返回文档本文适用于所有已经接入 商家会员卡 功能，并想要与支付宝进行合作的商家（例如：入会与会员积分兑换、开卡送券、进入公域投放开卡等活动）阅读。完成升级后商家发卡链路的性能将得到大幅提升， 减少发卡链路中商家与支付宝的交互次数，从而提升用户端的领卡体验。建议所有已经接入商家会员卡的商家，尽快根据本文指引进行升级。注意：●同一支付宝账号下任意应用创建的会员卡模板可通用，且历史创建会员卡模板也可继续使用。●在小程序内使用半屏开卡组件时，必须升级新模式开卡，否则无法使用半屏开卡组件。●线上已接入老模式开卡的商家/服务商需先完成新模式对接再逐步迁移业务，确保升级操作不会影响用户正常使用。1 老模式和新模式差异1.1 新模式的优势●简化开卡流程，降低商家接入成本○老模式开卡流程，收到支付宝回调后（http get），商家还需调用 、 、 3 个接口，才能完成整个开卡流程，商家接入成本高、流程长。○新模式开卡流程，回调商家方式改成 spi 模式，商家在收到支付宝 spi 回调后，从入参中获取用户授权的开卡信息，即可实现同步制卡并返回卡信息，商家无需再调用 alipay.system.oauth.token（换取授权访问令牌接口）、alipay.marketing.card.activateform.query（查询用户提交的会员卡表单信息接口）、alipay.marketing.card.open（会员卡开卡接口）。●缩短用户端开卡耗时，提高用户领卡体验 由于简化了接入流程，减少了系统间调用的时间开销，整体的开卡耗时会下降，提升用户体验。1.2 新模式适用场景●线下 iot 刷脸机具●商家私域小程序1.3 新老模式开卡流程1.3.1 老模式交互时序图1.3.2 新模式信息交互时序图2 如何升级到新模式2.1 实现开卡 spi商家开发者需根据 ，实现 spi.alipay.user.opencard.get（会员卡开通，获取会员卡信息接口），提供获取商家私域会员卡信息的能力。支付宝卡包会在用户确认开卡后，调用此 spi 获取商家私域会员卡信息，执行开卡动作，将此会员卡落入支付宝卡包。接入详见可查看 。2.1.1 注意事项spi 接口中字段详情介绍见接口文档 spi.alipay.user.opencard.get（会员卡开通，获取会员卡信息接口），接入过程中需要注意以下几点：●为保证用户体验，商家在收到支付宝 spi 消息后，需在 3s 内返回会员卡信息。●入参中的 user_info 字段，与老模式流程中 的 infos 出参一致，可直接获取用户提交的表单信息。●入参中的 biz_card_no 字段，为预生成的支付宝业务卡号，与老模式流程中 返回的 biz_card_no 一致。商家需要存储 biz_card_no，后续可根据 biz_card_no 更新、查询会员卡。●出参数中的 card_info 字段，与老模式流程中 基础功能 会员卡开卡的 card_ext_info 字段保持一致，其中 external_card_no 语义是商家卡号，针对同个 user_id（open_id），需要固定且唯一。●用户领卡成功后，可能会在支付宝卡包中主动删除会员卡。删除后，用户可能会重新进入开卡组件进行开卡，因此 spi 实现需要支持重复回调，逻辑如下：○商家/服务商 crm 系统中没有该用户的会员卡信息，则需重新为用户开卡并返回卡信息。○商家/服务商 crm 系统中已有该用户的会员卡，则可以直接返回已有的卡信息。2.1.2 示例代码2.2 更新模板商家开发者使用极速版开卡模式，需要在卡模板中指定实现 spi 接口的 appid，因此升级过程中，需要接入最新版 服务端 sdk，调用 更新模板，设置 spi_app_id 字段。2.2.1 spi_app_id 设置规则：●若是第三方代理模式，可以设置成服务商的 appid 或者是商家自己的 appid。●若不是第三方代理模式，只能设置商家自己的 appid。2.3 商家监听开卡结果消息（可选）若商家/服务商关心支付宝侧开卡结果（例如：关注线上开卡的成功率、需要排查开卡失败原因），可以订阅 ，支付宝完成开卡后将通过此接口向商家/服务商的 应用网关地址 发送结果消息。接入详见可查看 。2.3.1 注意事项消息参数等信息可查看 文档，接入过程中需要注意以下几点：●推荐使用 websocket 长连接 sdk 来接收 from 蚂蚁消息。●消息体中的开卡错误信息：error_code、error_msg，与老模式流程中： 返回的错误码一致。2.4 调整小程序插件调用参数2.4.1 订购开卡插件商家需订购 并完成前端集成。2.4.2 前端引入插件第一步：声明插件开发者需在小程序 app.json 文件中声明卡包插件。第二步：使用插件plugin.opencard(params) 接口说明本插件接口用于唤起开卡组件。入参说明参数名称参数类型是否必填描述cardparamsstring是开卡入参。l cardparams.templateidstring是开卡的卡模板 id。l cardparams.templateappidstring是卡模板 id 所关联的 appid。l cardparams.outstringstring否商户自定义透传信息。l cardparams.pagetypestring否开卡组件样式。默认 half（半屏开卡）。枚举支持：●full：全屏开卡。●half：半屏开卡。l cardparams.joinbenefittypestring否扩展功能 入会有礼 专用。为入会有礼对应的权益类型，固定传入：voucher_mrch。l cardparams.joinbenefitidstring否扩展功能 入会有礼 专用。为入会有礼对应的活动 id（商家平台配置所得）。callbackany是开卡完成回调 function。出参说明参数名称参数类型描述successboolean开卡结果。resultcodestring结果码。●10000：用户领卡成功。●10001：用户主动退出。●10002：网络链接错误。resultmsgstring结果信息描述。extinfoobject扩展信息。2.5 完成一次领卡商家在升级流程开发完成后，需使用自助验收工具完成一次领卡才判定为升级成功，开卡小程序 appid 选择 4.1 步骤 订购了支付宝卡包插件的小程序。
