支付寶小程序：消費紅包

消費紅包是開放平臺提供給商戶的一種優惠營銷工具，發放消費紅包的商戶需提前出資。用戶在特定的交易場景下用支付寶付款時，可以使用消費紅包抵用付款金額。對于收到用戶付款的商戶（可以不是發放紅包的商戶），訂單的實際收入不會受到影響，如下圖所示。

發放紅包的商戶可指定用戶收到的紅包在支付寶任意支付場景或者商戶下核銷，詳見下文的 基礎功能 -> 創建紅包模板 部分。

對用戶來說，相比于其他的營銷工具，消費紅包有如下優勢：

• 支持拆分多次使用：例如，10元紅包，用戶付款1元，可以先用紅包抵扣1元；剩余9元可以繼續在支付時抵扣。

• 支持一筆訂單最多 10 個紅包疊加使用：例如，商戶A發送 1 元紅包（限制到店付款可用）給用戶，用戶又在支付寶掃碼領了一個 2 元紅包（限制到店付款可用），到門店付款 10 元；此時，用戶可以同時使用 1 元紅包 和 2 元紅包，用戶實際僅需支付 7 元。

• 消費紅包可退款：在紅包有效期內，用戶在使用消費紅包后發生交易退款，紅包繼續退還給用戶，紅包仍可以繼續使用；如果用戶在退款時，紅包已過期，則資金退還到發放紅包的原商戶的出資支付寶賬戶。

• 紅包逾期未核銷可退：如果消費紅包在被用戶領取后，在有效期內沒有核銷，則資金退還給發放紅包的原商戶的出資支付寶賬戶。一般為實時退回，最長時間不會超過一個工作日。

• 開放接口，免費使用；

• 紅包營銷效果好，活躍老用戶，拉取新用戶，提升交易量；

• 支持指定其他商戶、支付寶任意場景核銷的券：如，限制花唄還款可用，限制支付寶的某些支付產品（APP 支付、電腦網站支付等）才可用等場景。

• 在各種大中型節慶日，提前給圈定的用戶發放支付寶紅包，用戶拿到后，在符合紅包的使用條件下，使用支付寶付款時，可以自動抵扣；

• 異業營銷：如品牌商出資，廣告商幫助品牌商做活動或者品牌宣傳，向用戶發放花唄還款紅包、指定商戶使用的紅包等。

該能力對企業支付寶賬戶和個人支付寶賬戶（含個體工商戶）均開放。

免費

消費紅包（消費時抵扣）的主要使用流程如下圖所示：

注意：

創建紅包模板成功后，同步返回紅包模板資金付款收銀臺地址，商戶打開付款地址登錄支付寶賬戶支付，登錄收銀臺的支付寶賬戶需保證與創建券模板接口中指定的出資賬戶相同（fund_account）。

商戶調用支付寶發券（紅包）成功后，需要引導用戶添加券（紅包）到卡包。不論用戶是否添加到卡包，券（紅包）已經發給用戶，只是用戶添加后才能在卡包內露出展示；不添加也不影響用戶支付時核銷。 在添加到卡包時，需要券（紅包）ID 對應的用戶在支付寶 APP 中打開。

支付 APP 內引導添加：

如商戶需要用戶添加到卡包，可在商戶端發放活動中引導用戶直接添加，拼接支付寶用戶添加券（紅包）到卡包地址的方式：

拼鏈接（https://render.alipay.com/p/s/mygrace/ndetail.html?__webview_options__=sms%3DYES%26pd%3DNO&type=VOUCHER&id=）+券 id（發券成功后接口同步返回商戶）。

示例： https://render.alipay.com/p/s/mygrace/ndetail.html?__webview_options__=sms%3DYES%26pd%3DNO&type=VOUCHER&id=2017101200073002254500AVEV0E

完成添加到卡包后的頁面效果如下圖所示：

• 無資金商戶優惠券

• 現金抵價券

• 營銷活動送紅包

• 用戶信息授權

本文檔展示了如何從零開始，使用開放平臺服務端 SDK 快速接入?消費紅包（消費時抵扣）功能。

