alipay.marketing.card.query

2021-02-26 07:01

Use this interface to query for membership card information with the card number or cardholder information.

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

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

Example:2014072300007148

method

String (128) Required

The interface name

Example:alipay.marketing.card.query

format

String (40)

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

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

target_card_no_type

String (64) Required

The type of the card number. Only Alipay provided card number can be queried. Possible values are:

BIZ_CARD: indicates a card number that is assigned by Alipay.
D_QR_CODE: dynamic QR code
D_BAR_CODE: dynamic bar code

Example:BIZ_CARD

target_card_no

String (32) Required

The card number.

If target_card_no_type is BIZ_CARD, the value of this field is the card number assigned by Alipay, which is identical to biz_card_no in the response of alipay.marketing.card.open.
If target_card_no_type is D_QR_CODE or D_BAR_CODE, the value of this field is the dynamic code value.

Example:000001

card_user_info

CardUserInfo

The information of the user that the membership card is issued to. See card_user_info for details.

ext_info

String (1024)

Extended information

card_user_info

Parameter

Description

user_uni_id

String (32) Required

The unique ID of the user. The value is based on user_uni_id_type. Currently only Alipay user ID is supported. The Alipay user ID begins with 2088 and consists of 16 digits.

Example:2088302463082075

user_uni_id_type

String (32) Required

ID type. The value is UID.

Example:UID

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_info

MerchantCardRequired

The membership card information. See card_info for details.

schema_url

String (64)

Required

The schema URL of the Alipay card page to be redirected to, from the membership card page.

Example:alipays://platformapi/startapp?appId=20000021&b=m&p=111

pass_id

String (32)

The pass ID for redirecting to Alipay card page from the membership card page, which corresponds to the p parameter of the schema URL.

Example:21942125

card_info

Parameter

Description

biz_card_no

String (32)

The card number that is assigned by Alipay

Note:

Return this field when the membership card is issued successfully. Save the value for future use.
This field is not required in the interfaces of card issuing, card update, card deletion, and card query.

Example:000001

external_card_no

String (64)

The merchant membership card number

Note:

If the card type is merchant membership card, this field is required.
This field is not required in the interfaces of card update, card deletion, and card query.

Example:EXT0001

open_date

Date (32) Required

The time when the membership card is issued. The format is yyyy-MM-dd HH:mm:ss. When using the card update interface to update the membership card, the value of open_date is same as the value of this field and cannot be modified.

Example:2014-02-20 21:20:46

valid_date

String (32) Required

The time when the membership card is expired. The format is yyyy-MM-dd HH:mm:ss. When using the card update interface to update the membership card, the value of valid_date is same as the value of this field and cannot be modified.

Example:2020-02-20 21:20:46

level

String (64)

Membership card level. The levels are customized by the merchant and can be defined in the template creation interface.

Example:VIP1

point

String (64)

Membership card points. The value must be a number. Float with two decimal places are supported.

Example:88

balance

String (64)

Membership card balance. The currency unit is Yuan and the amount is of two decimal places accuracy.

Example:124.89

template_id

String (32)

The ID that is assigned by Alipay to identify a membership card template. This field is used when the merchant updates templates for different membership card levels in the card update interface.

Example:20170308000000000058101000300045

mdcode_info

MdCodeInfoDTO (1024)

Information of the dynamic code that is issued by the merchant. When the value of write_off_type is mdbarcode or mdqrcode, the merchant uses the card update interface to issue the dynamic code. If the merchant dynamic code is required, contact Alipay Technical Support for related documents. For more information, see mdcode_info.

front_text_list

CardFrontTextDTO[](1024)

The text list on the membership card. One line contains one item, consisting of label on the left and value on the right. The text list cannot exceed four lines. For more information, see front_text_list.

front_image_id
String (1024)

The ID of the membership card image. The merchant uses the alipay.offline.material.image.upload interface to upload images. The uploaded image must conform to the following image specifications:

The file must be within 1 M; the file format must be BMP, PNG, JPEG, JPG, or GIF; the image must be 230 * 295 pixels. The image can be scaled up.

Example:9fxnkgt0QFmqKAl5V2BqxQAAACMAAQED

mdcode_info

Parameter

Description

code_status

String (14) Required

The status of issuing the dynamic code. Possible values are:

SUCCESS: The code is issued successfully.
FAIL_RETRY: The code is failed to be issued. Alipay informs the merchant to issue the code again.
FAIL_NOT_RETRY: The code is failed to be issued. Alipay does not inform the merchant to issue the code again.

Example:SUCCESS

code_value

String (128)

The code value. This field is required when the value of code_status is SUCCESS. The barcode or QR code generated based on the code value is used for redemption.

Example:1KFCDY0002

expire_time

Date (19)

The time when the current dynamic code is expired. This field is required when the value of code_status is SUCCESS.

Example:2017-06-09 16:25:53

time_stamp

Number (20) Required

The time when the merchant issues the dynamic code. Use long in Java to identify different requests for issuing the dynamic code.

Example:1496996459

front_text_list

Parameter

Description

label

String (4)

Label of the text

