### Start Coupon Stock

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/cashcoupons/README.md

Activates and starts a coupon stock, making it ready for use.

```APIDOC
## POST /v3/marketing/favor/stocks/{stock_id}/start

### Description
Activates and starts a coupon stock, making it ready for use.

### Method
POST

### Endpoint
/v3/marketing/favor/stocks/{stock_id}/start

### Parameters
#### Path Parameters
- **stock_id** (string) - Required - The ID of the coupon stock to start.

#### Query Parameters
(No query parameters documented)

#### Request Body
(No request body documented for this action)

### Request Example
(No request body for this action)

### Response
#### Success Response (200)
(No specific fields documented for success response body, likely indicates success with an empty body or a generic confirmation.)

#### Response Example
```json
{
  "message": "Coupon stock started successfully"
}
```
```

--------------------------------

### GET /v3/marketing/goods-subsidy-activity/retail-store-act/{activity_id}/representatives

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/retailstore/README.md

Queries a list of business representatives for a retail store activity.

```APIDOC
## GET /v3/marketing/goods-subsidy-activity/retail-store-act/{activity_id}/representatives

### Description
This endpoint queries and returns a list of business representatives associated with a specific retail store activity.

### Method
GET

### Endpoint
/v3/marketing/goods-subsidy-activity/retail-store-act/{activity_id}/representatives

#### Path Parameters
- **activity_id** (string) - Required - The unique identifier of the activity.

#### Query Parameters
- **offset** (integer) - Optional - The starting index for the query results. Defaults to 0.
- **limit** (integer) - Optional - The maximum number of results to return per page. Defaults to 20.

### Response
#### Success Response (200)
- **ListRepresentativeResponse** (object) - Contains a list of representatives. Please refer to the [ListRepresentativeResponse](ListRepresentativeResponse.md) definition for detailed fields, which typically includes a list of `RepresentativeInfo` objects.

#### Response Example
```json
{
  "total_count": 5,
  "data": [
    {
      "representative_id": "rep98765",
      "representative_name": "John Doe",
      "contact_phone": "13800138000",
      "add_time": "2023-10-26T15:00:00+08:00"
    },
    {
      "representative_id": "rep54321",
      "representative_name": "Jane Smith",
      "contact_phone": "13900139000",
      "add_time": "2023-10-26T15:05:00+08:00"
    }
  ]
}
```
```

--------------------------------

### GET /v3/marketing/goods-subsidy-activity/activities

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/retailstore/README.md

Queries a list of brand price increase activities within a specified area.

```APIDOC
## GET /v3/marketing/goods-subsidy-activity/activities

### Description
This endpoint allows querying a list of brand price increase activities within a specified area.

### Method
GET

### Endpoint
/v3/marketing/goods-subsidy-activity/activities

#### Query Parameters
- **area_code** (string) - Required - The area code for which to query activities.
- **activity_type** (string) - Optional - The type of activity to filter by (e.g., "PRICE_INCREASE").
- **offset** (integer) - Optional - The starting index for the query results. Defaults to 0.
- **limit** (integer) - Optional - The maximum number of results to return per page. Defaults to 20.

### Response
#### Success Response (200)
- **ListActsByAreaResponse** (object) - Contains a list of activities matching the query criteria. Please refer to the [ListActsByAreaResponse](ListActsByAreaResponse.md) definition for detailed fields, which typically includes a list of `ActInfo` objects.

#### Response Example
```json
{
  "total_count": 10,
  "data": [
    {
      "activity_id": "act123",
      "activity_name": "Summer Sale",
      "activity_type": "PRICE_INCREASE",
      "start_time": "2023-07-01T00:00:00+08:00",
      "end_time": "2023-07-31T23:59:59+08:00",
      "status": "ONGOING"
    },
    {
      "activity_id": "act456",
      "activity_name": "Back to School",
      "activity_type": "PRICE_INCREASE",
      "start_time": "2023-08-15T00:00:00+08:00",
      "end_time": "2023-09-15T23:59:59+08:00",
      "status": "UPCOMING"
    }
  ]
}
```
```

--------------------------------

### GET /v3/profitsharing/bills

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/profitsharing/README.md

Retrieves the download URL for profit sharing bills.

```APIDOC
## GET /v3/profitsharing/bills

### Description
Gets the download address for the profit sharing bill file.

### Method
GET

### Endpoint
/v3/profitsharing/bills

### Parameters
#### Query Parameters
- **bill_date** (string) - Required - The date for which to retrieve the bill (YYYY-MM-DD).
- **sub_mchid** (string) - Optional - The sub-merchant ID.

### Request Example
```json
{
  "bill_date": "2023-01-01"
}
```

### Response
#### Success Response (200)
- **download_url** (string) - The URL to download the bill file.

#### Response Example
```json
{
  "download_url": "https://api.mch.weixin.qq.com/some/download/url"
}
```
```

