開發(fā)指引

1. 接口規(guī)則

為了在保證支付安全的前提下，帶給商戶簡單、一致且易用的開發(fā)體驗，我們推出了全新的微信支付APIv3接口。該版本API的具體規(guī)則請參考“APIv3接口規(guī)則”

2. 開發(fā)環(huán)境搭建

為了幫助開發(fā)者調(diào)用開放接口，我們提供了Java、PHP、GO語言版本的開發(fā)庫，封裝了簽名生成、簽名驗證、敏感信息加/解密、媒體文件上傳等基礎功能

JAVA Golang PHP

2.1.1. 使用條件

? WechatPay merchant account

? Java 1.8 or later

? Maven or Gradle;

? 0.4.6 or later version of the Java httpClient SDK

2.1.2. 安裝

Gradle：在你的 build.gradle 文件中加入如下的依賴

implementation 'com.github.wechatpay-apiv3:wechatpay-apache-httpclient:0.4.7'

Maven：在 pom.xml 文件中加入以下依賴

<dependency>
<groupId>com.github.wechatpay-apiv3</groupId>
<artifactId>wechatpay-apache-httpclient</artifactId>
<version>0.4.7</version>
</dependency>

2.1.3. 初始化

用WechatPayHttpClientBuilder初始化創(chuàng)建一個httpClient，httpClient將被用于發(fā)送請求調(diào)用微信支付接口。用CertificatesManager初始化一個verifier實例，用于驗證簽名。


    private CloseableHttpClient httpClient;
    private CertificatesManager certificatesManager;
    private Verifier verifier;

    @Before
    //initialize verifier and build httpClient
    public void setup() throws GeneralSecurityException, IOException, HttpCodeException, NotFoundException {

        PrivateKey merchantPrivateKey = PemUtil.loadPrivateKey(privateKey);
        certificatesManager = CertificatesManager.getInstance();
        certificatesManager.putMerchant(merchantId, new WechatPay2Credentials(merchantId,
                        new PrivateKeySigner(merchantSerialNumber, merchantPrivateKey)),
                apiV3Key.getBytes(StandardCharsets.UTF_8));
        verifier = certificatesManager.getVerifier(merchantId);
        WechatPayHttpClientBuilder builder = WechatPayHttpClientBuilder.create()
                .withMerchant(merchantId, merchantSerialNumber, merchantPrivateKey)
                .withValidator(new WechatPay2Validator(verifier));
        httpClient = builder.build();
    }

2.1.4. 通用功能

敏感信息加密敏感信息解密


    @Test
    public void encryptedTest() throws IllegalBlockSizeException {
        String text = "helloWorld";
        String transformation = "RSA/ECB/PKCS1Padding";
        String encryptedText = RsaCryptoUtil.encrypt(text, verifier.getValidCertificate(), transformation);
        System.out.println(encryptedText);
    }


    @Test
    public void decryptedTest() throws BadPaddingException {
        String encryptedText = OBTgun4jiN13n3nmSg8v0MNDMy3mbs380yq4GrgO8vwCqXnvrWxwo3jUCNY2UY7MIOtv/SD8ke64MxcSB0hn5EzKv1LOLprI3NvvmNLS4C3SBulxpZG62RYp1+8FgwAI4M//icXvjtZWVH4KVDg==";
        String transformation = "RSA/ECB/PKCS1Padding";
        String decryptedText = RsaCryptoUtil.decrypt(encryptedText, PemUtil.loadPrivateKey(privateKey), transformation);
        assert("helloWorld".equals(decryptedText));
    }

2.2.1. 使用條件

? WechatPay merchant account

? GO SDK 0.2.13 or later version

2.2.2. 安裝

1. 使用 Go Modules 管理你的項目

如果你的項目還不是使用 Go Modules 做依賴管理，在項目根目錄下執(zhí)行：

go mod init

2. 無需 clone 倉庫中的代碼，直接在項目目錄中執(zhí)行：

go get -u github.com/wechatpay-apiv3/wechatpay-go

來添加依賴，完成 go.mod 修改與 SDK 下載

2.2.3. 初始化

初始化Client并向Client中加載商戶號，私鑰，API V3 key，商戶證書和序列號，用于之后發(fā)送接口請求。


import (
   "context"
   "crypto/rand"
   "crypto/rsa"
   "crypto/x509"
   "encoding/base64"
   "fmt"
   "github.com/wechatpay-apiv3/wechatpay-go/core"
   "github.com/wechatpay-apiv3/wechatpay-go/core/option"
   "github.com/wechatpay-apiv3/wechatpay-go/utils"
   "log"
   "net/http"
)