注意： 文檔中的代碼示例和 Demo 是用來闡述 API 基本使用方法的，僅針對大眾場景，供 ISV（系統服務商） 參考，特殊情況還請 ISV 自行擴展，確保符合自身業務需求。

要在您的小程序內使用消費紅包功能，您需要首先完成 開發者入駐 并 創建小程序。

小程序創建完成后，開發者在 功能列表 部分可以點擊 添加功能 來給創建的小程序添加功能。如下圖所示，開發者勾選 消費紅包?功能后，點擊左下角 確定 即完成添加功能。功能無需簽約即可使用。

添加功能包截圖

服務端 SDK 需要商戶集成在自己的服務端系統中，用于后續的服務端接口調用。

為了幫助開發者調用開放接口，我們提供了 開放平臺服務端 SDK ，包含 JAVA、PHP、NodeJS、Python 和 .NET 五種語言，封裝了簽名 & 驗簽、HTTP 接口請求等基礎功能。請先下載對應語言版本的 SDK 并引入您的開發工程。

在 SDK 調用前需要進行初始化，以 JAVA 代碼為例：

AlipayClient alipayClient = new DefaultAlipayClient(URL,APP_ID,APP_PRIVATE_KEY,FORMAT,CHARSET,ALIPAY_PUBLIC_KEY,SIGN_TYPE);

關鍵參數說明：

接下來，就可以用 alipayClient 來調用具體的 API 了。alipayClient 只需要初始化一次，后續調用不同的 API 都可以使用同一個 alipayClient 對象。

注意：

ISV /開發者可以通過 第三方應用授權 得到商戶授權令牌（app_auth_token）作為請求參數傳入，實現代商戶發起請求的能力。

完成接入指引的準備工作后，您就可以通過調用接口實現以下功能，完成消費紅包的發放。

參見?用戶授權?以此獲取用戶支付寶 user_id 等基礎信息用于發送消費紅包，如果商家已經獲取用戶的 user_id，可以跳過用戶授權步驟。

在商戶產生面向支付寶用戶的紅包發放需求時，需要首先調用該接口進行紅包模板的創建。

?

注意： 上圖接入流程中，商戶如果與開發者為同一角色，可省略掉授權環節。

以 JAVA 語言為例，調用 創建紅包模板接口（alipay.marketing.coupon.template.create）的示例代碼如下：