--------------------------------

### Core Client Initialization and Certificate Download

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/README.md

Demonstrates how to initialize the WeChat Pay core client with merchant credentials and automatically obtain platform certificates, then uses the client to download platform certificates.

```APIDOC
## Core Client Initialization and Certificate Download

### Description
This snippet shows the basic setup for using the WeChat Pay Go SDK. It covers initializing the `core.Client` with necessary merchant information such as Merchant ID, certificate serial number, private key, and APIv3 key. It also demonstrates how to use this client to download the WeChat Pay platform certificates, which are essential for verifying response signatures.

### Method
GET (for downloading certificates)

### Endpoint
`/v3/certificates` (Implicitly called by the SDK)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```go
package main

import (
	"context"
	"log"

	"github.com/wechatpay-apiv3/wechatpay-go/core"
	"github.com/wechatpay-apiv3/wechatpay-go/core/option"
	"github.com/wechatpay-apiv3/wechatpay-go/services/certificates"
	"github.com/wechatpay-apiv3/wechatpay-go/utils"
)

func main() {
	var (
		mchID                      string = "190000****"                                // Merchant ID
		mchCertificateSerialNumber string = "3775B6A45ACD588826D15E583A95F5DD********"  // Merchant Certificate Serial Number
		mchAPIv3Key                string = "2ab9****************************"          // Merchant APIv3 Key
	)

	// Load merchant private key from a local file
	mchPrivateKey, err := utils.LoadPrivateKeyWithPath("/path/to/merchant/apiclient_key.pem")
	if err != nil {
		log.Fatal("load merchant private key error")
	}

	ctx := context.Background()
	// Initialize client with automatic fetching of WeChat Pay platform certificates
	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)
	}
	
	// Send request to download WeChat Pay platform certificates
	svc := certificates.CertificatesApiService{Client: client}
	resp, result, err := svc.DownloadCertificates(ctx)
	log.Printf("status=%d resp=%s", result.Response.StatusCode, resp)
}
```

### Response
#### Success Response (200)
- **resp** (`*certificates.Certificate` or similar) - The deserialized response body containing certificate information.
- **result** (`*core.APIResult`) - Contains the raw HTTP request and response objects.

#### Response Example
```json
{
  "certificate": "-----BEGIN CERTIFICATE-----\nMIIDqjCCAp...\n-----END CERTIFICATE-----",
  "serial_no": "3775B6A45ACD588826D15E583A95F5DD********"
}
```

### Error Handling
- **err** (`error`) - An error object if the request fails.
```

--------------------------------

### GET /v3/profitsharing/return-orders/{out_return_no}

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/profitsharing/README.md

Queries the result of a profit sharing return operation.

```APIDOC
## GET /v3/profitsharing/return-orders/{out_return_no}

### Description
Queries the result of a profit sharing return operation.

### Method
GET

### Endpoint
/v3/profitsharing/return-orders/{out_return_no}

### Parameters
#### Path Parameters
- **out_return_no** (string) - Required - Merchant-defined unique return number.

### Response
#### Success Response (200)
- **return_order_id** (string) - The unique ID generated by WechatPay for the return order.
- **out_return_no** (string) - Merchant-defined unique return number.
- **out_order_no** (string) - Merchant-defined unique order number of the original profit sharing order.
- **state** (string) - The current state of the return order (e.g., "SUCCESS", "FAILED").
- **amount** (integer) - The amount returned.
- **fail_reason** (string) - Reason for failure if the return failed.

#### Response Example
```json
{
  "return_order_id": "4200001234202305111234567891",
  "out_return_no": "RT20230511001",
  "out_order_no": "P20230511001",
  "state": "SUCCESS",
  "amount": 100,
  "fail_reason": null
}
```
```

--------------------------------

### Initialize WeChat Pay Go Client

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/README.md

初始化 `core.Client` 实例，用于向微信支付发送请求。此客户端支持请求签名和应答验签，并可配置自动获取微信支付平台证书。需要商户号、证书序列号、商户私钥和 APIv3 密钥。