var (
   mchID                      = ""                  // merchant id
   mchCertificateSerialNumber = "" // merchant certificate serial number
   mchAPIv3Key                = ""                  // merchant api v3 key
   header                     = make(http.Header)
   ctx                        = context.Background()
   cert                       *x509.Certificate
   mchPrivateKey              *rsa.PrivateKey
   client                     *core.Client
   err                        error
)

func setup() {
   //Load platform certificate
   cert, err = utils.LoadCertificateWithPath("Path/To/Platform/Cert")
   if err != nil {
      log.Fatal(err)
   }
   // Load private key
   mchPrivateKey, err = utils.LoadPrivateKeyWithPath("Path/To/Private/Key")
   if err != nil {
      log.Fatal("load merchant private key error")
   }
   // Initialize client which is capable to update platform certificate periodically
   opts := []core.ClientOption{
      option.WithWechatPayAutoAuthCipher(mchID, mchCertificateSerialNumber, mchPrivateKey, mchAPIv3Key),
   }
   client, err = core.NewClient(ctx, opts...)
   if err != nil {
      log.Fatalf("new wechat pay client err:%s", err)
   }
}

2.2.4. 通用功能

敏感信息加密敏感信息解密


func Encryption(t *testing.T) {
	var testRSACryptoUtilMchCertificateStr = `-----BEGIN CERTIFICATE-----
	-----END CERTIFICATE-----`
	testRSACryptoUtilCertificate, _ = LoadCertificate(testRSACryptoUtilMchCertificateStr)
   const message = "hello world"
   
   // 使用OAEP padding方式對證書加密
   ciphertext, _ := EncryptOAEPWithCertificate(message, testRSACryptoUtilCertificate)
   
   // 使用PKCS1 padding對證書加密
   ciphertext, _ := EncryptPKCS1v15WithCertificate(message, testRSACryptoUtilCertificate)
}


func TestDecryption(t *testing.T) {
	var testRSACryptoUtilPrivateKeyStr = `-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----`
	testRSACryptoUtilPrivateKey, _ = LoadPrivateKey(testingKey(testRSACryptoUtilPrivateKeyStr))
	const ciphertext = ""

	// 使用PKCS1 padding進行私鑰解密
	decryptMessage, _ := DecryptPKCS1v15(ciphertext, testRSACryptoUtilPrivateKey)

	// 使用OAEP padding方式私鑰解密
	decryptMessage, _ := DecryptOAEP(ciphertext, testRSACryptoUtilPrivateKey)
}

2.3.1. 使用條件

? Guzzle 7.0，PHP >= 7.2.5

? Guzzle 6.5，PHP >= 7.1.2

? 項目已支持 PHP 8。

2.3.2. 安裝

推薦使用 PHP 包管理工具 Composer 安裝 SDK：

composer require wechatpay/wechatpay

2.3.3. 初始化

初始化Client并向Client中加載商戶號，私鑰，API V3 key，商戶證書和序列號，用于之后發(fā)送接口請求。


require_once('vendor/autoload.php');

use WeChatPay\Builder;
use WeChatPay\Crypto\Rsa;
use WeChatPay\Util\PemUtil;

$merchantId = '190000****';
$merchantPrivateKeyFilePath = 'file:///path/to/merchant/apiclient_key.pem';
$merchantPrivateKeyInstance = Rsa::from($merchantPrivateKeyFilePath, Rsa::KEY_TYPE_PRIVATE);
$merchantCertificateSerial = '3775B6A45ACD588826D15E583A95F5DD********';
$platformCertificateFilePath = 'file:///path/to/wechatpay/cert.pem';
$platformPublicKeyInstance = Rsa::from($platformCertificateFilePath, Rsa::KEY_TYPE_PUBLIC);
$platformCertificateSerial = PemUtil::parseCertificateSerialNo($platformCertificateFilePath);

// init a API V3 instance
$instance = Builder::factory([
    'mchid'      => $merchantId,
    'serial'     => $merchantCertificateSerial,
    'privateKey' => $merchantPrivateKeyInstance,
    'certs'      => [
        $platformCertificateSerial => $platformPublicKeyInstance,
    ],
]);

2.3.4. 通用功能

敏感信息加密敏感信息解密


    $encryptor = static function(string $msg) use ($platformPublicKeyInstance): string {
        return Rsa::encrypt($msg, $platformPublicKeyInstance, OPENSSL_PKCS1_PADDING);
    };
	$encryptedMsg =  $encryptor('HelloWorld');


    $decryptor = static function(string $msg) use ($merchantPrivateKeyInstance): string {
        return Rsa::decrypt($msg, $merchantPrivateKeyInstance, OPENSSL_PKCS1_PADDING);
    };
	$decryptedMsg =  $decryptor('ciphertext');

