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

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 showon 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"
}