支付寶卡包——核銷卡劵（alipay.pass.instance.update）

接口名稱：支付寶pass更新卡券執行個體接口

英文名稱：alipay.pass.instance.update

上一步：[url]https://openclub.alipay.com/read.php?tid=13242&fid=72[/url]

下一步：[url]https://openclub.alipay.com/read.php?tid=13244&fid=72[/url]

一、注意事項

該接口主要用于使頁面顯示核銷狀态，且該接口還含有失效卡劵、更新卡劵功能。

更新卡券接口包含三大主要功能：核銷卡券、失效卡券、更新卡券樣式内容 

根據status參數傳值進行區分。

CLOSED：失效卡券功能 ，主要用于卡劵過期等操作；

USED：核銷卡券功能，主要用于使用者已核銷使用該卡劵。

1、核銷卡券功能 

該接口核銷操作隻是将卡券狀态變更為USED（已使用），使用者用戶端展示為已使用狀态，未涉及資金流的核銷。

status傳值USED，且tpl_params的useStateDesc必須修改為不可使用。

2、失效卡券功能

将發放出去的卡券進行廢棄，讓卡券在使用者的支付寶用戶端消失。

status傳值CLOSED，且tpl_params的useStateDesc必須修改為不可使用。

3、更新卡券功能

更新卡券樣式内容，包括内容、logo、背景圖、樣式等。

不設定傳參status，且tpl_params參數資訊進行修改。

二、參數說明

1，SERIAL_NUMBER：發放卡劵接口設定并傳回的SERIALNUMBER參數值;

2，channl_id：發放卡劵接口設定的channl_id參數值;

3，狀态傳值更新卡券，支付寶對應的卡券會消失對應的卡券

（1）CLOSED：表示該卡劵失效--------------失效卡券功能 

（2）用于：表示已使用該卡劵---------------核銷卡券功能

4，verify_code：核銷碼串值，即發放卡劵接口設定的代碼參數值 - 卡劵外部顯示卡号;

5，verify_type：目前支援波（聲波方式），QRCode的（二維碼方式），條形碼（條碼方式），輸入（文本方式，即手工輸入方式）.verify_code和verify_type需同時傳入;

設定參數值為該卡劵模闆pass.json中操作的格式參數值。

6，tpl_params：的channelID，代碼，SERIALNUMBER設定的自定義參數不同于與發放接口設定參數值，不會影響調用效果。

三、接口請求示例

Java版本請求示例

public static void main(String[] args) throws AlipayApiException {
	 	AlipayClient alipayClient = new DefaultAlipayClient(AlipayConfig.gatewayUrl, AlipayConfig.app_id, AlipayConfig.merchant_private_key, AlipayConfig.format, AlipayConfig.charset, AlipayConfig.alipay_public_key, AlipayConfig.sign_type); 
	    AlipayPassInstanceUpdateRequest request = new AlipayPassInstanceUpdateRequest();
        request.setBizContent(
        	//券狀态，支援更新為USED、CLOSED兩種狀态
            "{"status":"USED","
            //channl_id取發放卡券時候設定的值(應用的appid或pid)
            + ""channel_id":"2016101800718925","
            //serial_number取發放成功的卡券的值
            + ""serial_number":"20170809147614221","
            + ""tpl_params":"
            + "{"
            + ""validStartDate":"2017-08-28 08:00:00","
            + ""validEndDate":"2024-08-09 20:00:00","
            + ""channelID":"2016101800718925","
            + ""discountInfo":"憑此券即可打0.5折","
            + ""code":"201607232562587i","
            + ""useStateDesc":"不可使用","
            + ""logoText":"2017年七夕8月28日優惠券","
            + ""serialNumber":"20170809147614210"},"
            //核銷卡劵碼值
            +""verify_code":"2016072325625921","
            +""verify_type":"barcode""
            + "}");
         AlipayPassInstanceUpdateResponse response=null;
        try {
            response = alipayClient.execute(request);
            System.out.println(response.getBody());
         } catch (AlipayApiException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
         }
         if(response.isSuccess()){
         System.out.println("調用成功");
         } else {
         System.out.println("調用失敗");
         }
}      

響應參數傳回示例