3. 業(yè)務時序圖

3.1. 業(yè)務時序圖

免密支付：

驗密支付：

3.2. API接入示例

文檔展示了如何使用微信支付服務端 SDK 快速接入掃碼支付產(chǎn)品，完成與微信支付對接的部分。

注意

? 文檔中的代碼示例是用來闡述 API 基本使用方法，代碼中的示例參數(shù)需替換成商戶自己賬號及請求參數(shù)才能跑通。

? 以下接入步驟僅提供參考，請商戶結合自身業(yè)務需求進行評估、修改。

3.2.1 下單

步驟說明：通過本接口提交微信支付付款碼支付訂單，需要掃描用戶付款碼后調(diào)用。

代碼示例

JAVA Go PHP


    @Test
    //Call Quick Pay Order API
    public void quickPayOrderTest() throws IOException {
		String requestBody = String.join("\n" ,
                		"{" ,
                        "'sp_appid': 'wxdace645e0bc2c424'," ,
                        "'sp_mchid': '10000100'," ,
                        "'sub_mchid': '20000100'," ,
                        "'out_trade_no': '20150806125346'," ,
                        "'merchant_category_code': '4111'," ,
                        "'payer': {" ,
                        "'auth_code': '134650720866361395'" ,
                        "}," ,
                        "'trade_type': 'MICROPAY'," ,
                        "'amount': {" ,
                        "'total': 1," ,
                        "'currency': 'HKD'" ,
                        "}," ,
                        "'attach': 'Payment Test'," ,
                        "'description': 'Image Store - Tencent Building in Shenzhen - QQ Doll'," ,
                        "'goods_tag': '1234'," ,
                        "'limit_pay': 'no_credit'," ,
                        "'detail': {" ,
                        "'cost_price': 1," ,
                        "'receipt_id': '1234'," ,
                        "'goods_detail': [{" ,
                        "'goods_id': 'iphone6s_16G'," ,
                        "'wxpay_goods_id': '3405'," ,
                        "'goods_name': 'iPhone6s 16G'," ,
                        "'quantity': 1," ,
                        "'price': 1" ,
                        "}]" ,
                        "}," ,
                        "'scene_info': {" ,
                        "'payer_client_ip': '14.23.150.211'," ,
                        "'device_ip': '59.37.125.32'," ,
                        "'device_id': '013467007045764'," ,
                        "'operator_id': 'P001'," ,
                        "'store_info': {" ,
                        "'id': 'SZTX001'," ,
                        "'name': 'Tencent Building Branch'," ,
                        "'address': 'Nanshan District, Shenzhen, Guangdong'" ,
                        "}" ,
                        "}" ,
                        "}").replace("'","\"");
        HttpPost httpPost = new HttpPost("https://apihk.mch.weixin.qq.com/v3/global/micropay/transactions/pay");
        httpPost.addHeader("Accept", "application/json");
        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
        httpPost.setEntity(new StringEntity(requestBody));
        CloseableHttpResponse response = httpClient.execute(httpPost);
        //Process the response 
    }


func quickPayOrder() {
   requestBody := `{
	"sp_appid": "wxdace645e0bc2c424",
	"sp_mchid": "10000100",
	"sub_mchid": "20000100",
	"out_trade_no": "20150806125346",
	"merchant_category_code": "4111",
	"payer": {
		"auth_code": "134650720866361395"
	},
	"trade_type": "MICROPAY",
	"amount": {
		"total": 1,
		"currency": "HKD"
	},
	"attach": "Payment Test",
	"description": "Image Store - Tencent Building in Shenzhen - QQ Doll",
	"goods_tag": "1234",
	"limit_pay": "no_credit",
	"detail": {
		"cost_price": 1,
		"receipt_id": "1234",
		"goods_detail": [{
			"goods_id": "iphone6s_16G",
			"wxpay_goods_id": "3405",
			"goods_name": "iPhone6s 16G",
			"quantity": 1,
			"price": 1
		}]
	},
	"scene_info": {
		"payer_client_ip": "14.23.150.211",
		"device_ip": "59.37.125.32",
		"device_id": "013467007045764",
		"operator_id": "P001",
		"store_info": {
			"id": "SZTX001",
			"name": "Tencent Building Branch",
			"address": "Nanshan District, Shenzhen, Guangdong"
		}
	}
}`
   result, err := client.Post(ctx, "https://apihk.mch.weixin.qq.com/v3/global/micropay/transactions/pay", requestBody)
   if err != nil {
      // Process error
   }
   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
}


