# 微信支付

# **了解微信支付，一种受中国客户欢迎的数字钱包.**

微信支付作为一个数字钱包，被整合到流行的中国超级应用--微信中。多年来，作为寻求与中国消费者建立联系的企业在国内和国际上的一个重要支付解决方案，它已经获得了显著的地位。微信已经转变为一个全面的生态系统，为中国购物者提供了聊天、浏览产品或服务的便利，并在一个统一的平台上进行无缝支付。这种整合使购物体验就像与同伴进行友好交谈一样毫不费力，而且都在一个地方。

## 特点

| 客户所在地         | 中国消费者<br />海外华人<br />中国游客|
| -------------------------- | ------------------------------------------------------------ |
| 用户支付货币      | CNY, GBP, USD, EUR，HKD                            |
| 结算给商户货币      | GBP,EUR,USD,HKD                                               |
| 最小交易金额 | 没有限制                                           |
| 最大交易金额 | 50,000 USD                                         |
| 退款                    | ✅                                                  |
| 部分退款            | ✅                                                  |
| 多次部分退款    | ✅                                                  |
| 争议                 | ❌                                                  |

## 子产品
| **支付场景**           | **产品**          | **支付场景描述**                            |
| -------------------------- | -------------------- | ------------------------------------------------------------ |
| **QR Code**                | **Web Payment**      | 在桌面浏览器上，选择微信支付作为支付方式的商家结账后，出现一个二维码。然后购物者打开手机上的微信应用，扫描浏览器页面上显示的条形码，完成支付。 |
| **QR Code**                | **Quick Pay**        | 在销售点，商家可以在终端上显示二维码，购物者可以打开手机上的微信应用，扫描二维码完成支付。 |
| **Mobile H5 Flows**        | **H5 payment**       | 在手机浏览器上，购物者在商家结账时选择微信支付作为支付方式，并从浏览器转到微信支付应用中完成支付，然后被转回商家浏览器。 |
| **Mobile - In WeChat app** | **Official Account	微信公众号** | 通常在更多的中文市场上流行，商家可以考虑在微信社交网站上建立一个个人资料页面，并提示购物者在微信社交网站环境中选择产品并完成付款。 |
| **Mobile - In WeChat app** | **Mini Program	小程序**     | 小程序是官方账户的另一种变化，它就像微信社交网站中的一个网站，商家可以在这里进行更多的定制，购物者可以在这个环境中选择产品并完成支付。 |

## 支付流程

### QR Code


