alipay.marketing.card.template.query

2020-10-16 11:40

Use this interface to query membership card templates

#Request

#Service address

Environment	HTTPS request URL
Production environment	https://openapi.alipay.com/gateway.do

#Request parameters

Parameter

Description

Basic parameter

app_id

String (32) Required

A unique ID that is assigned by Alipay to identify an app

Example:2014072300007148

method

String (128) Required

The interface name

Example:alipay.marketing.card.formtemplate.set

format

String (40)

Request format. Only JSON is supported.

Example:JSON

charset

String (10) Required

The charset with which the request data are encoded. UTF-8, GBK, and GB2312 are supported.

Example:UTF-8

sign_type

String (10) Required

The signature algorithm used by the merchant to generate the pre-sign string. RSA and RSA2 are supported. RSA2 is preferred.

Example:RSA2

sign

String (344) Required

The signature value. See Signature for details.

Example:See Request sample for details

timestamp

String (19) Required

The time when the request is sent. The format is yyyy-MM-dd HH:mm:ss.

Example:2014-07-24 03:07:50

version

String (3) Required

The interface version. The value is fixed as 1.0.

Example:1.0

biz_content

String Required

Collection of request parameters. The maximum length is not limited. Except for common parameters, all other request parameters must be passed to this parameter.

Business parameter

template_id

String (32) Required

The unique ID assigned by Alipay to identify a membership card template. This parameter is obtained from the template creation interface.

Example:201607180000001

#Response

Parameter

Description

Basic parameter

code

String Required

Gateway return code, which indicates whether the request is accepted by Alipay gateway.

Example:40004

msg

String Required

Description of the gateway return code

Example:Business Failed

sub_code

String

Processing result of the request

Example:ACQ.TRADE_HAS_SUCCESS

sub_msg

String

Description of the processing result of the request

Example:Payment for the transaction is completed.

sign

String Required

The signature value. See Signature for details.

Example:DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo=

Business parameter

card_type

String (32) Required

Card type. The value is fixed as OUT_MEMBER_CARD.

Example:OUT_MEMBER_CARD

biz_no_prefix

String (10)

Prefix of the membership card number. A card number consists of biz_no_prefix and biz_no_suffix. biz_no_prefix is generated by the merchant and biz_no_suffix is generated in real time.

biz_no_suffix_len

String (2) Required

Length of the card number suffix. The value ranges from 8 to 32, and cannot be changed after being assigned to a template. A card number consists of biz_no_prefix and biz_no_suffix and the maximum length is 32. Therefore, the value of biz_no_suffix_len must not exceed the difference of 32 minus the length of biz_no_prefix.

Example:10

template_style_info

TemplateStyleInfoDTO Required

Template style information. For more information, see template_style_info.

template_benefit_info

TemplateBenefitInfoDTO

Membership card privileges. The information in this parameter is displayed in the "Member benefits" module on the membership card page. For more information, see template_benefit_info.

column_info_list

TemplateColumnInfoDTO Required

Information about modules that are to be displayed on the membership card. For more information, see column_info_list.

field_rule_list

TemplateFieldRuleDTO Required

List of rules about the membership card fields information.

For example, if the card validity period is two years since issuance, then rule_name = DATE_IN_FUTURE.

For more information, see field_rule_list.

service_label_list

String (1024)

List of the service labels

Example:Checklater

open_card_conf

TemplateOpenCardConfDTO

Used to configure information about issuing the membership card. For more information, see open_card_conf.

card_action_list

TemplateActionInfoDTO

List of card action points. An action point is the clickable area on the card. A card can have up to four action points. Duplicated action points are not displayed. For more information, see card_action_list.

card_level_confs

TemplateCardLevelConfDTO

Used to configure the card level. For more information, see card_level_confs.

mdcode_notify_conf

TemplateMdcodeNotifyConfDTO

Used to configure related information needed for notifying merchants to generate dynamic QR code when the customer uses the membership card.

This parameter specifies the notification data that are sent to the merchant when the user opens the electronic membership card.

Note: This field is required when the value of write_off_typeis mdbarcode or mdqrcode. For more information, see mdcode_notify_conf.

card_spec_tag

String (20)

Special tag of the card, which is used only for certain situations. Usually can be ignored.

#template_style_info

Parameter

Description

card_show_name

String (10) Required

Card name displayed in the wallet.

Example: Huabei Joint Card

logo_id

String (1000) Required

