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

      alipay.marketing.card.update

      Use this interface to update 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 application

      Example:2014072300007148

      method

      String (128) Required

      The interface name

      Example:alipay.marketing.card.update

      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: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 basic parameters, all other request parameters must be put in this parameter.

      Business parameter

      target_card_no

      String (32) Required

      The card number that is assigned by Alipay, identical to biz_card_no in the response of alipay.marketing.card.open.

      Example:000001

      target_card_no_type

      String (32) Required

      The type of the card number, with a value of BIZ_CARD to indicate a card number that is assigned by Alipay.

      Example:BIZ_CARD

      occur_time

      Date (32) Required

      The date and time when the update occurs. The format is yyyy-MM-dd HH:mm:ss.

      Example:2016-06-27 12:12:12

      card_info

      MerchantCardRequired

      Information about the card to be updated to. See card_info for details.

      ext_info

      String (1024)

      Extended information

      notify_messages

      McardNotifyMessage

      The message for notifying the card information update. See notify_messages for details.


      #card_info

      Parameter

      Description

      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 cannot be modified and must be the same with that of card_ext_info.open_date in the alipay.marketing.card.open interface.

      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 cannot be modified and must be the same with that of card_ext_info.valid_date in the alipay.marketing.card.open 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 only used in the card update interface for updating the card template.

      Example:20170308000000000058101000300045

      mdcode_info

      MdCodeInfoDTO (1024)

      Information about 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 dynamic code expires. 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


      #notify_messages

      Parameter

      Description

      message_type

      String (32) 

      Required

      Message type, with a fixed message template for each type. Possible values are:

      • POINT_UPDATE: message for points update
      • BALANCE_UPDATE: message for balance update
      • LEVEL_UPDATE: message for level update

      Example:OPEN_CARD

      change_reason

      String (64)

      Reason for the update, which is provided by ISV and needs to follow these templates:

      • Template for a point update: {change_reason}, your points are updated.
      • Template for a balance update: {change_reason}, your balance is updated.

      Note: For a level update, no reason needs to be provided.

      Example:Due to your consupmtion, your balance is updated.

      ext_info

      String (1024) 

      Extended information


      #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

      result_code

      String (64) Required

      Secondary error handling result.


      #Error codes

      Returned result

      Description

      Solution

      INVALID_PARAMETER

      Incorrect parameters

      Check the problem according to the message.

      SYSTEM_ERROR

      Alipay system error

      Try again.

      NO_CARD_TYPE

      The card type is not defined.

      Use a correct card type.

      CARD_NOT_EXIT

      The membership card doesn't exist.

      Keep all the parameters related to card number consistent with the ones when issuing the membership card.


      #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");
AlipayMarketingCardUpdateRequest request = new AlipayMarketingCardUpdateRequest();
request.setBizContent("{" +
"\"target_card_no\":\"000001\"," +
"\"target_card_no_type\":\"BIZ_CARD\"," +
"\"occur_time\":\"2016-06-27 12:12:12\"," +
"\"card_info\":{" +
"\"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\"" +
"    }," +
"\"ext_info\":\"\\\"\\\"\"," +
"      \"notify_messages\":[{" +
"        \"message_type\":\"OPEN_CARD\"," +
"\"change_reason\":\"Because of your consupmtion\"," +
"\"ext_info\":\"{}\"" +
"        }]," +
"\"mcard_style_info\":{" +
"\"bg_color\":\"rgb(55,112,179)\"," +
"\"logo_id\":\"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC\"," +
"\"background_id\":\"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC\"" +
"    }" +
"  }");
AlipayMarketingCardUpdateResponse 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);
AlipayMarketingCardUpdateRequest  request= new AlipayMarketingCardUpdateRequest() ;
request.BizContent="{" +
"\"target_card_no\":\"000001\"," +
"\"target_card_no_type\":\"BIZ_CARD\"," +
"\"occur_time\":\"2016-06-27 12:12:12\"," +
"\"card_info\":{" +
"\"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\"" +
"    }," +
"\"ext_info\":\"\\\"\\\"\"," +
"      \"notify_messages\":[{" +
"        \"message_type\":\"OPEN_CARD\"," +
"\"change_reason\":\"Because of your consumption\"," +
"\"ext_info\":\"{}\"" +
"        }]," +
"\"mcard_style_info\":{" +
"\"bg_color\":\"rgb(55,112,179)\"," +
"\"logo_id\":\"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC\"," +
"\"background_id\":\"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC\"" +
"    }" +
"  }";
AlipayMarketingCardUpdateResponse 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 AlipayMarketingCardUpdateRequest ();
$request->setBizContent("{" .
"\"target_card_no\":\"000001\"," .
"\"target_card_no_type\":\"BIZ_CARD\"," .
"\"occur_time\":\"2016-06-27 12:12:12\"," .
"\"card_info\":{" .
"\"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\"" .
"    }," .
"\"ext_info\":\"\\\"\\\"\"," .
"      \"notify_messages\":[{" .
"        \"message_type\":\"OPEN_CARD\"," .
"\"change_reason\":\"Becauses of your consumption\"," .
"\"ext_info\":\"{}\"" .
"        }]," .
"\"mcard_style_info\":{" .
"\"bg_color\":\"rgb(55,112,179)\"," .
"\"logo_id\":\"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC\"," .
"\"background_id\":\"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC\"" .
"    }" .
"  }");
$result = $aop->execute ( $request); 

$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.update&app_id=15631&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&charset=GBK&biz_content=
  {
"target_card_no":"000001",
"target_card_no_type":"BIZ_CARD",
"occur_time":"2016-06-27 12:12:12",
"card_info":{
"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"
    },
"ext_info":"\"\"",
      "notify_messages":[{
        "message_type":"OPEN_CARD",
"change_reason":"Because of your consumption",
"ext_info":"{}"
        }],
"mcard_style_info":{
"bg_color":"rgb(55,112,179)",
"logo_id":"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC",
"background_id":"1T8Pp00AT7eo9NoAJkMR3AAAACMAAQEC"
    }
  }


      #Response sample

      JSON

      copy
      {
    "alipay_marketing_card_update_response": {
        "code": "10000",
        "msg": "Success",
        "result_code": "isv.update-usercard-fail"
    },
    "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"
}


      XML

      copy
      <alipay_marketing_card_update_response>
<code>10000</code>
<msg>Success</msg>  <result_code>isv.update-usercard-fail</result_code>
</alipay_marketing_card_update_response>


      #Exception sample

      JSON

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