```go
package main

import (
	"context"
	"log"

	"github.com/wechatpay-apiv3/wechatpay-go/core"
	"github.com/wechatpay-apiv3/wechatpay-go/core/option"
	"github.com/wechatpay-apiv3/wechatpay-go/services/certificates"
	"github.com/wechatpay-apiv3/wechatpay-go/utils"
)

func main() {
	var (
		mchID                      string = "190000****"                                // 商户号
		mchCertificateSerialNumber string = "3775B6A45ACD588826D15E583A95F5DD********"  // 商户证书序列号
		mchAPIv3Key                string = "2ab9****************************"          // 商户APIv3密钥
	)

	// 使用 utils 提供的函数从本地文件中加载商户私钥，商户私钥会用来生成请求的签名
	mchPrivateKey, err := utils.LoadPrivateKeyWithPath("/path/to/merchant/apiclient_key.pem")
	if err != nil {
		log.Fatal("load merchant private key error")
	}

	ctx := context.Background()
	// 使用商户私钥等初始化 client，并使它具有自动定时获取微信支付平台证书的能力
	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)
	}
	
	// 发送请求，以下载微信支付平台证书为例
	// https://pay.weixin.qq.com/wiki/doc/apiv3/wechatpay/wechatpay5_1.shtml
	svc := certificates.CertificatesApiService{Client: client}
	resp, result, err := svc.DownloadCertificates(ctx)
	log.Printf("status=%d resp=%s", result.Response.StatusCode, resp)
}
```

--------------------------------

### Download WeChat Pay Platform Certificates with Go SDK

Source: https://context7.com/wechatpay-apiv3/wechatpay-go/llms.txt

This Go function demonstrates how to actively download WeChat Pay platform certificates using the `wechatpay-go` SDK. These certificates are crucial for verifying signatures and encrypting data. The function requires an initialized `core.Client` and iterates through the downloaded certificates, logging their details. Note that the certificate content is encrypted and requires decryption using the merchant's APIv3 key.

```go
package main

import (
	"context"
	"log"

	"github.com/wechatpay-apiv3/wechatpay-go/core"
	"github.com/wechatpay-apiv3/wechatpay-go/services/certificates"
)

func DownloadCertificates(client *core.Client) {
	ctx := context.Background()

	// 创建证书服务
	svc := certificates.CertificatesApiService{Client: client}

	// 下载证书列表
	resp, result, err := svc.DownloadCertificates(ctx)
	if err != nil {
		log.Printf("下载证书失败: %v", err)
		return
	}

	log.Printf("获取到 %d 个平台证书", len(resp.Data))

	// 遍历证书列表
	for i, cert := range resp.Data {
		log.Printf("证书 [%d]:", i+1)
		log.Printf("  证书序列号: %s", *cert.SerialNo)
		log.Printf("  证书生效时间: %s", cert.EffectiveTime.Format("2006-01-02 15:04:05"))
		log.Printf("  证书过期时间: %s", cert.ExpireTime.Format("2006-01-02 15:04:05"))

		// 加密证书内容
		if cert.EncryptCertificate != nil {
			log.Printf("  加密算法: %s", *cert.EncryptCertificate.Algorithm)
			log.Printf("  证书密文: %s...", (*cert.EncryptCertificate.Ciphertext)[:50])
			log.Printf("  加密使用的Nonce: %s", *cert.EncryptCertificate.Nonce)
			log.Printf("  加密使用的关联数据: %s", *cert.EncryptCertificate.AssociatedData)
		}
	}

	log.Printf("HTTP状态码: %d", result.Response.StatusCode)

	// 注意: 证书内容使用 AES-256-GCM 加密
	// 需要使用商户 APIv3 密钥进行解密
	// SDK 的 WithWechatPayAutoAuthCipher 会自动处理证书下载和解密
}

```

--------------------------------

### GET /v3/profitsharing/orders/{out_order_no}

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/profitsharing/README.md

Queries the profit sharing result for a specific order.

```APIDOC
## GET /v3/profitsharing/orders/{out_order_no}

### Description
Queries the profit sharing result for a specific order.

### Method
GET

### Endpoint
/v3/profitsharing/orders/{out_order_no}

### Parameters
#### Path Parameters
- **out_order_no** (string) - Required - Merchant-defined unique order number.

### Response
#### Success Response (200)
- **order_id** (string) - The unique ID generated by WechatPay for the profit sharing order.
- **out_order_no** (string) - Merchant-defined unique order number.
- **state** (string) - The current state of the profit sharing order (e.g., "SUCCESS", "FAILED", "PENDING").
- **receivers** (array) - A list of profit sharing receivers and their status.
  - **type** (string) - Type of receiver.
  - **account** (string) - Account information of the receiver.
  - **amount** (integer) - The amount shared.
  - **succeed_amount** (integer) - The amount successfully shared.
  - **fail_reason** (string) - Reason for failure if the sharing failed.

#### Response Example
```json
{
  "order_id": "4200001234202305111234567890",
  "out_order_no": "P20230511001",
  "state": "SUCCESS",
  "receivers": [
    {
      "type": "MERCHANT",
      "account": "1900000109",
      "amount": 1000,
      "succeed_amount": 1000,
      "fail_reason": null
    }
  ]
}
```
```

--------------------------------

### POST /v3/pay/transactions/app - Prepay

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/payments/app/README.md

Creates an order for APP payment. This is the first step in the APP payment process.