Example:Major

value

String (32)

Value of the text

Example:Finance and trading

Error codes

Returned result	Description	Solution
INVALID_PARAMETER	Incorrect parameters	Check the problem according to the message.
SYSTEM_ERROR	Alipay system error	Try again.
CARD_NOT_EXIT	The membership card does not exist.	Check the card information.
NO_CARD_TYPE	The card type is not defined.	Use the correct card type.

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");
AlipayMarketingCardQueryRequest request = new AlipayMarketingCardQueryRequest();
request.setBizContent("{" +
"\"target_card_no_type\":\"BIZ_CARD\"," +
"\"target_card_no\":\"0000001\"," +
"\"card_user_info\":{" +
"\"user_uni_id\":\"2088302463082075\"," +
"\"user_uni_id_type\":\"UID\"" +
"    }," +
"\"ext_info\":\"\\\"\\\"\"" +
"  }");
AlipayMarketingCardQueryResponse response = alipayClient.execute(request);
if(response.isSuccess()){
System.out.println("The calling is successful.");
} else {
System.out.println("The calling is failed.");
}

.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);
AlipayMarketingCardQueryRequest  request= new AlipayMarketingCardQueryRequest() ;
request.BizContent="{" +
"\"target_card_no_type\":\"BIZ_CARD\"," +
"\"target_card_no\":\"0000001\"," +
"\"card_user_info\":{" +
"\"user_uni_id\":\"2088302463082075\"," +
"\"user_uni_id_type\":\"UID\"" +
"    }," +
"\"ext_info\":\"\\\"\\\"\"" +
"  }";
AlipayMarketingCardQueryResponse 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 AlipayMarketingCardQueryRequest ();
$request->setBizContent("{" .
"\"target_card_no_type\":\"BIZ_CARD\"," .
"\"target_card_no\":\"0000001\"," .
"\"card_user_info\":{" .
"\"user_uni_id\":\"2088302463082075\"," .
"\"user_uni_id_type\":\"UID\"" .
"    }," .
"\"ext_info\":\"\\\"\\\"\"" .
"  }");
$result = $aop->execute ( $request); 

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

HTTP request source code

copy

https://openapi.alipay.com/gateway.do?timestamp=2013-01-01 08:08:08&method=alipay.marketing.card.query&app_id=5647&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&charset=GBK&biz_content=
  {
"target_card_no_type":"BIZ_CARD",
"target_card_no":"0000001",
"card_user_info":{
"user_uni_id":"2088302463082075",
"user_uni_id_type":"UID"
    },
"ext_info":"\"\""
  }

Response sample

JSON

copy

{
    "alipay_marketing_card_query_response": {
        "code": "10000",
        "msg": "Success",
        "card_info": {
            "biz_card_no": "000001",
            "external_card_no": "EXT0001",
            "open_date": "2014-02-20 21:20:46",
            "valid_date": "2020-02-20 21:20:46",
            "level": "VIP1",
            "point": "88",
            "balance": "124.89",
            "template_id": "20170308000000000058101000300045",
            "mdcode_info": {
                "code_status": "SUCCESS",
                "code_value": "1KFCDY0002",
                "expire_time": "2017-06-09 16:25:53",
                "time_stamp": 1496996459
            },
            "front_text_list": [
                {
                    "label": "Major",
                    "value": "Finance and trading"
                }
            ],
            "front_image_id": "9fxnkgt0QFmqKAl5V2BqxQAAACMAAQED"
        },
        "schema_url": "alipays://platformapi/startapp?appId=20000021&b=m&p=111",
        "pass_id": "21942125"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}

XML

copy

<alipay_marketing_card_query_response>
<code>10000</code>
<msg>Success</msg>  <card_info>
    <biz_card_no>000001</biz_card_no>
    <external_card_no>EXT0001</external_card_no>
    <open_date>2014-02-20 21:20:46</open_date>
    <valid_date>2020-02-20 21:20:46</valid_date>
    <level>VIP1</level>
    <point>88</point>
    <balance>124.89</balance>
    <template_id>20170308000000000058101000300045</template_id>
    <mdcode_info>
      <code_status>SUCCESS</code_status>
      <code_value>1KFCDY0002</code_value>
      <expire_time>2017-06-09 16:25:53</expire_time>
      <time_stamp>1496996459</time_stamp>
    </mdcode_info>
    <front_text_list list="true">
      <card_front_text_d_t_o>
        <label>Major</label>
        <value>Finance and trading</value>
      </card_front_text_d_t_o>
    </front_text_list>
    <front_image_id>9fxnkgt0QFmqKAl5V2BqxQAAACMAAQED</front_image_id>
  </card_info>
  <schema_url>alipays://platformapi/startapp?appId=20000021&b=m&p=111</schema_url>
  <pass_id>21942125</pass_id>
</alipay_marketing_card_query_response>

Exception sample

JSON

copy

{
    "alipay_marketing_card_query_response": {
        "code": "20000",
        "msg": "Service Currently Unavailable",
        "sub_code": "isp.unknow-error",
        "sub_msg": "The system is busy."
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}