ID of the logo image obtained after using alipay.offline.material.image.upload to upload the image. The image must conform to the following standards:

Maximum file size: 1 MB.
Format: BMP, PNG, JPEG, JPG, and GIF.
Image size: Square shape with at least 500*500 pixels.
Merchant's logo is preferred.

Example:1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC

background_id

String (1000) Required

ID of the background image obtained after using alipay.offline.material.image.upload to upload the image. The image must conform to the following standards:

Max file size: 2 MB.
Format: BMP, PNG, JPEG, JPG, and GIF.
Image size: At least 1020*643 pixels.
The image cannot be morphed or have round corners.

Example:1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC

bg_color

String (32) Required

Font color. Only applies to texts in the card details information.

Example:rgb(55,112,179)

front_text_list_enable

Boolean (5)

This parameter decides whether texts are to be displayed in the card front. The default value is false, which means the text is not to be displayed. Texts consist of label and value, and are defined when creating or updating the card. Texts are to be displayed in lines and at most four lines are supported.

Example:false

front_image_enable

Boolean (5)

This parameter decides whether the ID photo is to be displayed in the card front. The default value is false, which means the image is not to be displayed. The image ID is obtained when creating or updating the card.

Example:false

feature_descriptions

String (4000)

Information about the card features that can be previewed by the user when issuing the card.

Example:Fee-free installment with Huabei card.

slogan

String (100)

Slogan

Example:Membership privileges incoming

slogan_img_id

String (100)

ID of the slogan image obtained after using alipay.offline.material.image.upload to upload the image.

Example:1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC

brand_name

String (100)

Brand name

Example:Alipay

banner_img_id

String (1000)

ID of the banner image obtained after using alipay.offline.material.image.upload to upload the image.

Example:1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC

banner_url

String (256)

Redirection address of the banner.

Example:http://www.Alipay.com

column_info_layout

String (10)

Module information layout. Possible values are:

list: list style layout
grid: grid style layout

If empty, the default value is list.

Example:list

#template_benefit_info

Parameter

Description

title

String (16) Required

Benefit title

Example:Every deal discounted

benefit_desc

String (1000) Required

Benefit description

Example:Every deal discounted

start_date

String (64) Required

Start time of the benefit

Example:2016-07-18 15:17:23

end_date

String (64) Required

End time of the benefit

Example:2016-07-34 12:12:12

#column_info_list

Parameter

Description

code

String (32) Required

Module code, including standard module codes and customized module code:

Standard module codes are specified by Alipay and include the following code values:

BALANCE: Balance in the membership card.
POINT: Point.
LEVEL: Card level
TELEPHONE: Phone number

Customized module codes are specified by merchants to display customized functions and features. Duplicated module codes are not allowed.

Example:BENEFIT_INFO

operate_type (32)

Module operation type. Possible values:

openNative: indicates that the module is with a subpage that can be opened to show the information specified by descs of the more_info field.
openWeb: indicates that the module is with a URL that can be opened.
staticinfo: indicates that the module shows information in static text.

Notes:

If this field is not specified, the default value is staticinfo.
Use staticinfo for standard modules.

Example:openWeb

title

String (16) Required

Module title

Example:Member exculsive

value

String (16)

Value of the module code. For example, the value of BALANCE.

Example:80

more_info

MoreInfoDTO (2048)

Additional information about the module. For more information, see more_info.

icon_id

String (1000)

If the value of template_style_info.column_info_layout is grid, this parameter is the icon ID of the grid. The icon ID is obtained after uploaded the image using alipay.offline.material.image.upload.

Example:1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC

tag

String (3)

If the value of template_style_info.column_info_layout is grid, this parameter is the tag of the grid.

Example:Hot

#more_info

Parameter

Description

title

String (16) Required

Subpage title of the openNative module. This field is valid only when the value of operate_type is openNative.

Example:Member exclusive privilege

url

String (256)

URL address of the openweb module. This field is required when the value of operate_type is openweb.

Example:www.alipay.com

params

String (1024)

Extended parameter, which must contain the value in URL. Format: JSON. This field is required when the value of operate_type is openweb.

descs

String[] (1000)

Descriptions to be shown on the subpage of the openNative module. This field is required when the value of operate_type is openNative.

Example:You have 30% off on your birthday

#field_rule_list

Parameter

Description

field_name

String (64) Required

Field names. Possible values:

