Alipay, China's leading third-party online payment solutionAlipay, China's leading third-party online payment solutionDOCS

      alipay.marketing.card.query

      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: 

      1. Return this field when the membership card is issued successfully. Save the value for future use.
      2. 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:

      1. If the card type is merchant membership card, this field is required.
      2. 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"
      }