支付有礼API简介

支付有礼是面向符合条件的微信支付商户开放的营销能力，用户在商家使用微信支付后可以领取微信支付代金券，下次回店消费只要符合用券条件即可自动抵扣优惠，能有效帮助商户拉动顾客二次购买或完成线下门店－线上商城的连接。

支持全场满额送支持商户支付后发单张券／券包支持投放全场满减券、换购券、折扣券，目前支付有礼API仅支持投放商家券落地页支持商户自定义品牌颜色、logo、商品图片活动造节，节前发券，节日冲量新品上市，提前发券券包套餐组合，爆品带销线下顾客沉淀至小程序【会员运营/电商,外卖/到家小程序】寻找其它出资方【品牌,银行等】

使用场景：商户可以创建满额送活动，用户支付后送全场券，提升交易额。

接口链接：创建全场满额送活动API

使用场景：商户创建活动后，可以通过该接口查询支付有礼的活动详情，用于管理活动。

接口链接：获取活动详情接口API

使用场景：商户创建活动后，可以通过该接口查询支付有礼的发券商户号，用于管理活动。

接口链接：获取活动发券商户号

使用场景：商户可通过该接口停止支付有礼活动。

在正式接入微信支付支付有礼服务前，你需要进行以下准备步骤：

确认资质选择接入模式：普通商户或普通服务商申请参数：AppID、商户号

在正式接入前，请确保商户（对于服务商，则是子商户）已创建商家券

商户需要判断自己公司注册区域适用的接入模式和自身实际情况，申请成为普通商户或普通服务商：

普通商户自行申请入驻微信支付，无需服务商协助。普通服务商则自身无法作为一个普通商户直接发起交易，其发起交易必须传入相关特约商户商户号的参数信息。

1. 接口规则

为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。

为了帮助开发者调用开放接口，我们提供了JAVA、PHP、GO三种语言版本的开发库，封装了签名生成、签名验证、敏感信息加/解密、媒体文件上传 等基础功能（更多语言版本的开发库将在近期陆续提供）。

测试步骤：

1、根据自身开发语言，选择对应的开发库并构建项目，具体配置请参考下面链接的详细说明：

wechatpay-java (opens new window)（推荐）、wechatpay-apache-httpclient (opens new window)，适用于Java开发者。注：当前开发指引接口JAVA示例代码采用wechatpay-apache-httpclient版本。wechatpay-php (opens new window)（推荐）、wechatpay-guzzle-middleware (opens new window)，适用于PHP开发者。注：当前开发指引接口PHP示例代码采用wechatpay-guzzle-middleware版本。wechatpay-go (opens new window)，适用于Go开发者。

更多资源可前往微信支付开发者社区 (opens new window)搜索查看。

2、创建加载商户私钥、加载平台证书、初始化httpClient的通用方法。

示例代码

javaphp