![pic_QR Code.png](https://api.apifox.cn/api/v1/projects/1296482/resources/386271/image-preview)

### Mobile H5 Flows


![pic_Mobile H5 Flows.png](https://api.apifox.cn/api/v1/projects/1296482/resources/386272/image-preview)

### Mobile - In WeChat app

![pic_Mobile - In WeChat app.png](https://api.apifox.cn/api/v1/projects/1296482/resources/386273/image-preview)

# **集成方式**

**Payment method enumeration values:** **`wechat_pay`**

**微信支付有两种对接方式**

1. Direct API 直连
2. Checkout 收银台

| **Integration method** | **Wechat Pay subproduction** | **terminal_type enumeration values** |
| ---------------------- | ---------------------------- | ------------------------------------ |
| Direct API             | Web Payment                  | WEB                                  |
| Direct API             | Quick Pay                    | SCAN_CODE                            |
| Direct API             | H5 Payment                   | WAP                                  |
| Direct API             | Official Account Payment 微信公众号支付    | OFFICIAL_ACCOUNT                     |

| 


## Direct API 直连

PaymentIntent是一个对象，代表了你向客户收款的意图，并跟踪付款过程的生命周期。在你的服务器上创建一个PaymentIntent，并指定要收取的金额和支持的货币。

### [Create a PaymentIntent](api-42631218)

对于直接的API集成，你可以创建PaymentIntent并在一个步骤中获得url。以下是创建付款意向的演示：

1. Web Payment
2. H5 Payment
3. Quick Pay
4. Official Account Payment



#### **Web Payment**


*Request*

```JSON
{
    "amount":20,
    "currency":"CNY",
    "confirm":true,
    "payment_method_options":{
        "wechat_pay":{
            "terminal_type":"WEB",
            "os_type":"IOS",
            "client_ip":"192.168.0.1" 
            }
    },
    "payment_method_data":{
        "type":"wechat_pay"
    },
"return_url":"https://wooshpay.com"
}
```

*Response*

```JSON
{
    "id": "pi_1666625039547498496",
    "object": "payment_intent",
    "created": 1686189348000,
    "livemode": false,
    "currency": "CNY",
    "amount": 20,
    "status": "requires_action",
    "client_secret": "pi_1666625039547498496_secret_qGj2VEg4khXSWkXvRI7Y3yZe",
    "next_action": {
        "type": "wechat_pay_display_qr_code",
        "wechat_pay_display_qr_code": {
            "image_data_url": "weixin://wxpay/bizpayurl?pr=lJhTByDzz"
        }
    },
    "payment_method_types": [
        "wechat_pay",
    ],
    "confirmation_method": "automatic",
    "payment_method_options": {
        "wechat_pay": {
            "terminal_type": "WEB",
            "os_type": "IOS",
            "client_ip": "192.168.0.1"
        }
    },
    "return_url": "https://wooshpay.com",
    "payment_method": "pm_1666625039430057984",
    "capture_method": "automatic"
}
```

The `image_data_url` from `wechat_pay_display_qr_code` from `next_action` can be opened, from the link, the merchant can generate corresponding QR codes. Then use the corresponding QR code to charge.

#### **H5 Payment**


*Request* 

```json
{
    "amount": 20,
    "currency": "CNY",
    "confirm": true,
    "payment_method_options": {
        "wechat_pay": {
            "terminal_type": "WAP",
            "client_ip": "192.168.124.133"  //customer's mobile's ip
        }
    },
    "payment_method_data": {
        "type": "wechat_pay"
    },
    "return_url": "yourwebsite"    
}
```

*Response*

```JSON
{
    "id": "pi_1666625208749916160",
    "object": "payment_intent",
    "created": 1686189389000,
    "livemode": false,
    "currency": "CNY",
    "amount": 20,
    "status": "requires_action",
    "client_secret": "pi_1666625208749916160_secret_BeEXcbvAQNUkrV9C6ZFjOamS",
    "next_action": {
        "type": "wechat_pay_redirect_to_web",
        "wechat_pay_redirect_to_web": {
            "url": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx08095629694611f41b32df91d6ea160000&package=3449031350&redirect_url=https%3A%2F%2Fwooshpay.com"
        }
    },
    "payment_method_types": [
        "wechat_pay"
    ],
    "confirmation_method": "automatic",
    "payment_method_options": {
        "wechat_pay": {
            "terminal_type": "WAP",
            "os_type": "IOS",
            "client_ip": "172.31.5.62"
        }
    },
    "return_url": "https://wooshpay.com",
    "payment_method": "pm_1666625208624087040",
    "capture_method": "automatic"
}
```

The `url` from `wechat_pay_redirect_to_web` from `next_action` can be opened, from the link, the customer will be direct to the wechat APP for payment, and be direct to `return_url` after payment.

#### **Quick Pay**


*Request*

```JSON
{
    "amount":10,
    "currency":"CNY",
    "confirm":true,
    "payment_method_options":{
        "wechat_pay":{
            "terminal_type":"SCAN_CODE",
            "os_type":"IOS",
            "client_ip":"192.XXX.XX.X" 
            }
    },
    "payment_method_data":{
        "type":"wechat_pay",
        "wechat_pay":{
            "payment_code":"XXXXXXXXXX"
        }
    },
    "return_url":"https://yourweb.com"
}
```

*Response*

```JSON
{
    "id": "pi_1760544113783996416",
    "object": "payment_intent",
    "created": 1708581401000,
    "livemode": true,
    "currency": "CNY",
    "amount": 20,
    "status": "requires_action",
    "description": "test_wechat",
    "client_secret": "pi_1760544113783996416_secret_QXXNIYPfHRYjwDoaZ9D9XMTk",
    "payment_method_types": [
        "wechat_pay"
    ],
    "confirmation_method": "automatic",
    "payment_method_options": {
        "wechat_pay": {
            "terminal_type": "SCAN_CODE",
            "client_ip": "192.XXX.XX.X"
        }
    },
    "payment_method": "pm_1760544113712693248",
    "capture_method": "automatic"
}
```

The password-free payment can be paid directly, otherwise the customer needs to enter the password, fingerprint, etc. on the mobile phone to pay.

#### **微信公众号支付**


*Request*
```JSON
{
    "amount": 20,
    "currency": "CNY",
    "confirm": true,
    "payment_method_options": {
        "wechat_pay": {
            "terminal_type": "OFFICIAL_ACCOUNT",
            "client_ip": "192.168.0.1",
            "openid": "" 
        }
    },
    "payment_method_data": {
        "type": "wechat_pay"
    }
}
```

*Response*

```JSON
{
    "id": "pi_1666626536515567616",
    "object": "payment_intent",
    "created": 1686189705000,
    "livemode": false,
    "currency": "CNY",
    "amount": 20,
    "status": "requires_action",
    "client_secret": "pi_1666626536515567616_secret_CcrukFKgxbPp7UEAxodLlNRD",
    "next_action":{
        "wechat_pay_official_account_params":{
            "appId":"XXXX",
            "timeStamp":"XXXX",
            "nonceStr":"XXXX",
            "signType":"XXXX",
            "paySign":"XXXX",
            "package":"XXXX"
        }
    },
    "payment_method_types": [
        "wechat_pay"
    ],
    "confirmation_method": "automatic",
    "payment_method_options": {
        "wechat_pay": {
            "openid": "",
            "terminal_type": "OFFICIAL_ACCOUNT",
            "client_ip": "192.168.0.1"
        }
    },
    "payment_method": "pm_1666626536389738496",
    "capture_method": "automatic"
}
```

`next_action`中的`wechat_pay_official_account_params`包含一些你需要在前端使用的参数。下面是一个关于如何使用这些参数的例子。*js* *example*

```JavaScript
function onBridgeReady(){
 WeixinJSBridge.invoke(
   'getBrandWCPayRequest', {
     "appId":"wx7a154c094f74e84f",      
     "timeStamp":"1682239457",        
     "nonceStr":"kLRl3fI6FiP8PXxNNAiytwuQBdoCWXvZ",     
     "package":"prepay_id=wx23164417189051acf8825c57d275230000",     
     "signType":"MD5",     
     "paySign":"703868ed93842f83c9dff4d80d0cad67"  
    },
    function(res){     
       if(res.err_msg == "get_brand_wcpay_request:ok" ) {}     // Using the above method to judge the front-end return, the WeChat team solemnly reminds: res.err_msg will return ok after the user's payment is successful, but it does not guarantee that it is absolutely reliable. 
       }
   ); 
}
if (typeof WeixinJSBridge == "undefined"){
   if( document.addEventListener ){
    document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false);
   }else if (document.attachEvent){
    document.attachEvent('WeixinJSBridgeReady', onBridgeReady); 
    document.attachEvent('onWeixinJSBridgeReady', onBridgeReady);
   }
}else{
   onBridgeReady();
} 
```



# **下一步**

You can add more features to your integration as needed

## [Create a Webhook](doc-2517709)

听取你的WooshPay账户上的事件，这样你的集成可以自动触发反应。创建一个webhook，主要关注 enabled_events和url。

## [Create a Refund](api-51369554)

创建一个退款，将资金偿还给你的客户。你也可以执行部分退款，但不是每一种支付方式都支持。部分退款是指你只退还原始交易金额的一部分。