开发指引-代扣服务切卡组件 | 微信支付合作伙伴平台文档中心

返回上一层文档首页 / 开发指引

代扣服务切卡组件开发指引

1. 接口规则

为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考“APIv3接口规则”

2. 开发准备

2.1. 搭建和配置开发环境

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

测试步骤：

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

• wechatpay-java（推荐）wechatpay-apache-httpclient，适用于Java开发者。

• wechatpay-php（推荐）、wechatpay-guzzle-middleware，适用于PHP开发者

注：当前开发指引接口PHP示例代码采用wechatpay-guzzle-middleware版本

• wechatpay-go，适用于Go开发者

更多资源可前往微信支付开发者社区搜索查看

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

JAVA
PHP


@Before
public void setup() throws IOException {
    // 加载商户私钥（privateKey：私钥字符串）
    PrivateKey merchantPrivateKey = PemUtil
            .loadPrivateKey(new ByteArrayInputStream(privateKey.getBytes("utf-8")));
 
    // 加载平台证书（mchId：商户号,mchSerialNo：商户证书序列号,apiV3Key：V3密钥）
    AutoUpdateCertificatesVerifier verifier = new AutoUpdateCertificatesVerifier(
            new WechatPay2Credentials(mchId, new PrivateKeySigner(mchSerialNo, merchantPrivateKey)),apiV3Key.getBytes("utf-8"));
 
    // 初始化httpClient
    httpClient = WechatPayHttpClientBuilder.create()
            .withMerchant(mchId, mchSerialNo, merchantPrivateKey)
            .withValidator(new WechatPay2Validator(verifier)).build();
}
 
@After
public void after() throws IOException {
    httpClient.close();
}


use GuzzleHttp\Exception\RequestException;
use WechatPay\GuzzleMiddleware\WechatPayMiddleware;
use WechatPay\GuzzleMiddleware\Util\PemUtil;
use GuzzleHttp\HandlerStack;
 
// 商户相关配置，
$merchantId = '1000100'; // 商户号
$merchantSerialNumber = 'XXXXXXXXXX'; // 商户API证书序列号
$merchantPrivateKey = PemUtil::loadPrivateKey('./path/to/mch/private/key.pem'); // 商户私钥文件路径
 
// 微信支付平台配置
$wechatpayCertificate = PemUtil::loadCertificate('./path/to/wechatpay/cert.pem'); // 微信支付平台证书文件路径
 
// 构造一个WechatPayMiddleware
$wechatpayMiddleware = WechatPayMiddleware::builder()
    ->withMerchant($merchantId, $merchantSerialNumber, $merchantPrivateKey) // 传入商户相关配置
    ->withWechatPay([ $wechatpayCertificate ]) // 可传入多个微信支付平台证书，参数类型为array
    ->build();
 
// 将WechatPayMiddleware添加到Guzzle的HandlerStack中
$stack = GuzzleHttp\HandlerStack::create();
$stack->push($wechatpayMiddleware, 'wechatpay');
 
// 创建Guzzle HTTP Client时，将HandlerStack传入，接下来，正常使用Guzzle发起API请求，WechatPayMiddleware会自动地处理签名和验签
$client = new GuzzleHttp\Client(['handler' => $stack]);


/*
    Package core 微信支付api v3 go http-client 基础库，你可以使用它来创建一个client，并向微信支付发送http请求
    只需要你在初始化客户端的时候，传递credential以及validator
    credential用来生成http header中的authorization信息
    validator则用来校验回包是否被篡改
    如果http请求返回的err为nil，一般response.Body 都不为空，你可以尝试对其进行序列化
    请注意及时关闭response.Body
    注意：使用微信支付apiv3 go库需要引入相关的包，该示例代码必须引入的包名有以下信息

    "context"
    "crypto/x509"
    "fmt"
    "io/ioutil"
    "log"
    "github.com/wechatpay-apiv3/wechatpay-go/core"
    "github.com/wechatpay-apiv3/wechatpay-go/core/option"
    "github.com/wechatpay-apiv3/wechatpay-go/utils"

    */