// Call QuickPay Order API
public function quickPayOrder($instance){
    try {
        $resp = $instance
            ->chain('/v3/global/micropay/transactions/pay')
            ->post(['json' => [
                'sp_appid'     => 'wxdace645e0bc2c424',
                'sp_mchid'     => '10000100',
                'sub_mchid'    => '20000100',
                'out_trade_no' => '20150806125346',
                'merchant_category_code' => '4111',
                'payer'          => [
                    'auth_code'=> '134650720866361395',
				],
				'trade_type'   => 'MICROPAY',
				'amount'       => [
            	'total'    => 1,
            	'currency' => 'USD'
        		],
            	'attach'       => 'QR code test',
            	'description'  => 'Image形象店-深圳騰大-QQ公仔',
				'goods_tag'    => '1234',
				'limit_pay'       => 'no_credit'
        	]]);

    echo $resp->getStatusCode(), PHP_EOL;
    echo $resp->getBody(), PHP_EOL;
} catch (Exception $e) {
        // EXception handling
        echo $e->getMessage(), PHP_EOL;
        if ($e instanceof \GuzzleHttp\Exception\RequestException && $e->hasResponse()) {
            $r = $e->getResponse();
            echo $r->getStatusCode() . ' ' . $r->getReasonPhrase(), PHP_EOL;
            echo $r->getBody(), PHP_EOL, PHP_EOL, PHP_EOL;
        }
    echo $e->getTraceAsString(), PHP_EOL;
    }
}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

重要參數(shù)：

out_trade_no: 商戶系統(tǒng)內(nèi)部訂單號

auth_code: 掃碼支付授權碼，即用戶打開微信錢包顯示的支付對應的數(shù)字

其他重要參數(shù)請前往提交付款碼支付API文檔頁面參考。

3.2.2 查詢訂單

步驟說明：商戶在用戶下單一定時間后，需主動進行查單以確認訂單狀態(tài)。

代碼示例

JAVA Go PHP


    @Test
    //Call query order API
    public void queryOrderTest() throws IOException {
        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/transactions/id/" +
                "4200123456789000?sub_mchid=100012321&sp_mchid=1900000000");
        httpGet.addHeader("Accept", "application/json");
        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
        CloseableHttpResponse response = httpClient.execute(httpGet);
        //Process the response 
    }


//Call query order API
func queryOrder() {
   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/transactions/id/4200000000000000?sub_mchid=100012321&sp_mchid=1900000000")
   if err != nil {
      // Process error
   }
   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
}


// Call query order API
public function queryOrder($instance)
{
    try {
        $resp = $instance
            ->v3->global->transactions->outTradeNo->_out_trade_no_
            ->get([
                    'query' => [
                'sp_mchid'     => '1900000000',
                'sub_mchid'    => '100012321',
                    ],
                    'out_trade_no' => 'YX0001'
                ]
            );

        echo $resp->getStatusCode(), PHP_EOL;
        echo $resp->getBody(), PHP_EOL;
    } catch (Exception $e) {
        // Exception handling
	}
}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

重要參數(shù)：

id：微信支付訂單號

out_trade_no：商戶內(nèi)部訂單號

可以用上述任一訂單號進行查詢。其他重要參數(shù)請前往查詢訂單API文檔頁面參考。

3.2.3 申請退款

步驟說明：支付完成支付狀態(tài)為SUCCESS后，可以調(diào)用該接口提交退款請求。

代碼示例

JAVA Go PHP


    @Test
    //Call Refund API
    public void refundTest() throws IOException {
		String refundBody = String.join("\n" ,
                		"{" ,
                        "'sp_appid': 'wx2421b1c4370ec43b', " ,
                        "'sp_mchid': '10000100'," ,
                        "'sub_mchid': '20000100'," ,
                        "'transaction_id': '1008450740201411110005820873'," ,
                        "'out_refund_no': 'R20150806125346'," ,
                        "    'amount' : {" ,
                        "        'refund': 5," ,
                        "        'total':10," ,
                        "         'currency':'HKD'" ,
                        "    }," ,
                        "    'reason': 'The item has been sold out.'," ,
                        "    'source': 'REFUND_SOURCE_UNSETTLED_FUNDS'" ,
                        "}").replace("'","\"");
        HttpPost httpPost = new HttpPost("https://apihk.mch.weixin.qq.com/v3/global/refunds");
        httpPost.addHeader("Accept", "application/json");
        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
        httpPost.setEntity(new StringEntity(refundBody));
        CloseableHttpResponse response = httpClient.execute(httpPost);
        //Process the response 
    }


