沙箱环境是支付宝开放平台为开发者提供的与生产环境完全隔离的联调测试环境，开发者在沙箱环境中完成的接口调用不会对生产环境中的数据造成任何影响。

沙箱为开放的产品提供 有限功能范围 的支持（覆盖的功能范围参见下面的业务用例），可以覆盖产品的绝大部分核心链路和对接逻辑，便于开发者快速学习/尝试/开发/调试，推荐开发者遵循业务用例来使用沙箱。

沙箱环境会自动完成或忽略一些场景的业务门槛，例如：开发者无需等待产品签约，即可直接在沙箱环境调用接口，使得开发集成工作可以与商务流程并行，从而提高项目整体的交付效率。

注意：

由于沙箱环境并非 100% 与生产环境一致，接口的实际响应逻辑请以生产环境为准，沙箱环境开发调试完成后，仍然需要在生产环境进行测试验收。

沙箱环境拥有完全独立的数据体系，沙箱环境下返回的数据（比如用户 ID 等）在生产环境中都是不存在的，开发者不可将沙箱环境返回的数据与生产环境中的数据混淆。

本文仅说明如何在沙箱环境中调试商家会员卡，非沙箱环境调试通用说明。

更多沙箱介绍和沙箱控制台使用说明可查看沙箱环境。

商家会员卡沙箱调试说明

沙箱通过业务用例定义支持的功能范围。业务用例描述了典型业务场景下，开发者可通过先后对接哪些接口来实现业务目标，每个业务用例会为开发者提供接口调用时序与参数示例值。

推荐开发者遵循业务用例来使用沙箱。

注意：

示例参数值中与沙箱当前账号、应用上下文相关的参数，需开发者自行参照接入指南调用配套接口获取。

目前沙箱钱包端上相关的功能还不支持。

该产品只在新沙箱环境提供支持。

业务用例

配置会员卡模板

上传卡模板图片文件