AlipayClient alipayClient =  new  DefaultAlipayClient( "https://openapi.alipay.com/gateway.do" , "app_id" , "your private_key" , "json" , "GBK" , "alipay_public_key" , "RSA2" );AlipayMarketingCouponTemplateCreateRequest request =  new  AlipayMarketingCouponTemplateCreateRequest(); request.setBizContent( "{"  +""voucher_type":"COUPON","  +//類型.暫時只支持"紅包"(COUPON)""voucher_use_scene":"HUABEI_COUPON_REPAYMENT","  +//紅包使用場景。""fund_account":"13040045386","  +//出資人登錄賬號。""brand_name":"支小寶","  +//品牌信息，由商戶自定義，在通用模板中展示在紅包LOGO下方。""publish_start_time":"2018-06-10 00:00:01","  +//發放開始時間，早于該時間不能發紅包。""publish_end_time":"2018-07-29 23:59:59","  +//發放結束時間，晚于該時間不能發紅包。紅包的發放結束時間和發放開始時間跨度不能大于90天。""voucher_valid_period":"{"type": "ABSOLUTE", "start": "2018-06-10 00:00:00","end": "2018-07-13 23:59:59"}"," +//紅包有效期""floor_amount":0,"  + //最低額度。設置紅包使用門檻""voucher_description":"["1、本紅包不可兌換現金，不可轉贈。","2、可以疊加使用，不限使用次數。"]","  +//紅包使用說明。""out_biz_no":"20180601000001654bb46ba","  +//外部業務單號。""total_amount":100.05,"  +//模板總金額。該數值不能小于1.00元，小數點以后最多保留兩位。""redirect_uri":"https://www.yourdomain.com/alipay/pay/success","  + //重定向地址。支付成功后需要重定向的地址，如果為空則不做重定向。""notify_uri":"https://www.yourdomain.com/reieve/voucher/flux","  +//紅包變動異步通知地址，傳入此字段后，紅包的核銷將會進行異步通知""rule_conf":"{"PID": "2088512417841101,2088512417841102", "STORE": "123456,678901"}","  + //pid的值需要調用商戶使用場景規則 PID 查詢接口查詢""extension_info":"{"coupon_AppActiveUrl":"http://www.yourdomain.com"}""  +" }" );AlipayMarketingCouponTemplateCreateResponse response = alipayClient.execute(request);  if (response.isSuccess()){System.out.println( "調用成功" );}  else  {System.out.println( "調用失敗" );}

關鍵入參說明：

1. voucher_type：券類型?？擅杜e，暫時只支持"紅包"(COUPON)。 使用示例： voucher_type=COUPON。

• 紅包可以拆分多次使用，例如，1元紅包，可以先用掉 0.5 元，剩余的 0.5 元可以繼續使用；

• 可以多個紅包疊加使用，一筆支付最多疊加 10 個紅包；

• 紅包被使用后發生退款，如果紅包有效期還在，會退還給用戶紅包，如果有效期已過，就會將資金退回原紅包模板出資賬戶。

1. voucher_use_scene：紅包使用場景。場景值會關聯當前紅包的展示模板，默認描述等信息。具體設置如下表：

1. fund_account：出資人登錄賬號，用于發紅包的資金會從該賬號劃撥到發紅包專用賬戶上。入參支付賬號即可，不強制為商戶賬號。

2. notify_uri：紅包變動異步通知地址，傳入此字段后，紅包的核銷將會進行異步通知。

注意：

當調用創建接口成功后，會返回付款訂單頁面，僅當前傳入資金賬號可進行付款，付款完成后紅包由草稿狀態變更為生效狀態，可進行發放。

1. brand_name：創建紅包模板時錄入的品牌信息，由商戶自定義，在通用模板中展示在紅包 logo 下方。根據紅包使用場景的不同，該信息的展示位置可能會有不同。

2. total_amount：模板總金額。本次發放模板設置的總金額。幣種為人民幣，單位為元。該數值不能小于1.00元，小數點以后最多保留兩位。

更多參數詳情參見?創建紅包模板接口?文檔。

關鍵出參說明：

1. template_id：紅包模板 ID。

2. fund_order_no：資金訂單號，模板支付時需要。

3. confirm_uri：模板支付確認鏈接 。

創建消費紅包模板成功后請打開出參的 confirm_uri 鏈接進行支付，如下圖所示。只有使用發紅包賬戶（fund_account）登錄后完成支付，紅包由草稿狀態變更為生效狀態，可進行發放。

在商戶或開發者完成支付寶紅包模板創建，并付款激活后，即可向用戶發放該紅包用于營銷支持。在發放紅包前，請先完成上圖步驟支付發放紅包的金額（total_amount），否則會出現 40004 的業務報錯。

在發放紅包完成后，可以按照 使用說明 章節中的介紹，引導用戶將收到的紅包添加到支付寶卡包。

上圖流程中，若開發者已通過其他渠道獲取到了用戶賬號/ID,可跳過授權流程：用戶信息授權。

以 JAVA 語言為例，調用 發券接口（alipay.marketing.voucher.send ）的示例代碼如下：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");rAlipayMarketingVoucherSendRequest request = new AlipayMarketingVoucherSendRequest();//創建API對應的request類rrequest.setBizContent("{" +r""template_id":"20140601000730010040000000EB"," +r""login_id":"13196215350"," +//支付寶登錄 IDr""taobao_nick":"yue54333"," +//淘寶昵稱r""user_id":"2088302001456115"," +//支付寶用戶 IDr""out_biz_no":"2016122814164328aadaee_1aee_4"," +r""amount":"9.99"," +//紅包金額，請傳入 String 類型，單位為“元”，請不要超過 total_amount(創建紅包模板時傳入的總金額）r""memo":"紅包"" +//發紅包備注r"}");//設置業務參數rAlipayMarketingVoucherSendResponse response = alipayClient.execute(request);rif(response.isSuccess()){rSystem.out.println("調用成功");r} else {rSystem.out.println("調用失敗");r}// 根據response中的結果繼續業務邏輯處理

注意：

紅包金額（amount）請不要超過在 創建紅包模板?時傳入的總金額（total_amount），否則會報錯金額不足。

關鍵入參說明：

1. template_id：紅包模板 ID。

2. login_id：支付寶登錄 ID，手機或郵箱。user_id, login_id, taobao_nick 不能同時為空，優先級依次降低。

3. amount：紅包金額，單位是元，類型為 String。紅包發放時填寫，其它情形不能填。

更多參數詳情參見?發券接口 文檔。

關鍵出參說明：

1. voucher_id：紅包 ID。

2. user_id：支付寶用戶 ID。

在商戶紅包被核銷時，將對紅包創建的開發者設置的服務地址進行異步調用通知。

回調參數說明：

當創建的紅包模板草稿信息有誤，或需要提前進行已激活的紅包模板過期，可進行紅包模板信息修改。

以 JAVA 語言為例，調用 修改券模板接口（alipay.marketing.cashvoucher.template.modify）的示例代碼如下：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");rAlipayMarketingCashvoucherTemplateModifyRequest request = new AlipayMarketingCashvoucherTemplateModifyRequest();//創建API對應的request類rrequest.setBizContent("{" +r""template_id":"20140601000730010040000000EB"," +//券模板ID    r""slogan":"四川移動"," +//券標語，用于拼接券名稱，最多6個字符，券名稱=券標語+券面額+’元代金券’。僅草稿狀態可修改r""publish_start_time":"2017-01-01 00:00:01"," +//發放開始時間，早于該時間不能發券。r""publish_end_time":"2017-01-29 23:59:59"," +//發放結束時間，晚于該時間不能發券。r""voucher_valid_period":"{"type":"ABSOLUTE","start":"2017-01-1000:00:00","end":"2017-01-1323:59:59"}"," +//券有效期。r""out_biz_no":"2017000xxx_modify"" +//外部業務單號r"}");//設置業務參數rAlipayMarketingCashvoucherTemplateModifyResponse response = alipayClient.execute(request);//通過alipayClient調用API，獲得對應的response類rif(response.isSuccess()){rSystem.out.println("調用成功");r} else {rSystem.out.println("調用失敗");r}// 根據response中的結果繼續業務邏輯處理

關鍵入參說明：

1. slogan：券標語，用于拼接券名稱，最多6個字符，券名稱=券標語+券面額+’元代金券’。僅草稿狀態可修改。

2. publish_start_time：發放開始時間，早于該時間不能發券。發放開始時間不能大于當前時間15天。格式為：yyyy-MM-dd HH:mm:ss。僅草稿狀態可修改。僅草稿狀態可修改。

3. publish_end_time：發放結束時間，晚于該時間不能發券。券的發放結束時間和發放開始時間跨度不能大于90天。發放結束時間必須晚于發放開始時間。格式為：yyyy-MM-dd HH:mm:ss。草稿狀態和生效狀態可修改。

更多參數詳情參見?修改券模板接口?文檔

關鍵出參說明：

status：模板修改后的狀態，I 表示草稿狀態所有入參都被修改了，S 表示生效狀態僅修改了 publish_end_time。

查詢模板的詳細信息，包含準實時的匯總信息。

?

以 JAVA 語言為例，調用?查詢券模板詳情接口（alipay.marketing.voucher.templatedetail.query）的示例代碼如下：

AlipayClient alipayClient =  new  DefaultAlipayClient( "https://openapi.alipay.com/gateway.do" , "app_id" , "your private_key" , "json" , "GBK" , "alipay_public_key" , "RSA2" );rAlipayMarketingVoucherTemplatedetailQueryRequest request =  new  AlipayMarketingVoucherTemplatedetailQueryRequest(); //創建API對應的request類 rrequest.setBizContent( "{"  +r""template_id":"20140601000730010040000000EB""  +//券模板ID    r"}" ); //設置業務參數 rAlipayMarketingVoucherTemplatedetailQueryResponse response = alipayClient.execute(request); //通過alipayClient調用API，獲得對應的response類 rif (response.isSuccess()){rSystem.out.println( "調用成功" );r}  else  {rSystem.out.println( "調用失敗" );r} // 根據response中的結果繼續業務邏輯處理

關鍵入參說明：?

template_id：券模板 ID。

關鍵出參說明：

1. template_id：紅包模板 ID。

2. voucher_type：紅包類型。

3. status：模板狀態，可枚舉。分別為‘草稿’(I)、‘生效’(S)、‘刪除’(D)和‘過期’(E)。

4. amount：面額。每張代金紅包可以抵扣的金額。幣種為人民幣，單位為元。該數值不小于 0，小數點以后最多兩位。

5. total_amount：總金額面額。幣種為人民幣，單位為元。該數值不小于 0，小數點以后最多兩位，僅代金券有效。

6. publish_count：已發放張數。單位為張。該數值是大于 0 的整數。

7. publish_amount：已發放總金額。幣種為人民幣，單位為元。該數值不小于 0，小數點以后最多兩位。

8. used_count：已使用張數。單位為張。該數值是大于 0 的整數。

9. used_amount：已使用總金額。幣種為人民幣，單位為元。該數值不小于 0，小數點以后最多兩位。

10. recycle_amount：退回金額。幣種為人民幣，單位為元。該數值不小于 0，小數點以后最多兩位。

注意：

該接口數據同步會有兩小時延遲，如需查詢模板發放優惠券/紅包詳情，請在發放兩個小時后調用該接口。

更多參數詳情參見?查詢券模板詳情接口?文檔。

分頁查詢當前 PID 下的所有模板。

以 JAVA 語言為例，調用?查詢券模板列表接口（alipay.marketing.voucher.templatelist.query）的示例代碼如下：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");rAlipayMarketingVoucherTemplatelistQueryRequest request = new AlipayMarketingVoucherTemplatelistQueryRequest();//創建API對應的request類rrequest.setBizContent("{" +r""create_start_time":"2017-01-0100:00:01"," +r""create_end_time":"2017-01-2923:59:59"," +r""page_num":1," +r""page_size":20" +r"}");//設置業務參數rAlipayMarketingVoucherTemplatelistQueryResponse response = alipayClient.execute(request);//通過alipayClient調用API，獲得對應的response類rif(response.isSuccess()){rSystem.out.println("調用成功");r} else {rSystem.out.println("調用失敗");r}// 根據response中的結果繼續業務邏輯處理

關鍵入參說明：

1. create_start_time：模板創建開始時間，格式為：yyyy-MM-dd HH:mm:ss。

2. create_end_time：模板創建結束時間，格式為：yyyy-MM-dd HH:mm:ss。

3. page_num：頁碼，必須為大于0的整數，1表示第一頁，2表示第2頁，依次類推。

4. page_size：每頁記錄條數，必須為大于0的整數，最大值為30。

關鍵出參說明：

voucher_templates： 紅包模板列表??

└ template_id：紅包模板 ID。

└ voucher_name：t紅包名稱。

└ status：模板狀態，可枚舉。分別為‘草稿’(I)、‘生效’(S)和‘過期’(E) 。

└ create_time：模板創建時間。格式為：yyyy-MM-dd HH:mm:sst。

└ activate_time： 模板激活時間。草稿狀態的模板該項為空。

更多參數詳情參見 查詢券模板列表接口 文檔。

在創建紅包使用規則時，查詢當前商戶所有外部門店數據。

使用 SDK 快速接入 以 JAVA 語言為例，調用?商戶外部門店查詢接口（ant.merchant.expand.merchant.storelist.query）的示例代碼如下：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");rAntMerchantExpandMerchantStorelistQueryRequest request = new AntMerchantExpandMerchantStorelistQueryRequest();//創建API對應的request類rrequest.setBizContent("{" +r""pid":"2088202967380463"," +//指定的商戶pid，如果指定， 只返回此pid的店鋪信息。r""is_include_cognate":"false"," +r""page_num":1," +//頁碼，必須為大于0的整數r""page_size":20" +//每頁記錄條數，必須為大于0的整數，最大值為30r"}");//設置業務參數rAntMerchantExpandMerchantStorelistQueryResponse response = alipayClient.execute(request);//通過alipayClient調用API，獲得對應的response類rif(response.isSuccess()){rSystem.out.println("調用成功");r} else {rSystem.out.println("調用失敗");r}// 根據response中的結果繼續業務邏輯處理

關鍵入參說明：

1. pid：指定的商戶 pid，如果指定，只返回此 pid 的店鋪信息(此 pid 必須是商戶自己的)。

2. is_include_cognate：該參數可入參 true / false。

• 當 is_include_cognate = true，指定 pid 為空，查詢商戶下所有pid的店鋪；

• 當 is_include_cognate = true，指定 pid 不為空時，查詢指定pid的店鋪；

• 當 is_include_cognate = false，指定 pid 為空時，查詢當前商戶pid的店鋪；

• 當 is_include_cognate = false，指定 pid 不為空時，查詢指定pid的店鋪。

關鍵出參說明：

merchant_stores：復雜類型 ShopQueryInfo，商戶門店列表：

└ pid：商戶 pid。

└ shop_id：內部門店ID。

└ store_id：外部門店ID。

└ name：門店名稱。

更多參數詳情參見? 商戶外部門店查詢接口 文檔。

可以刪除處于草稿狀態的紅包模板。

以 JAVA 語言為例，調用 刪除券模板接口（alipay.marketing.voucher.template.delete）的示例代碼如下：

AlipayClient alipayClient =  new  DefaultAlipayClient( "https://openapi.alipay.com/gateway.do" , "app_id" , "your private_key" , "json" , "GBK" , "alipay_public_key" , "RSA2" );rAlipayMarketingVoucherTemplateDeleteRequest request =  new  AlipayMarketingVoucherTemplateDeleteRequest(); //創建API對應的request類 rrequest.setBizContent( "{"  +r""template_id":"20140601000730010040000000EB""  +//模板 IDr"}" ); //設置業務參數 rAlipayMarketingVoucherTemplateDeleteResponse response = alipayClient.execute(request); //通過alipayClient調用API，獲得對應的response類 rif (response.isSuccess()){rSystem.out.println( "調用成功" );r}  else  {rSystem.out.println( "調用失敗" );r} // 根據response中的結果繼續業務邏輯處理

關鍵入參說明：

template_id：模板 ID。

查詢當前PID創建的某個模板給某用戶發送的所有的紅包。

以 JAVA 語言為例，調用?查詢券列表接口（alipay.marketing.voucher.list.query）的示例代碼如下：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");rAlipayMarketingVoucherListQueryRequest request = new AlipayMarketingVoucherListQueryRequest();//創建API對應的request類rrequest.setBizContent("{" +r""template_id":"20140601000730010040000000EB"," +r""user_id":"2088512417841101"" +r"}");//設置業務參數rAlipayMarketingVoucherListQueryResponse response = alipayClient.execute(request);//通過alipayClient調用API，獲得對應的response類rif(response.isSuccess()){rSystem.out.println("調用成功");r} else {rSystem.out.println("調用失敗");r}// 根據response中的結果繼續業務邏輯處理

關鍵入參說明：?

1. template_id：模板 ID。

2. user_id：支付寶用戶 ID。

關鍵出參說明：

vouchers：紅包列表

└ template_id：模板 ID。

└ voucher_id：紅包 ID。

└ status：紅包狀態，可枚舉，分別為“可用”(ENABLED)和“不可用”(DISABLED)。

└ send_time：發紅包時間，格式為：yyyy-MM-dd HH:mm:ss。

更多參數詳情參見?查詢券列表接口 文檔。

發放給用戶的紅包實例查詢。

使用 SDK 快速接入

以 JAVA 語言為例，調用?券查詢接口（alipay.marketing.voucher.query）的示例代碼如下：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");rAlipayMarketingVoucherQueryRequest request = new AlipayMarketingVoucherQueryRequest();//創建API對應的request類rrequest.setBizContent("{" +r""voucher_id":"20170616000730020041006ZYE2V"" +r"}");//設置業務參數rAlipayMarketingVoucherQueryResponse response = alipayClient.execute(request);//通過alipayClient調用API，獲得對應的response類rif(response.isSuccess()){rSystem.out.println("調用成功");r} else {rSystem.out.println("調用失敗");r}// 根據response中的結果繼續業務邏輯處理

關鍵入參說明：?

voucher_id：紅包 ID(紅包唯一標識,發紅包接口返回參數)。

關鍵出參說明：?

1. user_id：紅包所屬用戶 ID。

2. gmt_active：紅包激活時間(紅包可以使用起始時間)。

3. gmt_expired：紅包過期時間(紅包可以使用截止時間)。

4. total_amount：紅包面額(元)。

5. available_amount：紅包余額(元)。

6. status：紅包狀態(ENABLED:可用，DISABLED:不可用，DELETE:刪除狀態，TRANS:發放中，TRANSFER:已轉贈，UNC:未領取,USED:已使用，USING:使用中，REFUNDED:已退款，REFUNDING:退款中，UNACTIVE:未激活，EXPIRED:已過期)。

7. gmt_create：紅包創建時間(紅包發放時間)。

8. bill_details：復雜類型 VoucherBillDetail，紅包交易賬單信息(核銷交易信息、交易退款信息等可能存在多條)

└ trade_no：紅包ID(紅包唯一標識,發紅包接口返回參數)。

└ amount：紅包核銷/退款金額。

└ status：交易狀態(I:處理中, S:成功)。

└ partner_id：交易合作伙伴 ID。

└ partner_name：商戶名稱。

└ biz_type：賬單類型(V_USE:支付,V_REFUND:退款)。

└ gmt_create：交易時間。

更多參數詳情參見 券查詢接口 文檔。

查詢商戶可用于使用場景規則的 PID。調用 創建紅包模板接口?時規則參數（rule_conf）中 pid 的值只能入參該接口查詢到的 pid 值。

以 JAVA 語言為例，調用?商戶使用場景規則 PID 查詢接口（alipay.marketing.userule.pid.query）的示例代碼如下：

AlipayClient alipayClient = new DefaultAlipayClient("https://openapi.alipay.com/gateway.do","app_id","your private_key","json","GBK","alipay_public_key","RSA2");rAlipayMarketingUserulePidQueryRequest request = new AlipayMarketingUserulePidQueryRequest();//創建API對應的request類rrequest.setBizContent("{" +r""pid":"2088202967380463"" +r"}");//設置業務參數rAlipayMarketingUserulePidQueryResponse response = alipayClient.execute(request);//通過alipayClient調用API，獲得對應的response類rif(response.isSuccess()){rSystem.out.println("調用成功");r} else {rSystem.out.println("調用失敗");r}// 根據response中的結果繼續業務邏輯處理

關鍵入參說明：?

pid：合作伙伴 ID，傳入 ID 比如與當前 APPID 所屬合作伙伴 ID 一致，否則會報權限不足。

關鍵出參說明：

pids：滿足條件的所有 pid，多個 pid 使用英文逗號隔。

更多參數詳情參見? 商戶使用場景規則 PID 查詢接口 文檔。

此列表包含產品所涉及的所有接口，點擊接口英文名可查看接口的公共請求參數，業務請求參數，返回參數，其他語言請求示例以及錯誤碼等信息。

A：無論現金抵價券、無資金商戶優惠券還是消費紅包，直接在用戶核銷的訂單金額中抵扣，優惠券的業務中，支付寶均無收入，所以不需要開具發票。 核銷訂單中，核銷的商戶需要向用戶開具發票，建議按照用戶實付金額開票；優惠券紅包部分的發票，發券商戶可以向核銷的商戶索取，支付寶不介入雙方的發票索取事宜。

A：支持借記類渠道（余額、余額寶、借記卡、網銀）。

A：資金退回的場景：

• 紅包模板發放有效期到期或者主動刪除紅包模板，紅包模板未發放的剩余資金；

• 用戶紅包核銷后，交易發生退款，且紅包有效期已過，導致紅包資金的退回；

• 消費紅包在被用戶領取后，在有效期內沒有核銷。

資金退回渠道：均統一退回至原出資支付寶賬戶余額。

退回時間：一般為實時退回，最長時間不會超過一個工作日。

A：一筆支付訂單最多使用 10 個支付寶紅包。

A：支持拆分多次使用，不限制拆分次數上限。

A：交易退款，如果紅包有效期還在，紅包會退還給用戶。否則，如果紅包已過期，則資金會退回原紅包模板出資賬戶余額。

A：發送紅包接口 amount 參數為 String 類型，請檢查入參格式是否正確。

A：支持。