{"alipay_pass_instance_update_response":{"code":"10000","msg":"Success","result":"{"operate":"UPDATE","serialNumber":"20170809147614221"}","success":true},"sign":"ddlhTexj/Tc5+gfXtd71GXecPpZrGsbBffLEs+/ioPmvJzfl9lQcZlekvPqZod8Ie5m2UhaY90fe0UszIn30wKlt7PnHNqV8U1Holqqy4mMUpjx3O2rPuF1zOIOFThYubhXveasJ7PxmLVohXNm3EE0PlPniY2dkYmOxhARkp1jtBous4CgCZ7gheOLOe4/x4PAAZDUfG1v1KFO5rBLjC5YQqt/pCRS//mqU+fQAL9CQvX+ioVUMV2UHyemv97ldWUwmeRoS1eL8FQnYVQcc2DpFM8CS7hFA5nbdMPyrHXpTwZMfjd7LruMTNWsRHTKnpGrgivZdzSLQ97burqUiTQ=="}      

PHP版本請求示例

<?php
require_once 'AopSdk.php';
$aop = new AopClient ();
$aop->appId = '填寫您的appid';
$aop->rsaPrivateKey = '填寫您的私鑰';
$aop->alipayrsaPublicKey='填寫您的支付寶公鑰';
$aop->gatewayUrl = 'https://openapi.alipay.com/gateway.do';
$aop->apiVersion = '1.0';
$aop->signType = 'RSA2';
$aop->postCharset='utf-8';
$aop->format='json';
$date=date("YmdHis");
$arr=range(1000,9999);
shuffle($arr);
$request = new AlipayPassInstanceUpdateRequest ();
$request->setBizContent(
///券狀态，支援更新為USED、CLOSED兩種狀态
            "{"status":"USED","
            //channl_id取發放卡券時候設定的值(應用的appid或pid)
            . ""channel_id":"2016101800718925","
            //serial_number取發放成功的卡券的值
            . ""serial_number":"20170809147614255","
            . ""tpl_params":"
            . "{"
            . ""validStartDate":"2017-08-28 08:00:00","
            . ""validEndDate":"2024-08-09 20:00:00","
            . ""channelID":"2016091500520089","
            . ""discountInfo":"憑此券即可打0.5折","
            . ""code":"201607232562587i","
            . ""useStateDesc":"不可使用","
            . ""logoText":"2017年七夕8月28日優惠券","
            . ""serialNumber":"20170809147614210"},"
            //核銷卡劵碼值
            .""verify_code":"2016072325625921","
            .""verify_type":"barcode""
            . "}");
$result = $aop->execute ( $request);
var_dump($result);
$responseNode = str_replace(".", "_", $request->getApiMethodName()) . "_response";
$resultCode = $result->$responseNode->code;
if(!empty($resultCode)&&$resultCode == 10000){
	echo "成功";
} else {
	echo "失敗";
}      

public 'alipay_pass_instance_update_response' => 
    object(stdClass)[9]
      public 'code' => string '10000' (length=5)
      public 'msg' => string 'Success' (length=7)
      public 'result' => string '{"operate":"UPDATE","serialNumber":"20170809147614255"}' (length=55)
      public 'success' => boolean true
  public 'sign' => string 'UFeRo6qHyhMpNe3+eja6d65MM7S2sxDz7fdHaSigL+YiU/JRz6cyXXc4qFiXH3FbFDsJ0GThesaMkmfJD5JA6T5bEydKsadynRxxjB2zg4PWtgF3fmEtR1Jac11qBKR7d4xRjVQbF5caQ4U4ST4jB0D0qqUJHk8RKRZgdxB3xkEWf/JMvAomt7DGeDUkr7aZSFp8uhFxsb71psnvMNn2FGSnmCxjkbXzXmCD6CiAiv+zPjbIacf4hkidMKWZjBxECx99dgFu5kYFy4k4LhxPBPfo/m5iNGrd0+F+GKBPQe9W698UNR+bgtEVPDzCHQAdNIKE2cvRlLB8Cl6+9zjUXA==' (length=344)      

.NET版本請求示例

IAopClient client = new DefaultAopClient(config.gatewayUrl, config.app_id, config.private_key, "json", "1.0", "RSA2", config.alipay_public_key, config.charset, false);


        AlipayPassInstanceUpdateRequest request = new AlipayPassInstanceUpdateRequest();
        request.BizContent="{" +
        ""serial_number":"20190402ygyg00001"," +
        ""channel_id":"2088522421611655"," +
        ""tpl_params":"