func refund() {
   refundRequestBody := `{
    "sp_appid": "wx2421b1c4370ec43b",
    "sp_mchid": "10000100",
    "sub_mchid": "20000100",
    "transaction_id": "1008450740201411110005820873",
    "out_refund_no": "R20150806125346",
    "amount" : {
        "refund": 50,
        "total":100,
         "currency":"HKD"
    },
    "reason": "The item has been sold out",
    "source": "REFUND_SOURCE_UNSETTLED_FUNDS"
}`
   result, err := client.Post(ctx, "https://apihk.mch.weixin.qq.com/v3/global/refunds", refundRequestBody)
   if err != nil {
      // Process error
   }
   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
}


// Call Refund API
public function refundOrder($instance){
    try {
        $resp = $instance
            ->chain('v3/global/refunds')
            ->post(['json' => [
                'sp_appid'     => 'wxdace12300000000',
                'sp_mchid'     => '1900000000',
                'sub_mchid'    => '100012321',
                'out_trade_no' => 'YX0001',
                "out_refund_no"=> "REFUNDYX0001",
                'amount'       => [
                    'refund'   => 1,
                    'total'    => 1,
                    'currency' => 'USD'
                ]
            ]]);
        echo $resp->getStatusCode(), PHP_EOL;
        echo $resp->getBody(), PHP_EOL;
    } catch (Exception $e) {
        // Exception handling
    }
}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

重要參數(shù)：

out_trade_no: 商戶內(nèi)部訂單號

transaction_id: 微信訂單號

out_refund_no: 商戶內(nèi)部退款單號，應與訂單號一一對應

notify_url: 退款結果接收地址

其他重要參數(shù)請前往申請退款API文檔頁面參考。

3.2.4 查詢單筆退款

步驟說明：提交退款申請后，通過調(diào)用該接口查詢退款狀態(tài)。

代碼示例

JAVA Go PHP


    @Test
    //Call Query Refund API
    public void querySingleRefundTest() throws IOException {
        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/refunds/out-refund-no/RYX001?sub_mchid=100012321&sp_mchid=1900000000");
        httpGet.addHeader("Accept", "application/json");
        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
        CloseableHttpResponse response = httpClient.execute(httpGet);
        //Process the response 
    }


//Query single refund API
func querySingleRefund() {
   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/refunds/out-refund-no/REFUNDYX001?sub_mchid=100012321&sp_mchid=1900000000")
   if err != nil {
      // Process error
   }
   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
}


// Call Query Refund API
public function queryRefund($instance){
    try {
        $resp = $instance
            ->v3->global->refunds->outRefundNo->_out_refund_no_
            ->get([
                'query' => [
                    'sp_mchid' => '1900000000',
                    'sub_mchid'=> '100012321'
                ],
                'out_refund_no' => 'REFUNDYX0001'
            ]);

        echo $resp->getStatusCode(), PHP_EOL;
        echo $resp->getBody(), PHP_EOL;
    } catch (Exception $e) {
        // Exception handling
    }
}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

重要參數(shù)：

out_trade_no: 商戶內(nèi)部訂單號

refund_id：微信支付退款單號

其他重要參數(shù)請前往查詢單筆退款API文檔頁面參考。

3.2.5 查詢所有退款

步驟說明：提交退款申請后，通過調(diào)用該接口查詢一筆訂單下對應的全部退款信息。

代碼示例

JAVA Go PHP


    @Test
    //Call Query All Refund API
    public void queryAllRefundTest() throws IOException {
        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/refunds" +
                "?out_trade_no=YX202111100020&count=10&offset=0&sp_mchid=1900000000&sub_mchid=100012321");
        httpGet.addHeader("Accept", "application/json");
        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
        CloseableHttpResponse response = httpClient.execute(httpGet);
        //Process the response 
    }


//Query all refund API
func queryAllRefund() {
   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/refunds/out-refund-no/out_trade_no=YX001&count=10&offset=0&sp_mchid=1900000000&sub_mchid=100012321")
   if err != nil {
      // Process error
   }
   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
}