```APIDOC
## POST /v3/pay/transactions/app

### Description
Creates an order for APP payment. This is the first step in the APP payment process.

### Method
POST

### Endpoint
/v3/pay/transactions/app

#### Request Body
- **mchid** (string) - Required - Merchant ID.
- **out_trade_no** (string) - Required - Unique order number generated by the merchant.
- **amount** (Amount) - Required - Order amount details.
- **description** (string) - Required - Order details description.
- **notify_url** (string) - Required - Callback URL for payment status updates.
- **goods_detail** (array[GoodsDetail]) - Optional - Details of the goods included in the order.
- **scene_info** (SceneInfo) - Optional - Information about the transaction scene.

### Request Example
```json
{
  "mchid": "1900000109",
  "out_trade_no": "native1234567890",
  "amount": {
    "total": 1,
    "currency": "CNY"
  },
  "description": "APP支付测试",
  "notify_url": "https://your-domain.com/notify/wechatpay"
}
```

### Response
#### Success Response (200)
- **code** (string) - Business code, "SUCCESS" indicates success.
- **message** (string) - Description of the result, "系统成功成功" indicates success.
- **prepay_id** (string) - Prepay ID, used to generate the payment request.

#### Response Example
```json
{
  "code": "SUCCESS",
  "message": "系统成功成功",
  "prepay_id": "wx201703051234567890abcdef1234567890"
}
```
```

--------------------------------

### GET /v3/profitsharing/transactions/{transaction_id}/amounts

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/profitsharing/README.md

Queries the remaining amount that can be shared for a given transaction.

```APIDOC
## GET /v3/profitsharing/transactions/{transaction_id}/amounts

### Description
Queries the remaining amount that can be shared for a given transaction.

### Method
GET

### Endpoint
/v3/profitsharing/transactions/{transaction_id}/amounts

### Parameters
#### Path Parameters
- **transaction_id** (string) - Required - The WeChat Pay transaction ID.

### Response
#### Success Response (200)
- **transaction_id** (string) - The WeChat Pay transaction ID.
- **unsplit_amount** (integer) - The remaining amount that can be shared (in cents).
- **split_amount** (integer) - The total amount that has been shared so far (in cents).
- **all_unsplit** (boolean) - Indicates if the entire transaction amount is available for sharing.

#### Response Example
```json
{
  "transaction_id": "4200001234202305111234567890",
  "unsplit_amount": 5000,
  "split_amount": 15000,
  "all_unsplit": false
}
```
```

--------------------------------

### GET /v3/profitsharing/merchant-configs/{sub_mchid}

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/profitsharing/README.md

Queries the maximum profit sharing ratio for a specific sub-merchant.

```APIDOC
## GET /v3/profitsharing/merchant-configs/{sub_mchid}

### Description
Queries the maximum profit sharing ratio for a specific sub-merchant.

### Method
GET

### Endpoint
/v3/profitsharing/merchant-configs/{sub_mchid}

### Parameters
#### Path Parameters
- **sub_mchid** (string) - Required - The sub-merchant ID.

### Response
#### Success Response (200)
- **max_ratio** (string) - The maximum profit sharing ratio allowed (e.g., "0.88").

#### Response Example
```json
{
  "max_ratio": "0.88"
}
```
```

--------------------------------

### POST /v3/marketing/goods-subsidy-activity/activity/{activity_id}/apply

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/retailstore/README.md

Allows a service provider to apply for a brand's price increase activity.

```APIDOC
## POST /v3/marketing/goods-subsidy-activity/activity/{activity_id}/apply

### Description
This endpoint allows a service provider to apply for a brand's price increase activity.

### Method
POST

### Endpoint
/v3/marketing/goods-subsidy-activity/activity/{activity_id}/apply

#### Path Parameters
- **activity_id** (string) - Required - The unique identifier of the activity.

#### Request Body
- **ApplyActivityBody** (object) - Required - The request body for applying to an activity. This object may contain fields such as `out_request_no`, `goods_id`, `goods_name`, `goods_category`, `goods_brand`, `goods_price`, `activity_type`, `start_time`, `end_time`, `store_id`, `goods_description`, `goods_image_url`, `promotions`, etc. Please refer to the [ApplyActivityBody](ApplyActivityBody.md) definition for detailed fields.

### Request Example
```json
{
  "out_request_no": "1234567890",
  "goods_id": "example_goods_id",
  "goods_name": "Example Product",
  "goods_price": 19999,
  "activity_type": "PRICE_INCREASE",
  "start_time": "2023-01-01T10:00:00+08:00",
  "end_time": "2023-12-31T23:59:59+08:00"
}
```

### Response
#### Success Response (200)
- **ApplyActivityResponse** (object) - Contains details about the successful application. Please refer to the [ApplyActivityResponse](ApplyActivityResponse.md) definition for detailed fields.

#### Response Example
```json
{
  "activity_id": "example_activity_id",
  "activity_status": "APPLIED",
  "apply_time": "2023-10-27T10:30:00+08:00"
}
```
```