Balance: the balance
Point: the points, with a type of integer
Level: the level, with a type of string.
OpenDate: the date when the card is issued
ValidDate: the date when the card expires

Example:Balance

rule_name

String (64) Required

Rule name. Possible values:

ASSIGN_FROM_REQUEST: use the value of rule_value as the key, which indicates that values of fields are to be obtained from card_info of the alipay.marketing.card.open interface.
DATE_IN_FUTURE: a date in the future will be generated, in the format of YYYY-MM-DD. To use this parameter, the value of field_name must be OpenDate or ValidDate, with a value of 10m or 10d (10m means 10 months and 10d means 10 days).
CONST: a constant value that is assigned when the card template is created. Use the value of rule_value.

Example:ASSIGN_FROM_REQUEST

rule_value

String (512) Required

The value of this field depends on the rule_name field.

If rule_name is CONST, the value of rule_value is used directly as the card information.

If rule_name is DATE_IN_FUTURE, the value is 10m or 10d.

If rule_name is ASSIGN_FROM_REQUEST, the value is obtained from the alipay.marketing.card.open interface.

Example:Balance

#open_card_conf

Parameter

Description

open_card_source_type

String (20) Required

The party that issues the membership card. Possible values are:

ISV: independent software vendor
MER: merchant

Example:ISV

source_app_id

String (32) Required

App ID of the service provider that provides the card issuance page.

Example:201609191111111

open_card_url

String (256) Required

Card issuing link, which starts with http or https.

Example:https://www.alipay.com

conf

String (4000)

Reserved parameter for future use

card_rights

TemplateRightsContentDTO (3)

Card privilege information. For more information, see card_rights.

#card_rights

Parameter

Description

title

String (10) Required

Privilege title

Example:Gifts for points

detail

String (20)

Privilege details

Example:Check your points anytime and redeem gifts

#card_action_list

Parameter

Description

code

String (32) Required

Code of the card action point. Customized by the merchant.

Example:TO_CLOCK_IN

text

String (6) Required

Texts displayed at the card action point.

Example:Clock in

url

String (1024)

Action point redirection URL, which is an HTTP(S) address or Alipay schema address of the action point. This field is required when url_type is url or empty.

Example:https://merchant.ali.com/ee/clock_in.do

#card_level_confs

Parameter

Description

level

String (64) Required

Membership level. Must be consistent with the value of level in alipay.marketing.card.open.

Example:VIP1

level_show_name

String (64) Required

Displayed name of the membership level.

Example:Gold

level_icon

String (64) Required

ID of membership level icon image. Use the image that is uploaded by using alipay.offline.material.image.upload.

Example:1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC

level_desc

String (4000) Required

Membership level description.

Example:Free parking for Gold members

#mdcode_notify_conf

Parameter

Description

url

String (1024) Required

URL used to receive the code issuing notification. Use HTTPS URLs. When a member opens the electronic card, Alipay sends a POST request to this URL to notify the merhcant to generate a code.

Example:https://www.ali123.com/ant/mdcode

ext_params

String (1024)

Extended parameters, which is in a "key":value" format.

The POST request that is sent by Alipay to the address specified by url are including all the parameters in ext_params.

Example:{"param1":"value1","param2":"value2"}

#Business error code

Error code	Description	Solution
INVALID_PARAMETER	The parameters are invalid.	Use correct request parameters and try again.
SYSTEM_ERROR	System error	Try again later.
TEMPLATE_NOT_EXIT	The template does not exist.	Check whether the template ID is correct.

#Sample

#Request sample

JAVA

copy

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");
AlipayMarketingCardTemplateQueryRequest request = new AlipayMarketingCardTemplateQueryRequest();
request.setBizContent("{" +
"\"template_id\":\"20160718000000001\"" +
"  }");
AlipayMarketingCardTemplateQueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("Call succeeds");
} else {
System.out.println("Call fails");
}

.NET

copy

IAopClient client = new DefaultAopClient("https://openapi.alipay.com/gateway.do", "app_id", "merchant_private_key", "json", "1.0", "RSA2", "alipay_public_key", "GBK", false);
AlipayMarketingCardTemplateQueryRequest  request= new AlipayMarketingCardTemplateQueryRequest() ;
request.BizContent="{" +
"\"template_id\":\"20160718000000001\"" +
"  }";
AlipayMarketingCardTemplateQueryResponse response=client.execute(request);
Console.WriteLine(response.Body);

PHP

copy

