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

      alipay.marketing.card.open

      Use this interface to issue membership cards.


      #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.formtemplate.set

      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 sign value. See Signature for details.

      Example:2118ac8fad6bc1d9e88a6cd017c18d37

      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 in to this parameter.

      Business parameter

      out_serial_no

      String (64) Required

      The unique serial number that is assigned by the merchant to identify a request

      Example:201606270000001

      card_template_id

      String (32) Required

      The ID that is assigned by Alipay to identify a membership card template. The value is the same as that of template_id returned by Alipay in the template creation interface. 

      Example:201606270000001

      card_user_info

      CardUserInfo Required

      Information about the user that the membership card is issued to. See card_user_info for details.

      card_ext_info

      MerchantCard Required

      The membership card information. See card_ext_info for details.

      member_ext_info

      MerchantMenber

      The member information. See member_ext_info for details.


      #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. Only Alipay user ID is supported. The Alipay user ID consists of 16 digits.

      Example:2088302463082075

      user_uni_id_type

      String (32) Required

      ID type. The value is UID.

      Example:UID


      #card_ext_info

      Parameter

      Description

      biz_card_no

      String (32) 

      The membership card number that is assigned by Alipay

      Note: 

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

      Example:000001

      external_card_no

      String (64) 

      The membership card number that is assigned by the merchant

      Note:

      1. If the card type is OUT_MEMBER_CARD, this field is required in the request of card issuance interface.
      2. This field is not required in the request of card update, card deletion, and card query interfaces.

      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 this field is the same as that of this field in the card issuance interface.

      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. Floats with two decimal places are supported.

      Example:88

      balance

      String (64)

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

      Example:124.89

      template_id

      String (32)

      The ID that is assigned by Alipay to identify a membership card template. This field is used only 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 assigned by the merchant to identify a membership card. When the value of write_off_type is mdbarcode or mdqrcode, the merchant uses the card update interface to issue the dynamic code. To use the merchant dynamic code, contact Alipay Technical Support. See mdcode_info for details.

      front_text_list

      CardFrontTextDTO[](1024)

      The list of text that are to be shown on the membership card. One line contains one item, consisting of label on the left and value on the right. At most, four lines can be supported. See front_text_list for details.

      front_image_id
      String (1024)

      The ID of the membership card image. The merchant uses the alipay.offline.material.image.upload interface to upload the image. 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 proportionally.

      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 in long type, which can be used for identifying 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


      #member_ext_info

      Parameter

      Description

      name

      String (64) 

      Name

      Example:Lee

      gende

      String (32)

      Gender. Possible values are MALE and FEMALE.

      Example:MALE

      birth

      String (32) 

      Birthday. The format is yyyy-MM-dd.

      Example:2016-06-27

      cell

      String (32) 

      Mobile phone number

      Example:13000000000


      #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.


      #card_info

      Parameter

      Description

      biz_card_no

      String (32)

      The membership 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 request of card issuing, card update, card deletion, and card query interfaces.

      Example:000001

      external_card_no

      String (64)

      The membership card number that is assigned by the merchant

      Note:

      1. If the card type is OUT_MEMBER_CARD, this field is required.
      2. This field is not required in the request of card update, card deletion, and card query interfaces.

      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 this field is the same as that of the card issuance interface 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 this field is the same as that of the card issuance interface 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. Floats with two decimal places are supported.

      Example:88

      balance

      String (64)

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

      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. To use the merchant dynamic code, contact Alipay Technical Support. See mdcode_info for details.

      front_text_list

      CardFrontTextDTO[](1024)

      The list of textthat are to be shown on the membership card. One line contains one item, consisting of label on the left and value on the right. At most, four lines can be supported. See front_text_list for details.

      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 proportionally.

      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.

      TEMPLATE_NOT_EXIT

      The membership card template does not exist.

      Check the template.

      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");
AlipayMarketingCardOpenRequest request = new AlipayMarketingCardOpenRequest();
request.setBizContent("{" +
"\"out_serial_no\":\"201606270000001\"," +
"\"card_template_id\":\"201606270000001\"," +
"\"card_user_info\":{" +
"\"user_uni_id\":\"2088302463082075\"," +
"\"user_uni_id_type\":\"UID\"" +
"    }," +
"\"card_ext_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\"" +
"    }," +
"\"member_ext_info\":{" +
"\"name\":\"Lee\"," +
"\"gende\":\"MALE\"," +
"\"birth\":\"2016-06-27\"," +
"\"cell\":\"13000000000\"" +
"    }," +
"\"open_card_channel\":\"20161534000000000008863\"," +
"\"open_card_channel_id\":\"2088123123123123\"" +
"  }");
AlipayMarketingCardOpenResponse response = alipayClient.execute(request,accessToken);
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);
AlipayMarketingCardOpenRequest  request= new AlipayMarketingCardOpenRequest() ;
request.BizContent="{" +
"\"out_serial_no\":\"201606270000001\"," +
"\"card_template_id\":\"201606270000001\"," +
"\"card_user_info\":{" +
"\"user_uni_id\":\"2088302463082075\"," +
"\"user_uni_id_type\":\"UID\"" +
"    }," +
"\"card_ext_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\"" +
"    }," +
"\"member_ext_info\":{" +
"\"name\":\"Lee\"," +
"\"gende\":\"MALE\"," +
"\"birth\":\"2016-06-27\"," +
"\"cell\":\"13000000000\"" +
"    }," +
"\"open_card_channel\":\"20161534000000000008863\"," +
"\"open_card_channel_id\":\"2088123123123123\"" +
"  }";
AlipayMarketingCardOpenResponse response=client.execute(request,accessToken);
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 AlipayMarketingCardOpenRequest ();
$request->setBizContent("{" .
"\"out_serial_no\":\"201606270000001\"," .
"\"card_template_id\":\"201606270000001\"," .
"\"card_user_info\":{" .
"\"user_uni_id\":\"2088302463082075\"," .
"\"user_uni_id_type\":\"UID\"" .
"    }," .
"\"card_ext_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\"" .
"    }," .
"\"member_ext_info\":{" .
"\"name\":\"Lee\"," .
"\"gende\":\"MALE\"," .
"\"birth\":\"2016-06-27\"," .
"\"cell\":\"13000000000\"" .
"    }," .
"\"open_card_channel\":\"20161534000000000008863\"," .
"\"open_card_channel_id\":\"2088123123123123\"" .
"  }");
$result = $aop->execute ( $request , $accessToken ); 

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


      HTTP request source code

      copy
      https://openapi.alipay.com/gateway.do?timestamp=2013-01-01 08:08:08&method=alipay.marketing.card.open&app_id=4863&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&charset=GBK&auth_token=20130319e9b8d53d09034da8998caefa756c4006&biz_content=AlipayMarketingCardOpenModel


      #Response sample

      JSON

      copy
      {
    "alipay_marketing_card_open_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"
        },
        "open_card_channel": "QR",
        "open_card_channel_id": "2088123123123123"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}


      XML

      copy
      <alipay_marketing_card_open_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>
  <open_card_channel>QR</open_card_channel>
  <open_card_channel_id>2088123123123123</open_card_channel_id>
</alipay_marketing_card_open_response>


      #Exception sample

      JSON

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