--------------------------------

### POST /v3/marketing/goods-subsidy-activity/retail-store-act/{brand_id}/materials

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/retailstore/README.md

Generates promotional materials for a retail store activity by brand.

```APIDOC
## POST /v3/marketing/goods-subsidy-activity/retail-store-act/{brand_id}/materials

### Description
This endpoint generates promotional materials, such as QR codes, for a retail store activity associated with a specific brand.

### Method
POST

### Endpoint
/v3/marketing/goods-subsidy-activity/retail-store-act/{brand_id}/materials

#### Path Parameters
- **brand_id** (string) - Required - The unique identifier of the brand.

#### Request Body
- **CreateMaterialsRequest** (object) - Required - The request body containing details for material generation. Please refer to the [CreateMaterialsRequest](CreateMaterialsRequest.md) definition for detailed fields, which may include `activity_id`, `store_id`, `material_type`, `qr_code_config`, etc.

### Request Example
```json
{
  "activity_id": "example_activity_id",
  "store_id": "example_store_id",
  "material_type": "QR_CODE"
}
```

### Response
#### Success Response (200)
- **CreateMaterialsResponse** (object) - Contains the generated promotional materials. Please refer to the [CreateMaterialsResponse](CreateMaterialsResponse.md) definition for detailed fields, which might include `material_url` or `qr_code_data`.

#### Response Example
```json
{
  "brand_id": "example_brand_id",
  "material_info": {
    "material_type": "QR_CODE",
    "material_url": "https://example.com/qr/abcdef123"
  }
}
```
```

--------------------------------

### GET /v3/pay/transactions/out-trade-no/{out_trade_no} - QueryOrderByOutTradeNo

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/payments/app/README.md

Queries an order by its merchant's order number.

```APIDOC
## GET /v3/pay/transactions/out-trade-no/{out_trade_no}

### Description
Queries an order by its merchant's order number.

### Method
GET

### Endpoint
/v3/pay/transactions/out-trade-no/{out_trade_no}

#### Path Parameters
- **out_trade_no** (string) - Required - The merchant's order number.

### Response
#### Success Response (200)
- **code** (string) - Business code, "SUCCESS" indicates success.
- **message** (string) - Description of the result, "系统成功成功" indicates success.
- **transaction_id** (string) - WeChat Pay transaction ID.
- **out_trade_no** (string) - Merchant's order number.
- **trade_state** (string) - Transaction status.
- **trade_state_desc** (string) - Description of the transaction status.
- **payment_type** (string) - Payment type.
- **bank_type** (string) - Bank transaction type.
- **amount** (Amount) - Order amount details.
- **payer** (Payer) - Information about the payer.
- **create_time** (string) - Order creation time.
- **pay_time** (string) - Order payment time.
- **end_time** (string) - Order completion time.
- **success_time** (string) - Order successful payment time.
- **description** (string) - Order details description.
- **mchid** (string) - Merchant ID.
- **is_split** (string) - Indicates whether settlement is split.
- **settle_type** (string) - Settlement type.
- **profit_sharing** (string) - Indicates whether profit sharing is enabled.
- **scene_info** (SceneInfo) - Information about the transaction scene.

#### Response Example
```json
{
  "code": "SUCCESS",
  "message": "系统成功成功",
  "transaction_id": "4200000000202304071234567890",
  "out_trade_no": "native1234567890",
  "trade_state": "SUCCESS",
  "trade_state_desc": "支付成功",
  "payment_type": "JSAPI",
  "bank_type": "OTHERS",
  "amount": {
    "total": 1,
    "payer_total": 1,
    "currency": "CNY",
    "payer_currency": "CNY"
  },
  "payer": {
    "openid": "oUpF8uMuAJO7gg9 GmGmR_qS0Mh2g"
  },
  "create_time": "2023-04-07T10:00:00+08:00",
  "pay_time": "2023-04-07T10:01:00+08:00",
  "end_time": "2023-04-07T10:01:30+08:00",
  "success_time": "2023-04-07T10:01:00+08:00",
  "description": "APP支付测试",
  "mchid": "1900000109",
  "is_split": "Y",
  "settle_type": "BUSINESS",
  "profit_sharing": "N",
  "scene_info": {
    "payer_client_ip": "123.123.123.123",
    "device_id": "WEB_DEVICE_01"
  }
}
```
```

--------------------------------

### PrepayRequest Struct Documentation

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/partnerpayments/h5/PrepayRequest.md

This documentation describes the PrepayRequest struct used for initiating prepayment orders in the WeChat Pay V3 Go SDK. It outlines each field, its type, whether it's required, and a description of its purpose.