$aop = new AopClient ();
$aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do';
$aop->appId = 'your app_id';
$aop->rsaPrivateKey = 'Please fill in the developer's private key in a line of string, removing the head, tail, and carriage return';
$aop->alipayrsaPublicKey='Please fill in Alipay public key in a line of string';
$aop->apiVersion = '1.0';
$aop->signType = 'RSA2';
$aop->postCharset='GBK';
$aop->format='json';
$request = new AlipayMarketingCardTemplateQueryRequest ();
$request->setBizContent("{" .
"\"template_id\":\"20160718000000001\"" .
"  }");
$result = $aop->execute ( $request); 

$responseNode = str_replace(".", "_", $request->getApiMethodName()) . "_response";
$resultCode = $result->$responseNode->code;
if(!empty($resultCode)&&$resultCode == 10000){
echo "Succeeded";
} else {
echo "Failed";
}

HTTP request source code

copy

https://openapi.alipay.com/gateway.do?timestamp=2013-01-01 08:08:08&method=alipay.marketing.card.template.query&app_id=4798&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&charset=GBK&biz_content=
  {
"template_id":"20160718000000001"
  }

//To ensure a secure communication, verify whether the sign value in the response sample is provided by Ant Financial.

#Response sample

JSON

copy

{
    "alipay_marketing_card_template_query_response": {
        "code": "10000",
        "msg": "Success",
        "card_type": "OUT_MEMBER_CARD",
        "biz_no_prefix": "prex",
        "biz_no_suffix_len": "10",
        "template_style_info": {
            "card_show_name": "Huabei Joint Card",
            "logo_id": "1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
            "color": "rgb(55,112,179)",
            "background_id": "1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
            "bg_color": "rgb(55,112,179)",
            "front_text_list_enable": false,
            "front_image_enable": false,
            "feature_descriptions": [
                "With the Huabei Card, you can enjoy free installments"
            ],
            "slogan": "Benefits more than you can imagine.",
            "slogan_img_id": "1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
            "brand_name": "Coca Cola",
            "banner_img_id": "1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
            "banner_url": "http://www.baidu.com",
            "column_info_layout": "list"
        },
        "template_benefit_info": [
            {
                "title": "Discount for every purchase",
                "benefit_desc": [
                    "Discount for every purchase"
                ],
                "start_date": "2016-07-18 15:17:23",
                "end_date": "2016-07-34 12:12:12"
            }
        ],
        "column_info_list": [
            {
                "code": "BENEFIT_INFO",
                "operate_type": "openWeb",
                "title": "Only for members",
                "value": "80",
                "more_info": {
                    "title": "Member benefits",
                    "url": "http://www.baidu.com",
                    "params": "{}",
                    "descs": [
                        "30% off on your birthday"
                    ]
                },
                "icon_id": "1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
                "tag": "Popular",
                "group_title": "School helper"
            }
        ],
        "field_rule_list": [
            {
                "field_name": "Balance",
                "rule_name": "ASSIGN_FROM_REQUEST",
                "rule_value": "Balance"
            }
        ],
        "service_label_list": [
            "Checklater"
        ],
        "shop_ids": [
            "[\"2015122900077000000002409504\"]"
        ],
        "open_card_conf": {
            "open_card_source_type": "ISV",
            "source_app_id": "201609191111111",
            "open_card_url": "https://www.alipay.com",
            "conf": "\"\"",
            "card_rights": [
                {
                    "title": "Points for gifts",
                    "detail": "Check your points anytime，use your points for gifts"
                }
            ]
        },
        "pub_channels": [
            {
                "pub_channel": "SHOP_DETAIL",
                "ext_info": "\"key\":\"value\""
            }
        ],
        "card_action_list": [
            {
                "code": "TO_CLOCK_IN",
                "text": "Clock in",
                "url": "https://merchant.ali.com/ee/clock_in.do"
            }
        ],
        "card_level_confs": [
            {
                "level": "VIP1",
                "level_show_name": "Golden member",
                "level_icon": "1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
                "level_desc": "Free parking for golden members"
            }
        ],
        "mdcode_notify_conf": {
            "url": "https://www.ali123.com/ant/mdcode",
            "ext_params": "{\"param1\":\"value1\",\"param2\":\"value2\"}"
        },
        "card_spec_tag": "NONE"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

XML

copy

<alipay_marketing_card_template_query_response>
<code>10000</code>
<msg>Success</msg>  <card_type>OUT_MEMBER_CARD</card_type>
  <biz_no_prefix>prex</biz_no_prefix>
  <biz_no_suffix_len>10</biz_no_suffix_len>
  <template_style_info>
    <card_show_name>Huabei Joint Card</card_show_name>
    <logo_id>1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC</logo_id>
    <color>rgb(55,112,179)</color>
    <background_id>1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC</background_id>
    <bg_color>rgb(55,112,179)</bg_color>
    <front_text_list_enable>false</front_text_list_enable>
    <front_image_enable>false</front_image_enable>
    <feature_descriptions list="true">
      <string>With the Huabei Card, you can enjoy free installments</string>
    </feature_descriptions>
    <slogan>Benefits more than you can imagine</slogan>
    <slogan_img_id>1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC</slogan_img_id>
    <brand_name>可乐</brand_name>
    <banner_img_id>1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC</banner_img_id>
    <banner_url>http://www.baidu.com</banner_url>
    <column_info_layout>list</column_info_layout>
  </template_style_info>
  <template_benefit_info list="true">
    <template_benefit_info_d_t_o>
      <title>Discount for every purchase</title>
      <benefit_desc list="true">
        <string>Discount for every purchase</string>
      </benefit_desc>
      <start_date>2016-07-18 15:17:23</start_date>
      <end_date>2016-07-34 12:12:12</end_date>
    </template_benefit_info_d_t_o>
  </template_benefit_info>
  <column_info_list list="true">
    <template_column_info_d_t_o>
      <code>BENEFIT_INFO</code>
      <operate_type>openWeb</operate_type>
      <title>Only for members</title>
      <value>80</value>
      <more_info>
        <title>Member benefits</title>
        <url>http://www.baidu.com</url>
        <params>{}</params>
        <descs list="true">
          <string>30% off on your birthday</string>
        </descs>
      </more_info>
      <icon_id>1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC</icon_id>
      <tag>Popular</tag>
      <group_title>School helper</group_title>
    </template_column_info_d_t_o>
  </column_info_list>
  <field_rule_list list="true">
    <template_field_rule_d_t_o>
      <field_name>Balance</field_name>
      <rule_name>ASSIGN_FROM_REQUEST</rule_name>
      <rule_value>Balance</rule_value>
    </template_field_rule_d_t_o>
  </field_rule_list>
  <service_label_list list="true">
    <string>Checklater</string>
  </service_label_list>
  <shop_ids list="true">
    <string>["2015122900077000000002409504"]</string>
  </shop_ids>
  <open_card_conf>
    <open_card_source_type>ISV</open_card_source_type>
    <source_app_id>201609191111111</source_app_id>
    <open_card_url>https://www.alipay.com</open_card_url>
    <conf>""</conf>
    <card_rights list="true">
      <template_rights_content_d_t_o>
        <title>Points for gifts</title>
        <detail>Check your points anytime，use your points for gifts</detail>
      </template_rights_content_d_t_o>
    </card_rights>
  </open_card_conf>
  <pub_channels list="true">
    <pub_channel_d_t_o>
      <pub_channel>SHOP_DETAIL</pub_channel>
      <ext_info>"key":"value"</ext_info>
    </pub_channel_d_t_o>
  </pub_channels>
  <card_action_list list="true">
    <template_action_info_d_t_o>
      <code>TO_CLOCK_IN</code>
      <text>打卡</text>
      <url>https://merchant.ali.com/ee/clock_in.do</url>
    </template_action_info_d_t_o>
  </card_action_list>
  <card_level_confs list="true">
    <template_card_level_conf_d_t_o>
      <level>VIP1</level>
      <level_show_name>Golden member</level_show_name>
      <level_icon>1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC</level_icon>
      <level_desc>Free parking for golden members</level_desc>
    </template_card_level_conf_d_t_o>
  </card_level_confs>
  <mdcode_notify_conf>
    <url>https://www.ali123.com/ant/mdcode</url>
    <ext_params>{"param1":"value1","param2":"value2"}</ext_params>
  </mdcode_notify_conf>
  <card_spec_tag>NONE</card_spec_tag>
</alipay_marketing_card_template_query_response>

#

#Exception sample

JSON

copy

{
    "alipay_marketing_card_template_query_response": {
        "code": "20000",
        "msg": "Service Currently Unavailable",
        "sub_code": "isp.unknow-error",
        "sub_msg": "System busy"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}