// Call Query All Refund API
public function queryAllRefund($instance){
    try {
        $resp = $instance
            ->v3->global->refunds
            ->get([
                'query' => [
                    'out_trade_no' => 'YX001',
                    'count' => 10,
                    'offset' => 0,
                    'sp_mchid' => '1900000000',
                    'sub_mchid'=> '100012321'
                ]
            ]);

        echo $resp->getStatusCode(), PHP_EOL;
        echo $resp->getBody(), PHP_EOL;
    } catch (Exception $e) {
        // Exception handling
    }
}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

重要參數(shù)：

out_trade_no: 商戶內(nèi)部訂單號

transaction_id: 微信訂單號

offset: 分頁起始位置

count: 單頁返回的記錄數(shù)，最大20條記錄.

其他重要參數(shù)請前往查詢所有退款API文檔頁面參考。

3.2.6 下載對賬單

步驟說明：商戶每天可以通過調(diào)用該接口可以下載歷史交易賬單，通過對帳單核對后可以校對更正支付信息。

代碼示例

JAVA Go PHP


    @Test
    //Downloading Reconciliation API
    public void downloadReconTest() throws IOException {
        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/statements?date=20220401&mchid=1900000000");
        httpGet.addHeader("Accept", "application/json");
        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
        CloseableHttpResponse response = httpClient.execute(httpGet);
        //Process the response 
    }


//Download recon file API
func downloadReconFile() {
   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/statements?date=20220401&mchid=1900000000")
   if err != nil {
      // Process error
   }
   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
}


//Downloading Reconciliation API
public function downloadReconFile($instance){
    try {
        $resp = $instance
            ->v3->global->statements
            ->get([
                'query' => [
                    'date' => '20220401',
                    'mchid' => '1900000000'
                ]
            ]);

        echo $resp->getStatusCode(), PHP_EOL;
        echo $resp->getBody(), PHP_EOL;
    } catch (Exception $e) {
        // Exception handling
    }
}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

重要參數(shù)：

date: 賬單日期, 格式：20180103

其他重要參數(shù)請前往下載對賬單API文檔頁面參考。

3.2.7 撤銷訂單

步驟說明：下單超過5分鐘后，可以調(diào)用該接口對下單未支付的訂單進行關單操作，以便商戶更換訂單號重新下單發(fā)起支付或商戶系統(tǒng)退出不再受理后避免用戶繼續(xù)支付。

代碼示例

JAVA Go PHP


    @Test
    //Call revoke order API
    public void RevokeOrderTest() throws IOException {
		String revokeBody = String.join("\n" ,
                "{" ,
                "    'sp_mchid': '10000100'," ,
                "    'sub_mchid': '20000100'" ,
                "}").replace("'","\"");
        HttpPost httpPost = new HttpPost("https://apihk.mch.weixin.qq.com/v3/global/micropay/transactions/out-trade-no/YX001/reverse");
        httpPost.addHeader("Accept", "application/json");
        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
        httpPost.setEntity(new StringEntity(revokeBody));
        CloseableHttpResponse response = httpClient.execute(httpPost);
        //Process the response 
    }


//Call revoke order API
func revokeOrder() {
   revokeOrderBody := `{
    "sp_mchid": "10000100",
    "sub_mchid": "20000100"
   }`
   result, err := client.Post(ctx, "https://apihk.mch.weixin.qq.com/v3/global/micropay/transactions/out-trade-no/YX001/close", revokeOrderBody)
   if err != nil {
      // Process error
   }
   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
}


// Call Revoke order API
public function revokeOrder($instance){
    try {
        $resp = $instance
            ->v3->global->micropay->transactions->outTradeNo->_out_trade_no_->reverse
            ->post(['json' => [
                'sp_mchid'     => '10000100',
                'sub_mchid'    => '20000100'
                ],
                'out_trade_no' => 'YX0001'
            ]);

        echo $resp->getStatusCode(), PHP_EOL;
        echo $resp->getBody(), PHP_EOL;
    } catch (Exception $e) {
        // Exception handling
    }
}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

重要參數(shù)：

out_trade_no: 商戶內(nèi)部訂單號

transaction_id: 微信支付訂單號

out_refund_no: 商戶內(nèi)部退款單號，應與訂單號一一對應

notify_url: 退款結果接收地址

可以用上述任一訂單號進行查詢。其他重要參數(shù)請前往撤銷訂單API文檔頁面參考。

3.2.8 下載平臺證書

步驟說明：在調(diào)用其他接口之前，需要調(diào)用該接口下載平臺證書用于對返回消息進行驗簽和返回消息中的加密字段進行解密。

代碼示例