```APIDOC
## PrepayRequest Struct

### Description
Represents the request payload for creating a WeChat Pay prepayment order. This struct contains all necessary information for initiating a payment transaction, including merchant details, order information, and payment-related configurations.

### Fields

#### `SpAppid` (string) - Required
Service provider's public account AppID.

#### `SpMchid` (string) - Required
Service provider's merchant ID, generated and issued by WeChat Pay.

#### `SubAppid` (string) - Optional
Sub-merchant's public account AppID.

#### `SubMchid` (string) - Required
Sub-merchant's merchant ID, generated and issued by WeChat Pay.

#### `Description` (string) - Required
Description of the goods or service being paid for.

#### `OutTradeNo` (string) - Required
Merchant's unique order number.

#### `TimeExpire` (time.Time) - Optional
Order expiration time, formatted according to RFC3339.

#### `Attach` (string) - Optional
Additional data to be attached to the transaction.

#### `NotifyUrl` (string) - Required
Callback URL for transaction notifications. Must be HTTPS and cannot contain query parameters.

#### `GoodsTag` (string) - Optional
Goods tag, used for functionalities like coupons or instant discounts.

#### `LimitPay` ([]string) - Optional
Specifies the payment methods allowed for this transaction.

#### `SupportFapiao` (bool) - Optional
If set to `true`, an invoice opening entry will appear in the payment success message and details page. Requires the electronic invoice function to be enabled in the WeChat Pay Merchant Platform or WeChat Official Account Platform.

#### `Amount` (*Amount) - Required
An `Amount` object specifying the transaction amount and currency. See [Amount.md](Amount.md) for details.

#### `Detail` (*Detail) - Optional
A `Detail` object containing detailed information about the goods or services. See [Detail.md](Detail.md) for details.

#### `SceneInfo` (*SceneInfo) - Optional
A `SceneInfo` object providing details about the transaction scene. See [SceneInfo.md](SceneInfo.md) for details.

#### `SettleInfo` (*SettleInfo) - Optional
A `SettleInfo` object for settlement-related configurations. See [SettleInfo.md](SettleInfo.md) for details.

### Example Request Body
```json
{
  "sp_appid": "wx1234567890abcdef",
  "sp_mchid": "1900000001",
  "sub_mchid": "1900000002",
  "description": "Test Product",
  "out_trade_no": "TEST_OUT_TRADE_NO_12345",
  "notify_url": "https://yourdomain.com/wxpay/notify",
  "amount": {
    "total": 100,
    "currency": "CNY"
  }
}
```

### Related Links
- [Return to Type List](README.md#类型列表)
- [Return to Interface List](README.md#接口列表)
- [Return to Service README](README.md)
```

--------------------------------

### GET /v3/pay/transactions/id/{transaction_id} - QueryOrderById

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/payments/app/README.md

Queries an order by its WeChat Pay transaction ID.

```APIDOC
## GET /v3/pay/transactions/id/{transaction_id}

### Description
Queries an order by its WeChat Pay transaction ID.

### Method
GET

### Endpoint
/v3/pay/transactions/id/{transaction_id}

#### Path Parameters
- **transaction_id** (string) - Required - The WeChat Pay transaction ID.

### Response
#### Success Response (200)
- **code** (string) - Business code, "SUCCESS" indicates success.
- **message** (string) - Description of the result, "系统成功成功" indicates success.
- **transaction_id** (string) - WeChat Pay transaction ID.
- **out_trade_no** (string) - Merchant's order number.
- **trade_state** (string) - Transaction status.
- **trade_state_desc** (string) - Description of the transaction status.
- **payment_type** (string) - Payment type.
- **bank_type** (string) - Bank transaction type.
- **amount** (Amount) - Order amount details.
- **payer** (Payer) - Information about the payer.
- **create_time** (string) - Order creation time.
- **pay_time** (string) - Order payment time.
- **end_time** (string) - Order completion time.
- **success_time** (string) - Order successful payment time.
- **description** (string) - Order details description.
- **mchid** (string) - Merchant ID.
- **is_split** (string) - Indicates whether settlement is split.
- **settle_type** (string) - Settlement type.
- **profit_sharing** (string) - Indicates whether profit sharing is enabled.
- **scene_info** (SceneInfo) - Information about the transaction scene.

#### Response Example
```json
{
  "code": "SUCCESS",
  "message": "系统成功成功",
  "transaction_id": "4200000000202304071234567890",
  "out_trade_no": "native1234567890",
  "trade_state": "SUCCESS",
  "trade_state_desc": "支付成功",
  "payment_type": "JSAPI",
  "bank_type": "OTHERS",
  "amount": {
    "total": 1,
    "payer_total": 1,
    "currency": "CNY",
    "payer_currency": "CNY"
  },
  "payer": {
    "openid": "oUpF8uMuAJO7gg9 GmGmR_qS0Mh2g"
  },
  "create_time": "2023-04-07T10:00:00+08:00",
  "pay_time": "2023-04-07T10:01:00+08:00",
  "end_time": "2023-04-07T10:01:30+08:00",
  "success_time": "2023-04-07T10:01:00+08:00",
  "description": "APP支付测试",
  "mchid": "1900000109",
  "is_split": "Y",
  "settle_type": "BUSINESS",
  "profit_sharing": "N",
  "scene_info": {
    "payer_client_ip": "123.123.123.123",
    "device_id": "WEB_DEVICE_01"
  }
}
```
```