func SetUp() (opt []option.ClientOption, err error) {
    //商户号
    mchID := ""
    //商户证书序列号
    mchCertSerialNumber := ""
    //商户私钥文件路径
    privateKeyPath := ""
    //平台证书文件路径
    wechatCertificatePath := ""

    // 加载商户私钥
    privateKey, err := utils.LoadPrivateKeyWithPath(privateKeyPath)
    if err != nil {
        log.Printf("load private err:%s", err.Error())
        return nil, err
    }
    // 加载微信支付平台证书
    wechatPayCertificate, err := utils.LoadCertificateWithPath(wechatCertificatePath)
    if err != nil {
        log.Printf("load certificate err:%s",err)
        return nil, err
    }
    //设置header头中authorization信息
    opts := []option.ClientOption{
        option.WithMerchant(mchID, mchCertSerialNumber, privateKey), // 设置商户相关配置
        option.WithWechatPay([]*x509.Certificate{wechatPayCertificate}), // 设置微信支付平台证书，用于校验回包信息用
    }
    return opts, nil
}

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

说明：

• 上面的开发库为微信支付官方开发库，其它没有审核或者控制下的第三方工具和库，微信支付不保证它们的安全性和可靠性

通过包管理工具引入SDK后，可根据下面每个接口的示例代码替换相关参数后进行快速测试

• 开发者如果想详细了解签名生成、签名验证、敏感信息加/解密、媒体文件上传等常用方法的具体代码实现，可阅读下面的详细说明：

1.签名生成

2.签名验证

3.敏感信息加解密

4.merchantPrivateKey（私钥）

5.wechatpayCertificates（平台证书）

6.APIV3Key（V3 key）

• 如想更详细的了解我们的接口规则，可查看我们的接口规则指引文档

3. 快速接入

3.1. 业务流程图

业务流程时序图：

重点步骤说明：

步骤1 配置出行乘车券

步骤2.3 出行券发放后，商户可通过《出行券切卡组件预下单API》获取拉起小程序需要的token参数。

步骤2.5 获取token后，商户可按照《拉起快捷切卡小程序》部分的描述拉起小程序

3.2. API接入（含示例代码）

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

注意：

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

3.2.1. 【服务端】出行券切卡组件预下单

步骤说明：该接口为拉起快捷切卡小程序的前置步骤，通过调用快捷切卡组件预下单API获取授权token

示例代码：

JAVA
PHP


public void BuildRelations() throws Exception{
    //请求URL
    HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/industry-coupon/tokens");
    // 请求body参数
    String reqdata = "{"
            + "\"open_id\": \"obLatjrR8kUDlj4-nofQsPAJAAFI\","
            + "\"coupon_list\": {"
            + "\"coupon_id\":\"11005526091\","
            + "\"stock_id\":16584651"
            + "}"
            + "}";
    StringEntity entity = new StringEntity(reqdata,"utf-8");
    entity.setContentType("application/json");
    httpPost.setEntity(entity);
    httpPost.setHeader("Accept", "application/json");
    //完成签名并执行请求
    CloseableHttpResponse response = httpClient.execute(httpPost);

    try {
        int statusCode = response.getStatusLine().getStatusCode();
        if (statusCode == 200) { //处理成功
            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
        } else if (statusCode == 204) { //处理成功，无返回Body
            System.out.println("success");
        } else {
            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
            throw new IOException("request failed");
        }
    } finally {
        response.close();
    }
}


try {
    $resp = $client->request(
        'POST',
        'https://api.mch.weixin.qq.com/v3/industry-coupon/tokens', //请求URL
        [
            // JSON请求体
            'json' => [
                "open_id" => "obLatjiVCpXycAp8CWjsD5oAzHQ4",
                "coupon_list" => [
                    "coupon_id" => "11005526091", 
                    "stock_id" => 16584651, 
                ]
            ],
            'headers' => [ 
                'Accept' => 'application/json'
            ]
        ]
    );
    $statusCode = $resp->getStatusCode();
    if ($statusCode == 200) { //处理成功
        echo "success,return body = " . $resp->getBody()->getContents()."\n";
    } else if ($statusCode == 204) { //处理成功，无返回Body
        echo "success";
    }
} catch (RequestException $e) {
    // 进行错误处理
    echo $e->getMessage()."\n";
    if ($e->hasResponse()) {
        echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
    }
    return;
}