JAVA Go PHP


    @Test
    //Call certificate downloading API
    public void certDownloadingTest() throws IOException {
        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/certificates");
        httpGet.addHeader("Accept", "application/json");
        httpGet.addHeader("Content-type", "application/json; charset=utf-8");

        CloseableHttpResponse response = httpClient.execute(httpGet);
        //Process the response 
//Get the response body: EntityUtils.toString(response.getEntity());
//Get the response status code: response.getStatusLine().getStatusCode();

        //Instead of calling the API to download platform certificate，
        //We also recommend use the certificateMenager to get the valid certificate
        verifier.getValidCertificate();
    }


//Calling download certificate API
func downloadCert() {
   result, err := client.Get((ctx, "https://apihk.mch.weixin.qq.com/v3/global/certificates"))
   if err != nil {
      if core.IsAPIError(err, "INVALID_REQUEST") {
         //Process invalid request
      }
      // Process other error
   }
   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
}


// Call download certificate API
public function downloadCert($instance){
    $resp = $instance->chain('v3/global/certificates')->get(
        ['debug' => true] // debug mode，https://docs.guzzlephp.org/en/stable/request-options.html#debug
    );
    echo $resp->getBody(), PHP_EOL;
}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

重要參數(shù)：無

其他重要參數(shù)請前往下載平臺證書API文檔頁面參考。

3.2.9 退款通知

步驟說明：退款狀態(tài)改變后，微信會把相關退款結果發(fā)送給商戶。

注意

? 同樣的通知可能會多次發(fā)送給商戶系統(tǒng)。商戶系統(tǒng)必須能夠正確處理重復的通知。推薦的做法是，當商戶系統(tǒng)收到通知進行處理時，先檢查對應業(yè)務數(shù)據(jù)的狀態(tài)，并判斷該通知是否已經(jīng)處理。如果未處理，則再進行處理；如果已處理，則直接返回結果成功。在對業(yè)務數(shù)據(jù)進行狀態(tài)檢查和處理之前，要采用數(shù)據(jù)鎖進行并發(fā)控制，以避免函數(shù)重入造成的數(shù)據(jù)混亂。

? 如果在所有通知頻率(4小時)后沒有收到微信側回調(diào)，商戶應調(diào)用查詢訂單接口確認訂單狀態(tài)。

特別提醒：機構系統(tǒng)對于支付結果通知的內(nèi)容一定要做簽名驗證,并校驗返回的訂單金額是否與商戶側的訂單金額一致，防止數(shù)據(jù)泄露導致出現(xiàn)“假通知”，造成資金損失。

3.2.9.1 通知規(guī)則

退款狀態(tài)改變后，微信會把相關退款結果發(fā)送給商戶。

對后臺通知交互時，如果微信收到應答不是成功或超時，微信認為通知失敗，微信會通過一定的策略定期重新發(fā)起通知，盡可能提高通知的成功率，但微信不保證通知最終能成功。（通知頻率為15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 總計 24h4m）

3.2.9.2 通知報文

退款結果通知是以“POST”方法訪問商戶設置的通知url，通知的數(shù)據(jù)以“JSON”格式通過請求主體（BODY）傳輸。通知的數(shù)據(jù)包括了加密的退款結果詳情。

下面詳細描述證書解密的流程

1、從商戶平臺上獲取商戶的密鑰，記為“key”。

2、針對“algorithm”中描述的算法（目前為AEAD_AES_256_GCM），取得對應的參數(shù)“nonce”和“associated_data”。

3、使用“key”、“nonce”和“associated_data”對數(shù)據(jù)密文“ciphertext”進行解密（需要先對ciphertext做base64解碼，然后再解密），得到證書內(nèi)容

注意

AEAD_AES_256_GCM算法的接口細節(jié)，請參考rfc5116。微信支付使用的密鑰key長度為32個字節(jié)，隨機串nonce長度12個字節(jié)，associated_data長度小于16個字節(jié)并可能為空。

3.2.9.3 通知簽名

加密不能保證通知請求來自微信。微信會對發(fā)送給商戶的通知進行簽名，并將簽名值放在通知的HTTP頭Wechatpay-Signature。商戶應當驗證簽名，以確認請求來自微信，而不是其他的第三方。簽名驗證的算法請參考《微信支付API V3簽名驗證》。

3.2.9.4 回調(diào)示例

退款通知


{
	"id": "EV-2018022511223320873",
	"create_time": "2018-06-08T10:34:56+08:00",
	"resource_type": "encrypt-resource",
	"event_type": "REFUND.SUCCESS",
	"summary": "退款成功",
	"resource": {
		"original_type": "refund",
		"algorithm": "AEAD_AES_256_GCM",
		"ciphertext": "...",
		"associated_data": "",
		"nonce": "..."
	}
}