--------------------------------

### InitiateTransferBatchRequest

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/partnertransferbatch/InitiateTransferBatchRequest.md

This section details the structure and fields for the `InitiateTransferBatchRequest` object, used to initiate a batch transfer.

```APIDOC
## InitiateTransferBatchRequest

### Description
Represents the request structure for initiating a batch transfer to multiple recipients.

### Method
POST

### Endpoint
/v3/transfer-batches

### Parameters
#### Request Body
- **SubMchid** (string) - Required - Merchant ID of the sub-merchant.
- **SubAppid** (string) - Optional - WeChat-assigned public account ID of the sub-merchant. Required when AuthorizationType is INFORMATION_AUTHORIZATION_TYPE or INFORMATION_AND_FUND_AUTHORIZATION_TYPE.
- **AuthorizationType** (AuthType) - Required - Authorization type of the sub-merchant.
  - `INFORMATION_AUTHORIZATION_TYPE`: Information authorization type.
  - `FUND_AUTHORIZATION_TYPE`: Fund authorization type.
  - `INFORMATION_AND_FUND_AUTHORIZATION_TYPE`: Information and fund authorization type.
- **OutBatchNo** (string) - Required - Merchant's internal batch order number, must be unique.
- **BatchName** (string) - Required - Name of this batch transfer.
- **BatchRemark** (string) - Optional - Description of the transfer, UTF8 encoded, max 32 characters.
- **TotalAmount** (int64) - Required - Total transfer amount in cents. Must match the sum of all individual transfer amounts in the batch.
- **TotalNum** (int64) - Required - Total number of transfers in the batch, up to 3000. Must match the sum of all individual transfers in the batch.
- **TransferDetailList** ([]TransferDetailInput) - Optional - List of individual transfer details, max 3000 entries.
- **SpAppid** (string) - Optional - WeChat-assigned public account ID of the service provider. Required when AuthorizationType is FUND_AUTHORIZATION_TYPE.
- **TransferPurpose** (TransferUseType) - Optional - Purpose of the transfer.
  - `GOODSPAYMENT`: Goods payment.
  - `COMMISSION`: Commission.
  - `REFUND`: Refund.
  - `REIMBURSEMENT`: Reimbursement.
  - `FREIGHT`: Freight.
  - `OTHERS`: Others.
- **TransferScene** (TransferScene) - Optional - Transfer scene.
  - `ORDINARY_TRANSFER`: Ordinary transfer.
  - `PAYROLL_CARD_TRANSFER`: Payroll card transfer.

### Request Example
```json
{
  "SubMchid": "1900000100",
  "SubAppid": "wxd678efh567890ab",
  "AuthorizationType": "INFORMATION_AUTHORIZATION_TYPE",
  "OutBatchNo": "plonto0Md5",
  "BatchName": "测试",
  "BatchRemark": "tov0",
  "TotalAmount": 1000,
  "TotalNum": 1,
  "TransferDetailList": [
    {
      "OutDetailNo": "P2000000000120200908105555888",
      "TransferAmount": 1000,
      "TransferRemark": "tov0",
      "Openid": "o6I8x6EQ4x5_bY4aQ7w_QE28M77U",
      "UserName": "微信用户"
    }
  ],
  "TransferPurpose": "GOODSPAYMENT"
}
```

### Response
#### Success Response (200)
- **BatchId** (string) - WeChat Pay's unique batch transfer ID.
- **OutBatchNo** (string) - Merchant's internal batch order number.
- **CreateTime** (string) - Batch creation time in RFC3339 format.
- **Status** (string) - Status of the batch transfer (e.g., PROCESSING, SUCCESS, FAILED).

#### Response Example
```json
{
  "BatchId": "1001603290000000001",
  "OutBatchNo": "plonto0Md5",
  "CreateTime": "2020-09-08T10:58:51+08:00",
  "Status": "PROCESSING"
}
```
```

--------------------------------

### GET /v3/pay/partner/transactions/out-trade-no/{out_trade_no}

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/partnerpayments/app/README.md

This endpoint is used to query an order by its merchant order number.