func CreateActivity() {
       // 初始化客户端
    ctx := context.TODO()
    opts, err := SetUp()
    if err != nil {
        return
    }
    client, err := core.NewClient(ctx, opts...,)
    if err != nil{
        log.Printf("init client err:%s",err)
        return
    }
  //设置请求地址
  URL := "https://api.mch.weixin.qq.com/v3/marketing/paygiftactivity/unique-threshold-activity"
  //设置请求信息,此处也可以使用结构体来进行请求
  mapInfo := map[string]interface{}{
    "activity_base_info": map[string]interface{}{
      "activity_name": "良品铺子回馈活动",
      "activity_second_title": "海飞丝的券",
      "merchant_logo_url": "https://tool.oschina.net/regex.jpg",
      "background_color": "COLOR010",
      "begin_time": "2015-05-20T13:29:35+08:00",
      "end_time": "2015-05-20T13:29:35+08:00",
      "available_periods": map[string]interface{}{
        "available_time": [...]interface{}{
          map[string]interface{}{
            "begin_time": "2015-05-20T00:00:00+08:00",
            "end_time": "2015-05-20T23:59:59+08:00",
       },
      },
        "available_day_time": [...]interface{}{
          map[string]interface{}{
            "begin_day_time": "110000",
            "end_day_time": "135959",
       },
      },
     },
      "out_request_no": "100002322019090134234sfdf",
      "delivery_purpose": "OFF_LINE_PAY",
      "mini_programs_appid": "wx23232232323",
      "mini_programs_path": "/path/index/index",
    },
    "award_send_rule": map[string]interface{}{
      "transaction_amount_minimum": 100,
      "send_content": "SINGLE_COUPON",
      "award_type": "BUSIFAVOR",
      "award_list": [...]interface{}{
        map[string]interface{}{
          "stock_id": "98065001",
          "original_image_url": "https://tool.oschina.net/regex.jpg",
          "thumbnail_url": "https://tool.oschina.net/regex.jpg",
      },
     },
      "merchant_option": "MANUAL_INPUT_MERCHANT",
      "merchant_id_list": [...]interface{}{
        "10000022",
        "10000023",
     },
    },
    "advanced_setting": map[string]interface{}{
      "delivery_user_category": "DELIVERY_MEMBER_PERSON",
      "merchant_member_appid": "34567890",
      "goods_tags": [...]interface{}{
        "xxx",
        "yyy",
     },
    },
  }

  // 发起请求
  response, err := client.Post(ctx, URL, mapInfo)
  if err != nil{
    log.Printf("client post err:%s",err)
    return
  }
  // 校验回包内容是否有逻辑错误
  err = core.CheckResponse(response)
  if err != nil{
    log.Printf("check response err:%s",err)
    return
  }
  // 读取回包信息
  body, err := ioutil.ReadAll(response.Body)
  if err != nil{
    log.Printf("read response body err:%s",err)
    return
  }
  fmt.Println(string(body))
}

重要入参说明：

• open_id：openid是微信用户在appid下的唯一用户标识（appid不同，则获取到的openid就不同），可用于永久标记一个用户。openid获取方式请参考以下文档小程序获取openid、公众号获取openid、APP获取openid

• coupon_id：微信为代金券唯一分配的id。

• stock_id：批次号，微信为每个代金券批次分配的唯一id。

注意：

更多参数、响应详情及错误码请参见出行券切卡组件预下单API接口文档

3.2.2. 【客户端】出行券切卡组件预下单

步骤说明：引导切卡流程在独立的小程序中执行，调用方通过跳转小程序的方式可以快速拉起

示例代码：


let mch_code = ''; // 商户的mchCode
let token = ''; // token通过API获取

// 调用跳转小程序的接口，跳转到引导切卡组件
wx.navigateToMiniProgram({
  appId: 'wx179335ce27355ca8',
  path: `trafficCoupon/pages/index/index?mch_code=${mch_code}&token=${token}`,
  success() {
    // 跳转成功
  },
  fail() {
    // 跳转失败
  }
});

注意：

更多参数、响应详情及错误码请参见拉起快捷切卡小程序接口文档

CONTENT
1.接口规则
2. 开发准备
2.1. 搭建和配置开发环境
3.快速接入
3.1. 业务流程图
3.2. API接入（含示例代码）