商戶對resource對象進行解密后，得到的資源對象示例


{
    "sp_mchid": "1900000100",
    "sub_mchid": "1900000109",
    "transaction_id": "1008450740201411110005820873",
    "out_trade_no": "20150806125346",
    "refund_id": "50200207182018070300011301001",
    "out_refund_no": "7752501201407033233368018",
    "refund_status": "SUCCESS",
    "success_time": "2018-06-08T10:34:56+08:00",
    "recv_account": "招商銀行信用卡0403",
    "fund_source": "REFUND_SOURCE_UNSETTLED_FUNDS",
    "amount" : {
        "total": 528800,
        "currency": "HKD",
        "refund": 528800,
        "payer_total": 528800,
        "payer_refund": 528800,
        "payer_currency": "HKD",
        "exchange_rate" : {
            "type": "SETTLEMENT_RATE",
            "rate": 100000000
        }
    }
}

3.2.9.5 通知應答

退款通知http應答碼為200或204才會當作正常接收，當回調(diào)處理異常時，應答的HTTP狀態(tài)碼應為500，或者4xx。

注意

當商戶后臺應答失敗時，微信支付將記錄下應答的報文，建議商戶按照以下格式返回。

其他重要參數(shù)請前往退款通知API文檔頁面參考。

3.2.10 查詢資金結算明細

步驟說明：商戶在交易完結之后，可按結算日期查詢已結算資金明細（sette_state為SETTLED），也可以查詢未結算資金明細（sette_state為UNSETTLE）。

注意

該接口供跨境收單機構/直連商戶使用，特別是，日本/澳門機構商戶若開通香港錢包業(yè)務，需要對接該接口。

代碼示例

JAVA Go PHP


    @Test
    //Query Settlement API
    public void querySettlementTest() throws IOException {
        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/settle/settlements" +
                "?sub_mchid=100012321&settle_state=SETTLED&settle_start_date=20221225" +
                "&settle_end_date=20221226&offset=10&limit=5");
        httpGet.addHeader("Accept", "application/json");
        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
        CloseableHttpResponse response = httpClient.execute(httpGet);
        //Process the response 
    }


//Query settlement API
func querySettlement() {
   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/settle/settlements?sub_mchid=100012321&settle_state=SETTLED&settle_start_date=20221225&settle_end_date=20221226&offset=10&limit=5")
   if err != nil {
      // Process error
   }
   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
}


//Querying Settlement Info API
public function querySettlementInfo($instance){
    try {
        $resp = $instance
            ->v3->global->settle->settlements
            ->get(['query' => [
                'sub_mchid' => '100012321',
                'settle_state' => 'SETTLED',
                'settle_start_date' => '20221225',
                'settle_end_date' => '20221226',
                'offset' => '10',
                'limit' => '5'
            ]]);

        echo $resp->getStatusCode(), PHP_EOL;
        echo $resp->getBody(), PHP_EOL;
    } catch (\Exception $e) {
        // Exception handling
    }
}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

重要參數(shù)：

settle_state：資金結算狀態(tài)，枚舉值：

SETTLED：已結算

UNSETTLE：未結算

其他重要參數(shù)請前往查詢資金結算明細API文檔頁面參考。

视频一区二区三区自拍_千金肉奴隷1985未删减版在线观看_国产成人黄色视频在线播放_少女免费播放片高清在线观看_国产精品v欧美精品v

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

支付產(chǎn)品

資金類產(chǎn)品

其他產(chǎn)品

開發(fā)指引

1. 接口規(guī)則

2. 開發(fā)環(huán)境搭建

2.1.1. 使用條件

2.1.2. 安裝

2.1.3. 初始化

2.1.4. 通用功能

2.2.1. 使用條件

2.2.2. 安裝

2.2.3. 初始化

2.2.4. 通用功能

2.3.1. 使用條件

2.3.2. 安裝

2.3.3. 初始化

2.3.4. 通用功能

3. 業(yè)務時序圖

3.1. 業(yè)務時序圖

3.2. API接入示例

3.2.1 下單

3.2.2 查詢訂單

3.2.3 申請退款

3.2.4 查詢單筆退款

3.2.5 查詢所有退款

3.2.6 下載對賬單

3.2.7 撤銷訂單

3.2.8 下載平臺證書

3.2.9 退款通知

3.2.9.1 通知規(guī)則

3.2.9.2 通知報文

3.2.9.3 通知簽名

3.2.9.4 回調(diào)示例

3.2.9.5 通知應答

3.2.10 查詢資金結算明細