1@Before2public void setup() throws IOException {3    // 加载商户私钥（privateKey：私钥字符串）4    PrivateKey merchantPrivateKey = PemUtil5            .loadPrivateKey(new ByteArrayInputStream(privateKey.getBytes("utf-8")));6 7    // 加载平台证书（mchId：商户号,mchSerialNo：商户证书序列号,apiV3Key：V3密钥）8    AutoUpdateCertificatesVerifier verifier = new AutoUpdateCertificatesVerifier(9            new WechatPay2Credentials(mchId, new PrivateKeySigner(mchSerialNo, merchantPrivateKey)),apiV3Key.getBytes("utf-8"));10 11    // 初始化httpClient12    httpClient = WechatPayHttpClientBuilder.create()13            .withMerchant(mchId, mchSerialNo, merchantPrivateKey)14            .withValidator(new WechatPay2Validator(verifier)).build();15}16 17@After18public void after() throws IOException {19    httpClient.close();20}

3、基于接口的示例代码，替换请求参数后可发起测试。

说明：

上面的开发库为微信支付官方开发库，其它没有审核或者控制下的第三方工具和库，微信支付不保证它们的安全性和可靠性。通过包管理工具引入SDK后，可根据下面每个接口的示例代码替换相关参数后进行快速测试。开发者如果想详细了解签名生成、签名验证、敏感信息加/解密、媒体文件上传等常用方法的具体代码实现，可阅读下面的详细说明：签名生成签名验证敏感信息加解密merchantPrivateKey（私钥）wechatpayCertificates（平台证书）APIV3Key（V3 key）如想更详细的了解我们的接口规则，可查看我们的接口规则指引文档。

重点步骤说明：

步骤5 商户创建商家券后，可通过《创建全场满额送活动》接口创建支付有礼活动，微信支付生成支付有礼活动并返回活动ID给到商户。

步骤20 支付有礼活动创建后，商户可通过《获取活动详情接口》查询管理活动。

步骤22 活动创建后，如需结束活动，可通过《终止活动》接口，结束活动。

文档展示了如何使用微信支付服务端 SDK 快速接入支付有礼，完成与微信支付对接的部分。

注意

文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。

步骤说明：商户可以创建满额送活动，用户支付后送全场券，提升交易额。

background_color取值：

示例代码

javaphp

1public void CreateActivity() throws Exception{2    //请求URL3    HttpPost httpPost = new HttpPost(";);4    // 请求body参数5    String reqdata = "{"6            + "\"activity_base_info\": {"7            + "\"activity_name\":\"良品铺子回馈活动\","8            + "\"activity_second_title\":\"海飞丝的券\","9            + "\"merchant_logo_url\":\"\","10            + "\"background_color\":\"COLOR010\","11            + "\"begin_time\":\"2015-05-20T13:29:35+08:00\","12            + "\"end_time\":\"2015-05-20T13:29:35+08:00\","13            + "\"available_periods\": {"14            + "\"available_time\": ["15            + "{"16            + "\"begin_time\":\"2015-05-20T00:00:00+08:00\","17            + "\"end_time\":\"2015-05-20T23:59:59+08:00\""18            + "}"19            + "],"20            + "\"available_day_time\": ["21            + "{"22            + "\"begin_day_time\":\"110000\","23            + "\"end_day_time\":\"135959\""24            + "}"25            + "]"26            + "},"27            + "\"out_request_no\":\"100002322019090134234sfdf\","28            + "\"delivery_purpose\":\"OFF_LINE_PAY\","29            + "\"mini_programs_appid\":\"wx23232232323\","30            + "\"mini_programs_path\":\"/path/index/index\""31            + "},"32            + "\"award_send_rule\": {"33            + "\"transaction_amount_minimum\":100,"34            + "\"send_content\":\"SINGLE_COUPON\","35            + "\"award_type\":\"BUSIFAVOR\","36            + "\"award_list\": ["37            + "{"38            + "\"stock_id\":\"98065001\","39            + "\"original_image_url\":\"\","40            + "\"thumbnail_url\":\"\""41            + "}"42            + "],"43            + "\"merchant_option\":\"MANUAL_INPUT_MERCHANT\","44            + "\"merchant_id_list\": ["45            + "\"0\":\"10000022\","46            + "\"1\":\"10000023\""47            + "]"48            + "},"49            + "\"advanced_setting\": {"50            + "\"delivery_user_category\":\"DELIVERY_MEMBER_PERSON\","51            + "\"merchant_member_appid\":\"34567890\","52            + "\"goods_tags\": ["53            + "\"0\":\"xxx\","54            + "\"1\":\"yyy\""55            + "]"56            + "}"57            + "}";58    StringEntity entity = new StringEntity(reqdata,"utf-8");59    entity.setContentType("application/json");60    httpPost.setEntity(entity);61    httpPost.setHeader("Accept", "application/json");6263    //完成签名并执行请求64    CloseableHttpResponse response = httpClient.execute(httpPost);6566    try {67        int statusCode = response.getStatusLine().getStatusCode();68        if (statusCode == 200) { //处理成功69            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));70        } else if (statusCode == 204) { //处理成功，无返回Body71            System.out.println("success");72        } else {73            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));74            throw new IOException("request failed");75        }76    } finally {77        response.close();78    }79}

重要入参说明：

activity_name：活动名称。activity_second_title：活动副标题。merchant_logo_url：商户logo，送出优惠券时展示， 仅支持通过《图片上传API》接口获取的图片URL地址。out_request_no：商户请求单号，商户创建批次凭据号（格式：商户ID+日期+流水号），商户侧需保持唯一性，可包含英文字母，数字，｜，_，*，-等内容，不允许出现其他不合法符号。delivery_purpose：投放目的。枚举值：

OFF_LINE_PAY：拉用户回店消费

JUMP_MINI_APP：引导用户前往小程序消费。send_content：发放内容，可选单张券或礼包，选礼包时奖品限定3-5个。枚举值：

SINGLE_COUPON：单张券

GIFT_PACKAGE：礼包

步骤说明：商户创建活动后，可以通过该接口查询支付有礼的活动详情，用于管理活动。

示例代码

javaphp

1public void QueryActivity() throws Exception{2    //请求URL3    HttpGet httpGet = new HttpGet(";);4    httpGet.setHeader("Accept", "application/json");56    //完成签名并执行请求7    CloseableHttpResponse response = httpClient.execute(httpGet);89    try {10        int statusCode = response.getStatusLine().getStatusCode();11        if (statusCode == 200) { //处理成功12            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));13        } else if (statusCode == 204) { //处理成功，无返回Body14            System.out.println("success");15        } else {16            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));17            throw new IOException("request failed");18        }19    } finally {20        response.close();21    }22}

步骤说明：商户创建活动后，可以通过该接口查询支付有礼的发券商户号，用于管理活动。

示例代码

javaphp

1public void QueryActivityMch() throws Exception{2    //请求URL3    HttpGet httpGet = new HttpGet(";);4    httpGet.setHeader("Accept", "application/json");56    //完成签名并执行请求7    CloseableHttpResponse response = httpClient.execute(httpGet);89    try {10        int statusCode = response.getStatusLine().getStatusCode();11        if (statusCode == 200) { //处理成功12            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));13        } else if (statusCode == 204) { //处理成功，无返回Body14            System.out.println("success");15        } else {16            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));17            throw new IOException("request failed");18        }19    } finally {20        response.close();21    }22}

重要入参说明：

activity_id：活动ID。

更多参数、响应详情及错误码请参见获取活动发券商户号接口文档。

步骤说明：商户创建活动后，可以通过该接口查询支付有礼的活动指定商品，用于管理活动。

示例代码

javaphp

1public void QueryActivityGoods() throws Exception{2    //请求URL3    HttpGet httpGet = new HttpGet(";);4    httpGet.setHeader("Accept", "application/json");56    //完成签名并执行请求7    CloseableHttpResponse response = httpClient.execute(httpGet);89    try {10        int statusCode = response.getStatusLine().getStatusCode();11        if (statusCode == 200) { //处理成功12            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));13        } else if (statusCode == 204) { //处理成功，无返回Body14            System.out.println("success");15        } else {16            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));17            throw new IOException("request failed");18        }19    } finally {20        response.close();21    }22}

重要入参说明：

activity_id：活动ID。

更多参数、响应详情及错误码请参见获取活动指定商品列表接口文档。

步骤说明：商户可通过该接口停止支付有礼活动。

示例代码

javaphp

1public void TerminateActivity() throws Exception{2    //请求URL3    HttpPost httpPost = new HttpPost(";);4    // 请求body参数5    String reqdata ="";6    StringEntity entity = new StringEntity(reqdata,"utf-8");7    entity.setContentType("application/json");8    httpPost.setEntity(entity);9    httpPost.setHeader("Accept", "application/json");1011    //完成签名并执行请求12    CloseableHttpResponse response = httpClient.execute(httpPost);1314    try {15        int statusCode = response.getStatusLine().getStatusCode();16        if (statusCode == 200) { //处理成功17            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));18        } else if (statusCode == 204) { //处理成功，无返回Body19            System.out.println("success");20        } else {21            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));22            throw new IOException("request failed");23        }24    } finally {25        response.close();26    }27}

重要入参说明：

activity_id：活动ID。

更多参数、响应详情及错误码请参见终止活动接口文档。

步骤说明：商户创建活动后，可以通过该接口增加支付有礼的发券商户号，用于管理活动。

示例代码

javaphp

1public void GetActivityList() throws Exception{2  // 加载商户私钥（privateKey：私钥字符串）3  PrivateKey merchantPrivateKey = PemUtil4          .loadPrivateKey(new ByteArrayInputStream(privateKey.getBytes("utf-8")));56  // 加载平台证书（mchId：商户号,mchSerialNo：商户证书序列号,apiV3Key：V3秘钥）7  AutoUpdateCertificatesVerifier verifier = new AutoUpdateCertificatesVerifier(8          new WechatPay2Credentials(mchId, new PrivateKeySigner(mchSerialNo, merchantPrivateKey)),apiV3Key.getBytes("utf-8"));910  CloseableHttpClient httpClient = HttpClients.createDefault();11  // 初始化httpClient12  httpClient = WechatPayHttpClientBuilder.create()13          .withMerchant(mchId, mchSerialNo, merchantPrivateKey)14          .withValidator(new WechatPay2Validator(verifier)).build();1516  //请求URL17  HttpPost httpPost = new HttpPost(";);18  // 请求body参数19  String reqdata = "{"20          + "\"merchant_id_list\": ["21          + "\"100123456\","22          + "\"100123457\""23          + "],"24          + "\"add_request_no\":\"100002322019090134234sfdf\""25          + "}";26  StringEntity entity = new StringEntity(reqdata,"utf-8");27  entity.setContentType("application/json");28  httpPost.setEntity(entity);29  httpPost.setHeader("Accept", "application/json");3031  //完成签名并执行请求32  CloseableHttpResponse response = httpClient.execute(httpPost);3334  try {35      int statusCode = response.getStatusLine().getStatusCode();36      if (statusCode == 200) { //处理成功37          System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));38      } else if (statusCode == 204) { //处理成功，无返回Body39          System.out.println("success");40      } else {41          System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));42          throw new IOException("request failed");43      }44  } finally {45      response.close();46  }47}

重要入参说明：

activity_id：活动ID。add_request_no：请求业务单据号，商户添加发券商户号的凭据号，商户侧需保持唯一性。

步骤说明：商户根据一定过滤条件，查询已创建的支付有礼活动。

示例代码

javaphp

1public void GetActivityList() throws Exception{2  // 加载商户私钥（privateKey：私钥字符串）3  PrivateKey merchantPrivateKey = PemUtil4          .loadPrivateKey(new ByteArrayInputStream(privateKey.getBytes("utf-8")));56  // 加载平台证书（mchId：商户号,mchSerialNo：商户证书序列号,apiV3Key：V3秘钥）7  AutoUpdateCertificatesVerifier verifier = new AutoUpdateCertificatesVerifier(8          new WechatPay2Credentials(mchId, new PrivateKeySigner(mchSerialNo, merchantPrivateKey)),apiV3Key.getBytes("utf-8"));910  CloseableHttpClient httpClient = HttpClients.createDefault();11  // 初始化httpClient12  httpClient = WechatPayHttpClientBuilder.create()13          .withMerchant(mchId, mchSerialNo, merchantPrivateKey)14          .withValidator(new WechatPay2Validator(verifier)).build();1516  //请求URL17  HttpGet httpGet = new HttpGet(";);18  httpGet.setHeader("Accept", "application/json");1920  //完成签名并执行请求21  CloseableHttpResponse response = httpClient.execute(httpGet);2223  try {24      int statusCode = response.getStatusLine().getStatusCode();25      if (statusCode == 200) { //处理成功26          System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));27      } else if (statusCode == 204) { //处理成功，无返回Body28          System.out.println("success");29      } else {30          System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));31          throw new IOException("request failed");32      }33  } finally {34      response.close();35  }36}

重要入参说明：

offset：分页页码，页面从0开始。limit：分页大小。特殊规则：最大取值为100，最小为1。

步骤说明：商户创建活动后，可以通过该接口删除支付有礼的发券商户号，用于管理活动。

示例代码

javaphp

1public void DelActivityMch() throws Exception{2  // 加载商户私钥（privateKey：私钥字符串）3  PrivateKey merchantPrivateKey = PemUtil4          .loadPrivateKey(new ByteArrayInputStream(privateKey.getBytes("utf-8")));56  // 加载平台证书（mchId：商户号,mchSerialNo：商户证书序列号,apiV3Key：V3秘钥）7  AutoUpdateCertificatesVerifier verifier = new AutoUpdateCertificatesVerifier(8          new WechatPay2Credentials(mchId, new PrivateKeySigner(mchSerialNo, merchantPrivateKey)),apiV3Key.getBytes("utf-8"));910  CloseableHttpClient httpClient = HttpClients.createDefault();11  // 初始化httpClient12  httpClient = WechatPayHttpClientBuilder.create()13          .withMerchant(mchId, mchSerialNo, merchantPrivateKey)14          .withValidator(new WechatPay2Validator(verifier)).build();1516  //请求URL17  HttpPost httpPost = new HttpPost(";);18  // 请求body参数19  String reqdata = "{"20          + "\"merchant_id_list\": ["21          + "\"100123456\","22          + "\"100123457\""23          + "],"24          + "\"delete_request_no\":\"100002322019090134234sfdf\""25          + "}";26  StringEntity entity = new StringEntity(reqdata,"utf-8");27  entity.setContentType("application/json");28  httpPost.setEntity(entity);29  httpPost.setHeader("Accept", "application/json");3031  //完成签名并执行请求32  CloseableHttpResponse response = httpClient.execute(httpPost);3334  try {35      int statusCode = response.getStatusLine().getStatusCode();36      if (statusCode == 200) { //处理成功37          System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));38      } else if (statusCode == 204) { //处理成功，无返回Body39          System.out.println("success");40      } else {41          System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));42          throw new IOException("request failed");43      }44  } finally {45      response.close();46  }47}

重要入参说明：

activity_id：活动ID。

A：支付有礼活动的曝光商户号必须是商家券归属商户号的同品牌。同品牌商户号是指同一企业/集团/品牌/公司旗下，如果存在多个微信支付商户号，该企业/集团/品牌/公司可以授权财付通支付科技有限公司将其旗下的多个商户号创建为同品牌商户号组合。主要用于更便利使用免充值营销产品功能，包括开通产品权限、配置组合内商户号为可用商户、配置活动后可用商户免审核等。

A：支付有礼中投放批次的校验，请按照以下几点排查：

单张券/券包中所有的券开始时间需早于支付有礼活动的开始时间，结束时间需晚于支付有礼的结束时间。如果批次为上传code模式，需先上传code再投放到支付有礼。添加券包时，库存、限领和归属商户号需要保持一致。曝光商户号、批次的归属商户号需要全部为同品牌。

A：间隔需要小于31536000s，即需要小于365天。

A：查询活动发券商户号API才会有这个字段返回，接口文档地址。

以上内容是支付有礼简介和使用流程，如有不明白之处可以与我们咨询。