```APIDOC
## GET /v3/pay/partner/transactions/out-trade-no/{out_trade_no}

### Description
This API is used to query an order by its merchant order number. This is useful for retrieving the status of a transaction when the WeChat Pay transaction ID is unknown.

### Method
GET

### Endpoint
/v3/pay/partner/transactions/out-trade-no/{out_trade_no}

#### Path Parameters
- **out_trade_no** (string) - Required - The merchant's order number.

### Response
#### Success Response (200)
- **code** (string) - Business status code.
- **message** (string) - Business status message.
- **transaction_id** (string) - The unique transaction ID assigned by WeChat Pay.
- **out_trade_no** (string) - The merchant's order number.
- **trade_state** (string) - The state of the transaction (e.g., SUCCESS, CLOSED, USERPAYING).
- **trade_state_desc** (string) - A description of the transaction state.
- **payment_type** (string) - The payment type used for the transaction.
- **bank_type** (string) - The bank type used for the transaction.
- **amount** (Amount) - The transaction amount.
- **payer** (Payer) - Information about the payer.
- **create_time** (string) - The time when the transaction was created.
- **pay_time** (string) - The time when the transaction was paid.
- **end_time** (string) - The time when the transaction was completed or closed.
- **success_time** (string) - The time when the transaction was successfully paid.
- **scene_info** (SceneInfo) - Scene information.

#### Response Example
```json
{
  "code": "SUCCESS",
  "message": "成功",
  "transaction_id": "4200001234202310271234567890",
  "out_trade_no": "native1234567890",
  "trade_state": "SUCCESS",
  "trade_state_desc": "支付成功",
  "payment_type": "JSAPI",
  "bank_type": "OTHERS",
  "amount": {
    "total": 1,
    "currency": "CNY"
  },
  "payer": {
    "openid": "oUpEYu------------------",
    "payer_id": "oUpEYu------------------"
  },
  "create_time": "2023-10-27T10:00:00+08:00",
  "pay_time": "2023-10-27T10:05:00+08:00",
  "end_time": "2023-10-27T10:05:00+08:00",
  "success_time": "2023-10-27T10:05:00+08:00",
  "scene_info": {
    "device_id": "APPLET"
  }
}
```
```

--------------------------------

### Call SubsidyReturn API using WeChat Pay Go v3

Source: https://github.com/wechatpay-apiv3/wechatpay-go/blob/main/docs/merchantexclusivecoupon/SubsidyApi.md

This Go code snippet demonstrates how to initialize the WeChat Pay client and call the SubsidyReturn API. It includes setting up merchant credentials, loading the private key, and constructing the SubsidyReturnRequest with necessary parameters. The response and potential errors are handled.

```go
package main

import (
	"context"
	"log"

	"github.com/wechatpay-apiv3/wechatpay-go/core"
	"github.com/wechatpay-apiv3/wechatpay-go/services/merchantexclusivecoupon"
	"github.com/wechatpay-apiv3/wechatpay-go/utils"
)

func main() {
	var (
		mchID                      string = "190000****"                               // 商户号
		mchCertificateSerialNumber string = "3775************************************" // 商户证书序列号
		mchAPIv3Key                string = "2ab9****************************"         // 商户APIv3密钥
	)

	// 使用 utils 提供的函数从本地文件中加载商户私钥，商户私钥会用来生成请求的签名
	mchPrivateKey, err := utils.LoadPrivateKeyWithPath("/path/to/merchant/apiclient_key.pem")
	if err != nil {
		log.Printf("load merchant private key error:%s", err)
		return
	}

	ctx := context.Background()
	// 使用商户私钥等初始化 client，并使它具有自动定时获取微信支付平台证书的能力
	opts := []core.ClientOption{
		option.WithWechatPayAutoAuthCipher(mchID, mchCertificateSerialNumber, mchPrivateKey, mchAPIv3Key),
	}
	client, err := core.NewClient(ctx, opts...)
	if err != nil {
		log.Printf("new wechat pay client err:%s", err)
		return
	}

	svc := merchantexclusivecoupon.SubsidyApiService{Client: client}
	resp, result, err := svc.SubsidyReturn(ctx,
		merchantexclusivecoupon.SubsidyReturnRequest{
			StockId:            core.String("128888000000001"),
			CouponCode:         core.String("ABCD12345678"),
			TransactionId:      core.String("4200000913202101152566792388"),
			RefundId:           core.String("50100506732021010105138718375"),
			PayerMerchant:      core.String("1900000001"),
			PayeeMerchant:      core.String("1900000002"),
			Amount:             core.Int64(100),
			Description:        core.String("20210115DESCRIPTION"),
			OutSubsidyReturnNo: core.String("subsidy-abcd-12345678"),
		},
	)

	if err != nil {
		// 处理错误
		log.Printf("call SubsidyReturn err:%s", err)
	} else {
		// 处理返回结果
		log.Printf("status=%d resp=%s", result.Response.StatusCode, resp)
	}
}
```