调用OpenAPI：alipay.offline.material.image.upload

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayOfflineMaterialImageApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayOfflineMaterialImageApiUpload {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayOfflineMaterialImageApi api = new AlipayOfflineMaterialImageApi();
        AlipayOfflineMaterialImageUploadModel data = new AlipayOfflineMaterialImageUploadModel();
        data.setImageName("海底捞");
        data.setImagePid("2088021822217233");
        data.setImageType("jpg或mp4");
        File imageContent = new File("文件路径");
        try {
            AlipayOfflineMaterialImageUploadResponseModel response = api.upload(data, imageContent);
        } catch (ApiException e) {
            AlipayOfflineMaterialImageUploadDefaultResponse errorObject = (AlipayOfflineMaterialImageUploadDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

出参示例值：

{
    "image_url":"http://dl.django.t.taobao.com/rest/1.0/image?fileIds=V9rfg69SSimLZg5wDA3yEgAAACMA...",
    "image_id":"hOTQ1lT1TtOjcxGflvnUXgAAACMAAQED"
}

创建会员卡模板

调用OpenAPI：alipay.marketing.card.template.create

入参示例值：

说明：request_id 每次需要变化。

{
  "biz_no_prefix": "20",
  "biz_no_suffix_len": "20",
  "card_action_list": [
    {
      "code": "TO_CLOCK_IN",
      "text": "打卡",
      "url": "http:\/\/www.sandbox.com",
      "url_type": "url"
    }
  ],
  "card_type": "OUT_MEMBER_CARD",
  "column_info_list": [
    {
      "code": "BENEFIT_INFO",
      "group_title": "沙箱",
      "icon_id": "1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
      "more_info": {
        "descs": [
          "会员生日7折"
        ],
        "title": "沙箱会员专享权益",
        "url": "http:\/\/www.sandbox.com"
      },
      "operate_type": "openWeb",
      "tag": "沙箱",
      "title": "会员专享",
      "value": "80"
    }
  ],
  "field_rule_list": [
    {
      "field_name": "Balance",
      "rule_name": "ASSIGN_FROM_REQUEST",
      "rule_value": "Balance"
    }
  ],
  "request_id": "20220805100000023100613",
  "template_style_info": {
    "background_id": "1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
    "bg_color": "rgb(55,112,179)",
    "card_show_name": "沙箱测试会员卡",
    "color": "rgb(55,112,179)",
    "front_image_enable": false,
    "front_text_list_enable": false,
    "logo_id": "1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC"
  },
  "write_off_type": "qrcode"
}

出参示例值：

{
    "template_id":"201607180000001"
}

配置卡模板开卡表单

调用OpenAPI：alipay.marketing.card.formtemplate.set

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingCardFormtemplateApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingCardFormtemplateApiSet {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingCardFormtemplateApi api = new AlipayMarketingCardFormtemplateApi();
        AlipayMarketingCardFormtemplateSetModel data = new AlipayMarketingCardFormtemplateSetModel();
        OpenFormFieldDO fields = new OpenFormFieldDO();
        fields.setOptional("{\n\n \"common_fields\": [\n\n \"OPEN_FORM_FIELD_GENDER\"\n\n ]\n\n }");
        fields.setRequired("{\n\n \"common_fields\": [\n\n \"OPEN_FORM_FIELD_MOBILE\"\n\n ]\n\n }");
        data.setFields(fields);
        data.setTemplateId("20170228000000000210102000300974");
        try {
            Object response = api.set(data);
        } catch (ApiException e) {
            AlipayMarketingCardFormtemplateSetDefaultResponse errorObject = (AlipayMarketingCardFormtemplateSetDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

出参示例值：

{}

修改会员卡模板

调用OpenAPI：alipay.marketing.card.template.modify

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingCardTemplateApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingCardTemplateApiModify {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingCardTemplateApi api = new AlipayMarketingCardTemplateApi();
        AlipayMarketingCardTemplateModifyModel data = new AlipayMarketingCardTemplateModifyModel();
        PaidOuterCardTemplateConfDTO paidOuterCardConf = new PaidOuterCardTemplateConfDTO();
        PaidOuterCardManageUrlConfDTO manageUrlConf = new PaidOuterCardManageUrlConfDTO();
        manageUrlConf.setUpgradeUrl("https://www.alipay.com");
        manageUrlConf.setDowngradeUrl("https://www.alipay.com");
        manageUrlConf.setRefundUrl("https://www.alipay.com");
        manageUrlConf.setCycleManageUrl("https://www.alipay.com");
        manageUrlConf.setRenewUrl("https://www.alipay.com");
        paidOuterCardConf.setManageUrlConf(manageUrlConf);
        PaidOuterCardCycleSellConfDTO cycleSellingConf = new PaidOuterCardCycleSellConfDTO();
        List<String> cycleType = new ArrayList<String>();
        cycleType.add("YEAR");
        cycleType.add("QUARTER");
        cycleSellingConf.setCycleType(cycleType);
        cycleSellingConf.setSupportCycleSell(true);
        cycleSellingConf.setCycleSellingUrl("https://www.alipay.com");
        paidOuterCardConf.setCycleSellingConf(cycleSellingConf);
        PaidOuterCardSellingConfDTO openSellingConf = new PaidOuterCardSellingConfDTO();
        openSellingConf.setStartDate("2021-01-01 12:00:00");
        openSellingConf.setEndDate("2031-01-01 12:00:00");
        List<PaidOuterCardPriceDetailDTO> priceDetail = new ArrayList<PaidOuterCardPriceDetailDTO>();
        PaidOuterCardPriceDetailDTO priceDetail0 = new PaidOuterCardPriceDetailDTO();
        priceDetail0.setWorth("199.99");
        priceDetail0.setDesc("99购超值会员卡");
        priceDetail0.setPriceType("FIXED");
        priceDetail0.setPrice("99.99");
        priceDetail.add(priceDetail0);
        openSellingConf.setPriceDetail(priceDetail);
        openSellingConf.setSellingUrl("https://www.alipay.com");
        paidOuterCardConf.setOpenSellingConf(openSellingConf);
        data.setPaidOuterCardConf(paidOuterCardConf);
        TemplateOpenCardConfDTO openCardConf = new TemplateOpenCardConfDTO();
        List<TemplateRightsContentDTO> cardRights = new ArrayList<TemplateRightsContentDTO>();
        TemplateRightsContentDTO cardRights0 = new TemplateRightsContentDTO();
        cardRights0.setDetail("积分随时查，积分换好礼");
        cardRights0.setLogoId("1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC");
        cardRights0.setTitle("积分兑换好礼");
        cardRights.add(cardRights0);
        openCardConf.setCardRights(cardRights);
        openCardConf.setOpenCardUrl("https://www.alipay.com");
        openCardConf.setConf("\"\"");
        openCardConf.setOpenCardSourceType("ISV");
        openCardConf.setSourceAppId("201609191111111");
        data.setOpenCardConf(openCardConf);
        data.setCardSpecTag("NONE");
        data.setTemplateId("201607180000001");
        List<TemplateFieldRuleDTO> fieldRuleList = new ArrayList<TemplateFieldRuleDTO>();
        TemplateFieldRuleDTO fieldRuleList0 = new TemplateFieldRuleDTO();
        fieldRuleList0.setRuleName("ASSIGN_FROM_REQUEST");
        fieldRuleList0.setFieldName("Balance");
        fieldRuleList0.setRuleValue("Balance");
        fieldRuleList.add(fieldRuleList0);
        data.setFieldRuleList(fieldRuleList);
        data.setSpiAppId("2014072300007148");
        List<TemplateActionInfoDTO> cardActionList = new ArrayList<TemplateActionInfoDTO>();
        TemplateActionInfoDTO cardActionList0 = new TemplateActionInfoDTO();
        cardActionList0.setCode("TO_CLOCK_IN");
        cardActionList0.setUrl("https://merchant.ali.com/ee/clock_in.do");
        cardActionList0.setUrlType("url");
        cardActionList0.setText("打卡");
        TemplateActionMiniAppUrlDTO miniAppUrl = new TemplateActionMiniAppUrlDTO();
        miniAppUrl.setMiniAppId("2018xxxxxxx");
        miniAppUrl.setMiniQueryParam("abc");
        miniAppUrl.setMiniPageParam("/index");
        miniAppUrl.setDisplayOnList("false");
        cardActionList0.setMiniAppUrl(miniAppUrl);
        cardActionList.add(cardActionList0);
        data.setCardActionList(cardActionList);
        List<TemplateBenefitInfoDTO> templateBenefitInfo = new ArrayList<TemplateBenefitInfoDTO>();
        TemplateBenefitInfoDTO templateBenefitInfo0 = new TemplateBenefitInfoDTO();
        templateBenefitInfo0.setStartDate("2016-07-18 15:17:23");
        templateBenefitInfo0.setEndDate("2016-07-34 12:12:12");
        List<String> benefitDesc = new ArrayList<String>();
        benefitDesc.add("消费即折扣");
        templateBenefitInfo0.setBenefitDesc(benefitDesc);
        templateBenefitInfo0.setTitle("消费即折扣");
        templateBenefitInfo.add(templateBenefitInfo0);
        data.setTemplateBenefitInfo(templateBenefitInfo);
        List<TemplateCardLevelConfDTO> cardLevelConf = new ArrayList<TemplateCardLevelConfDTO>();
        TemplateCardLevelConfDTO cardLevelConf0 = new TemplateCardLevelConfDTO();
        cardLevelConf0.setLevelShowName("黄金会员");
        cardLevelConf0.setLevelDesc("黄金会员享受免费停车");
        cardLevelConf0.setLevel("VIP1");
        cardLevelConf0.setLevelIcon("1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC");
        cardLevelConf.add(cardLevelConf0);
        data.setCardLevelConf(cardLevelConf);
        TemplateMdcodeNotifyConfDTO mdcodeNotifyConf = new TemplateMdcodeNotifyConfDTO();
        mdcodeNotifyConf.setUrl("https://www.ali123.com/ant/mdcode");
        mdcodeNotifyConf.setExtParams("{\"param1\":\"value1\",\"param2\":\"value2\"}");
        data.setMdcodeNotifyConf(mdcodeNotifyConf);
        TemplateStyleInfoDTO templateStyleInfo = new TemplateStyleInfoDTO();
        templateStyleInfo.setBgColor("rgb(55,112,179)");
        templateStyleInfo.setSloganImgId("1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC");
        List<String> featureDescriptions = new ArrayList<String>();
        featureDescriptions.add("使用花呗卡可享受免费分期");
        templateStyleInfo.setFeatureDescriptions(featureDescriptions);
        templateStyleInfo.setBannerUrl("http://www.baidu.com");
        templateStyleInfo.setBrandName("可乐");
        templateStyleInfo.setSlogan("会员权益享不停");
        templateStyleInfo.setFrontTextListEnable(false);
        templateStyleInfo.setCardShowName("花呗联名卡");
        templateStyleInfo.setBannerImgId("1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC");
        templateStyleInfo.setColumnInfoLayout("list");
        templateStyleInfo.setLogoId("1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC");
        templateStyleInfo.setColor("rgb(55,112,179)");
        templateStyleInfo.setBackgroundId("1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC");
        templateStyleInfo.setFrontImageEnable(false);
        data.setTemplateStyleInfo(templateStyleInfo);
        data.setBizNoPrefix("prex");
        List<PubChannelDTO> pubChannels = new ArrayList<PubChannelDTO>();
        PubChannelDTO pubChannels0 = new PubChannelDTO();
        pubChannels0.setPubChannel("SHOP_DETAIL");
        pubChannels0.setExtInfo("{\"key\":\"value\"}");
        pubChannels.add(pubChannels0);
        data.setPubChannels(pubChannels);
        List<String> shopIds = new ArrayList<String>();
        shopIds.add("2015122900077000000002409504");
        data.setShopIds(shopIds);
        data.setRequestId("2016072100000000001");
        data.setBizNoSuffixLen("10");
        data.setWriteOffType("qrcode");
        List<TemplateColumnInfoDTO> columnInfoList = new ArrayList<TemplateColumnInfoDTO>();
        TemplateColumnInfoDTO columnInfoList0 = new TemplateColumnInfoDTO();
        columnInfoList0.setCode("BENEFIT_INFO");
        columnInfoList0.setTag("热门");
        MoreInfoDTO moreInfo = new MoreInfoDTO();
        moreInfo.setUrl("http://www.baidu.com");
        moreInfo.setParams("{}");
        moreInfo.setTitle("会员专享权益");
        List<String> descs = new ArrayList<String>();
        descs.add("会员生日7折");
        moreInfo.setDescs(descs);
        columnInfoList0.setMoreInfo(moreInfo);
        columnInfoList0.setOperateType("openWeb");
        columnInfoList0.setTitle("会员专享");
        columnInfoList0.setValue("80");
        columnInfoList0.setGroupTitle("校园助手");
        columnInfoList0.setIconId("1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC");
        columnInfoList.add(columnInfoList0);
        data.setColumnInfoList(columnInfoList);
        try {
            AlipayMarketingCardTemplateModifyResponseModel response = api.modify(data);
        } catch (ApiException e) {
            AlipayMarketingCardTemplateModifyDefaultResponse errorObject = (AlipayMarketingCardTemplateModifyDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

出参示例值：

{
    "template_id":"2016071800000000001"
}

查询会员卡模板

调用OpenAPI：alipay.marketing.card.template.query

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingCardTemplateApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingCardTemplateApiQuery {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingCardTemplateApi api = new AlipayMarketingCardTemplateApi();
        String templateId = "20160718000000001";
        try {
            AlipayMarketingCardTemplateQueryResponseModel response = api.query(templateId);
        } catch (ApiException e) {
            AlipayMarketingCardTemplateQueryDefaultResponse errorObject = (AlipayMarketingCardTemplateQueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

出参示例值：

{
    "mdcode_notify_conf":{
        "ext_params":"{\"param1\":\"value1\",\"param2\":\"value2\"}",
        "url":"https://www.ali123.com/ant/mdcode"
    },
    "card_level_confs":[
        {
            "level_show_name":"黄金会员",
            "level":"VIP1",
            "level_icon":"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
            "level_desc":"黄金会员享受免费停车"
        }
    ],
    "paid_outer_card_conf":{
        "open_selling_conf":{
            "end_date":"2031-01-01 12:00:00",
            "price_detail":[
                {
                    "price":"99.99",
                    "price_type":"FIXED",
                    "worth":"199.99",
                    "desc":"99购超值会员卡"
                }
            ],
            "start_date":"2021-01-01 12:00:00",
            "selling_url":"https://www.alipay.com"
        },
        "manage_url_conf":{
            "refund_url":"https://www.alipay.com",
            "cycle_manage_url":"https://www.alipay.com",
            "downgrade_url":"https://www.alipay.com",
            "renew_url":"https://www.alipay.com",
            "upgrade_url":"https://www.alipay.com"
        },
        "cycle_selling_conf":{
            "support_cycle_sell":true,
            "cycle_type":[
                "YEAR",
                "QUARTER"
            ],
            "cycle_selling_url":"https://www.alipay.com"
        }
    },
    "card_spec_tag":"NONE",
    "template_style_info":{
        "front_image_enable":false,
        "color":"rgb(55,112,179)",
        "logo_id":"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
        "brand_name":"可乐",
        "column_info_layout":"list",
        "background_id":"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
        "feature_descriptions":[
            "使用花呗卡可享受免费分期"
        ],
        "bg_color":"rgb(55,112,179)",
        "front_text_list_enable":false,
        "banner_img_id":"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
        "slogan_img_id":"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
        "card_show_name":"花呗联名卡",
        "banner_url":"http://www.baidu.com",
        "slogan":"会员权益享不停"
    },
    "open_card_conf":{
        "source_app_id":"201609191111111",
        "card_rights":[
            {
                "logo_id":"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
                "detail":"积分随时查，积分换好礼",
                "title":"积分兑换好礼"
            }
        ],
        "open_card_source_type":"ISV",
        "open_card_url":"https://www.alipay.com",
        "conf":"\"\""
    },
    "template_benefit_info":[
        {
            "end_date":"2016-07-34 12:12:12",
            "benefit_desc":[
                "消费即折扣"
            ],
            "title":"消费即折扣",
            "start_date":"2016-07-18 15:17:23"
        }
    ],
    "column_info_list":[
        {
            "group_title":"校园助手",
            "operate_type":"openWeb",
            "code":"BENEFIT_INFO",
            "more_info":{
                "descs":[
                    "会员生日7折"
                ],
                "title":"会员专享权益",
                "params":"{}",
                "url":"http://www.baidu.com"
            },
            "tag":"热门",
            "title":"会员专享",
            "icon_id":"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
            "value":"80"
        }
    ],
    "card_type":"OUT_MEMBER_CARD",
    "biz_no_suffix_len":"10",
    "spi_app_id":"2014072300007148",
    "field_rule_list":[
        {
            "rule_name":"ASSIGN_FROM_REQUEST",
            "rule_value":"Balance",
            "field_name":"Balance"
        }
    ],
    "service_label_list":[
        "HUABEI_FUWU"
    ],
    "card_action_list":[
        {
            "code":"TO_CLOCK_IN",
            "url_type":"url",
            "text":"打卡",
            "mini_app_url":{
                "mini_app_id":"2018xxxxxxx",
                "mini_page_param":"/index",
                "mini_query_param":"abc",
                "display_on_list":"false"
            },
            "url":"https://merchant.ali.com/ee/clock_in.do"
        }
    ],
    "biz_no_prefix":"prex",
    "pub_channels":[
        {
            "ext_info":"{\"key\":\"value\"}",
            "pub_channel":"SHOP_DETAIL"
        }
    ],
    "shop_ids":[
        "2015122900077000000002409504"
    ]
}

会员卡管理

实现获取会员卡 SPI 接口

实现 SPI 接口：spi.alipay.user.opencard.get

具体的实现可以参考 [实现获取会员卡 SPI 接口](https://opendocs.alipay.com/open-v3/05w8jv?ref=api_v3#1. 实现获取会员卡 SPI 接口)。

触发用户开卡

目前沙箱钱包端上相关的功能还不支持，需要以下 2 步完成用户开卡（线上环境不需要）

\1. 配置领卡链接，配置的 callback 地址暂时不会被使用。

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingCardActivateurlApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingCardActivateurlApiApply {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingCardActivateurlApi api = new AlipayMarketingCardActivateurlApi();
        AlipayMarketingCardActivateurlApplyModel data = new AlipayMarketingCardActivateurlApplyModel();
        data.setFollowAppId("20150000000000000");
        data.setCallback("https://alipay.com/card/demo.htm");
        data.setOutString("201928393932");
        data.setTemplateId("20170228000000000210102000300974");
        try {
            AlipayMarketingCardActivateurlApplyResponseModel response = api.apply(data);
        } catch (ApiException e) {
            AlipayMarketingCardActivateurlApplyDefaultResponse errorObject = (AlipayMarketingCardActivateurlApplyDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

触发用户领卡

GET

http://sandboxsys.sx.alipaydev.com/prods/mcard/{merchantId}/{appId}?templateId={templateId}&logonId={logonId}&userInfo={userInfo}

{merchantId} 为沙箱分配商家的PID。

{appId}: 为沙箱分配的 APPID。

{templateId} 为前面步骤创建的会员卡模版 ID。

{logonId} 为需要领卡的沙箱账号，如 xxxx@sandbox.com。

{userInfo} 为开卡需要提交的表单信息，由“配置卡模板开卡表单” 的 optional 字段决定。如 [{"OPEN_FORM_FIELD_GENDER":"男"},{"OPEN_FORM_FIELD_MOBILE":"13888888888"},{"OPEN_FORM_FIELD_NAME":"李四"}]，注意传参前需要进行HTTP ENCODE。

开卡成功响应示例：

{
    "stat": "ok",
    "code": "",
    "msg": "",
    "data": "商家会员卡开卡成功"
}

监听开卡结果通知

接收 MsgAPI 消息：alipay.user.opencard.result.notify

消息业务参数示例值：

{
  "external_card_no": "ac301c8a18174ce5acc3ef2ddb7d20e0",
  "user_id": "2088622997219898",
  "success": true,
  "biz_card_no": "2000000000000000002589",
  "template_id": "20230105000000000213105000300098"
}

查询会员卡信息

调用OpenAPI：alipay.marketing.card.query

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingCardApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingCardApiQuery {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingCardApi api = new AlipayMarketingCardApi();
        AlipayMarketingCardQueryModel data = new AlipayMarketingCardQueryModel();
        data.setTargetCardNo("0000001");
        CardUserInfo cardUserInfo = new CardUserInfo();
        cardUserInfo.setUserUniIdType("UID");
        cardUserInfo.setUserUniId("2088302463082075");
        data.setCardUserInfo(cardUserInfo);
        data.setExtInfo("{\"key\":\"value\"}");
        data.setTargetCardNoType("BIZ_CARD");
        try {
            AlipayMarketingCardQueryResponseModel response = api.query(data);
        } catch (ApiException e) {
            AlipayMarketingCardQueryDefaultResponse errorObject = (AlipayMarketingCardQueryDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

出参示例值：

{
    "pass_id":"21942125",
    "schema_url":"alipays://platformapi/startapp?appId=20000021&b=m&p=111",
    "paid_outer_card_info":{
        "action":"OPEN",
        "cycle_info":{
            "alipay_deduct_product_code":"PAID_OUTER_CARD",
            "alipay_deduct_agreement":"20151127000928469118",
            "close_reason":"MANUAL_CLOSE",
            "cycle_type":"YEAR",
            "open_status":"OPEN",
            "alipay_deduct_scene":"PAID_OUTER_CARD"
        },
        "purchase_info":{
            "alipay_trade_no":"2015042321001004720200028594",
            "out_trade_no":"20150320010101001",
            "price":"88.88",
            "action_date":"2021-08-12 12:12:12",
            "source":"ALIPAY_TINY_APP"
        }
    },
    "card_info":{
        "open_date":"2014-02-20 21:20:46",
        "front_text_list":[
            {
                "label":"专业",
                "value":"金融贸易"
            }
        ],
        "external_card_no":"EXT0001",
        "valid_date":"2020-02-20 21:20:46",
        "balance":"124.89",
        "level":"VIP1",
        "mdcode_info":{
            "time_stamp":1496996459,
            "code_value":"1KFCDY0002",
            "expire_time":"2017-06-09 16:25:53",
            "code_status":"SUCCESS"
        },
        "front_image_id":"9fxnkgt0QFmqKAl5V2BqxQAAACMAAQED",
        "biz_card_no":"000001",
        "template_id":"20170308000000000058101000300045",
        "point":"88"
    }
}

更新会员卡信息

调用 OpenAPI：alipay.marketing.card.update

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingCardApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingCardApiUpdate {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingCardApi api = new AlipayMarketingCardApi();
        AlipayMarketingCardUpdateModel data = new AlipayMarketingCardUpdateModel();
        data.setTargetCardNo("000001");
        MerchantCardMsgInfo merchantCardMsgInfo = new MerchantCardMsgInfo();
        merchantCardMsgInfo.setChangedPoint("100.00");
        data.setMerchantCardMsgInfo(merchantCardMsgInfo);
        MerchantCard cardInfo = new MerchantCard();
        cardInfo.setValidDate("2020-02-20 21:20:46");
        List<CardFrontTextDTO> frontTextList = new ArrayList<CardFrontTextDTO>();
        CardFrontTextDTO frontTextList0 = new CardFrontTextDTO();
        frontTextList0.setLabel("专业");
        frontTextList0.setValue("金融贸易");
        frontTextList.add(frontTextList0);
        cardInfo.setFrontTextList(frontTextList);
        cardInfo.setOpenDate("2014-02-20 21:20:46");
        cardInfo.setLevel("VIP1");
        MdCodeInfoDTO mdcodeInfo = new MdCodeInfoDTO();
        mdcodeInfo.setCodeValue("1KFCDY0002");
        mdcodeInfo.setCodeStatus("SUCCESS");
        mdcodeInfo.setTimeStamp(1496996459);
        mdcodeInfo.setExpireTime("2017-06-09 16:25:53");
        cardInfo.setMdcodeInfo(mdcodeInfo);
        cardInfo.setFrontImageId("9fxnkgt0QFmqKAl5V2BqxQAAACMAAQED");
        cardInfo.setBizCardNo("000001");
        cardInfo.setPoint("88");
        cardInfo.setTemplateId("20170308000000000058101000300045");
        cardInfo.setExternalCardNo("EXT0001");
        cardInfo.setBalance("124.89");
        data.setCardInfo(cardInfo);
        List<McardNotifyMessage> notifyMessages = new ArrayList<McardNotifyMessage>();
        McardNotifyMessage notifyMessages0 = new McardNotifyMessage();
        notifyMessages0.setChangeReason("由于你的消费");
        notifyMessages0.setMessageType("OPEN_CARD");
        notifyMessages0.setExtInfo("{\"key\":\"value\"}");
        notifyMessages.add(notifyMessages0);
        data.setNotifyMessages(notifyMessages);
        data.setExtInfo("{\"key\":\"value\"}");
        data.setTargetCardNoType("BIZ_CARD");
        McardStylInfo mcardStyleInfo = new McardStylInfo();
        mcardStyleInfo.setBgColor("rgb(55,112,179)");
        mcardStyleInfo.setLogoId("1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC");
        mcardStyleInfo.setBackgroundId("1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC");
        data.setMcardStyleInfo(mcardStyleInfo);
        data.setOccurTime("2020-12-27 12:12:12");
        PaidOuterCardExtraInfoDTO paidOuterCardInfo = new PaidOuterCardExtraInfoDTO();
        PaidOuterCardCycleInfoDTO cycleInfo = new PaidOuterCardCycleInfoDTO();
        cycleInfo.setCloseReason("MANUAL_CLOSE");
        cycleInfo.setAlipayDeductScene("PAID_OUTER_CARD");
        cycleInfo.setAlipayDeductAgreement("20151127000928469118");
        cycleInfo.setCycleType("YEAR");
        cycleInfo.setAlipayDeductProductCode("PAID_OUTER_CARD");
        cycleInfo.setOpenStatus("OPEN");
        paidOuterCardInfo.setCycleInfo(cycleInfo);
        paidOuterCardInfo.setAction("OPEN");
        PaidOuterCardPurchaseInfoDTO purchaseInfo = new PaidOuterCardPurchaseInfoDTO();
        purchaseInfo.setActionDate("2021-08-12 12:12:12");
        purchaseInfo.setSource("ALIPAY_TINY_APP");
        purchaseInfo.setAlipayTradeNo("2015042321001004720200028594");
        purchaseInfo.setOutTradeNo("20150320010101001");
        purchaseInfo.setPrice("88.88");
        paidOuterCardInfo.setPurchaseInfo(purchaseInfo);
        data.setPaidOuterCardInfo(paidOuterCardInfo);
        try {
            AlipayMarketingCardUpdateResponseModel response = api.update(data);
        } catch (ApiException e) {
            AlipayMarketingCardUpdateDefaultResponse errorObject = (AlipayMarketingCardUpdateDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

出参示例值

{
    "result_code":"isv.update-usercard-fail"
}

删除会员卡信息

调用OpenAPI：alipay.marketing.card.delete

package com.java.sdk.demo;

import com.alipay.v3.ApiException;
import com.alipay.v3.ApiClient;
import com.alipay.v3.util.model.AlipayConfig;
import com.alipay.v3.Configuration;
import com.alipay.v3.api.AlipayMarketingCardApi;
import com.alipay.v3.model.*;
import java.io.File;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class AlipayMarketingCardApiDelete {

    public static void main(String[] args) throws ApiException {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // 初始化alipay参数（全局设置一次）
        AlipayConfig alipayConfig = new AlipayConfig();
        alipayConfig.setServerUrl("https://openapi.alipay.com");
        alipayConfig.setAppId("<-- 请填写您的AppId，例如：2019091767145019 -->");
        alipayConfig.setPrivateKey("<-- 请填写您的应用私钥，例如：MIIEvQIBADANB ... ... -->");
        alipayConfig.setAlipayPublicKey("<-- 请填写您的支付宝公钥，例如：MIIBIjANBg... -->");
        defaultClient.setAlipayConfig(alipayConfig);
        AlipayMarketingCardApi api = new AlipayMarketingCardApi();
        String outSerialNo = "2016062700001";
        String targetCardNo = "0000001";
        String targetCardNoType = "BIZ_CARD";
        String reasonCode = "USER_UNBUND";
        String extInfo = "{\"new_card_no\":\"12345\",\" donee_user_id\":\"2088102130652460\"}";
        try {
            AlipayMarketingCardDeleteResponseModel response = api.delete(outSerialNo, targetCardNo, targetCardNoType, reasonCode, extInfo);
        } catch (ApiException e) {
            AlipayMarketingCardDeleteDefaultResponse errorObject = (AlipayMarketingCardDeleteDefaultResponse) e.getErrorObject();
            System.out.println("调用失败:" + errorObject);
        }
    }
}

出参示例值：

{
    "biz_serial_no":"2016062700001"
}

沙箱调试

商家会员卡沙箱调试说明#

业务用例#

配置会员卡模板#

上传卡模板图片文件#

创建会员卡模板#

配置卡模板开卡表单#

修改会员卡模板#

查询会员卡模板#

会员卡管理#

实现获取会员卡 SPI 接口#

触发用户开卡#

监听开卡结果通知#

查询会员卡信息#

更新会员卡信息#

删除会员卡信息#

商家会员卡沙箱调试说明

业务用例

配置会员卡模板

上传卡模板图片文件

创建会员卡模板

配置卡模板开卡表单

修改会员卡模板

查询会员卡模板

会员卡管理

实现获取会员卡 SPI 接口

触发用户开卡

监听开卡结果通知

查询会员卡信息

更新会员卡信息

删除会员卡信息