WeChat Pay

API intro

Request URL: The URL is set by the notify_url parameter submitted in the [Order Placement API for QR Code Pay] and must use the https protocol. If the URL cannot be accessed, the merchant will not receive any WeChat notifications. The URL must be directly accessible without any parameters. For example: notify_url: http://pay.weixin.qq.com/wxpay/123456789

Request method: POST

Applicable object:Common modeInstitutional mode

API Rules: https://wechatpay-api.gitbook.io/wechatpay-api-v3

Notification Rules

After the user completes the payment, WeChat will send both the payment result and the user information to the merchant. The merchant needs to receive and process the information, and return the successful response. Notification will only be sent if the payment is successful.

When notifying the interaction to the backend, if the response received by WeChat is unsuccessful or timeout, WeChat considers it as a notification failure and will send it again by following certain strategies to maximize the success rate, but WeChat does not guarantee a successful notification. （Notification frequency:15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - in total 24h4m）

Notification Message

For payment result notifications, access the notification URL set up by the merchant with the `POST` method, and the notification data is transmitted through the request body (BODY) in the `JSON` format. The notification data contains the details of the encrypted payment result.

The procedure of how to decrypt the notification data is described as follows.

1、Obtain APIv3 Secret from the merchant platform and record it as key.

2、For the algorithm described in `resource.algorithm` (which is AEAD_AES_256_GCM), obtain the corresponding `parameters nonce` and `associated_data`.

3、Decrypt the `resource.ciphertext` with `key`, `nonce`, and `associated_data` to obtain the resource object in JSON form.

Note: For the information on the API of the algorithm `AEAD_AES_256_GCM`, see rfc5116. The length of the `key` used for WeChat Pay is 32 bytes, the length of the random string `nonce` is 12 bytes, and the length of the `associated_data` is less than 16 bytes or may be zero.

Request Parameters

Notification Signature

Encryption does not guarantee that the notification request comes from wechat pay. Wechat pay will sign the notification sent to the merchant and put the signature value in the Wechatpay-Signature of Notification's HTTP header. The merchant should verify the signature to confirm that the request is from wechat pay, not other third parties. For the algorithm of signature verification, please refer to 【Wechat Pay API V3 Signature Scheme】

Callback Example

Payment Success Result Notification

{
    "id":"EV-2018022511223320873",
    "create_time":"20180225112233",
    "resource_type":"encrypt-resource",
    "event_type":"TRANSACTION.SUCCESS",
    "resource" : {
        "algorithm":"AEAD_AES_256_GCM",
        "ciphertext": "...",
        "nonce": "...",
        "associated_data": ""
    }
}

List of decrypted resource objects:

{
    "id": "1008450740201411110005820873",
    "sp_appid": "wx2421b1c4370ec43b",
    "sp_mchid": "10000100",
    "sub_mchid": "20000100",
    "out_trade_no": "20150806125346",
    "payer": {
      "sp_openid": "oUpF8uN95-Ptaags6E_roPHg7AG0"
    },
    "amount" : {
        "total": 528800,
        "currency": "HKD",
        "payer_total": 518799,
        "payer_currency": "CNY",
        "exchange_rate" : {
            "type": "SETTLEMENT_RATE",
            "rate": 8000000
        }
    },
    "trade_type": "MICROPAY",
    "trade_state": "SUCCESS",
    "trade_state_desc": "Payment successful",
    "bank_type": "CCB_DEBIT",
    "attach": "Payment test",
    "success_time": "2018-06-08T10:34:56+08:00",
    "promotion_detail":[
        {
            "promotion_id":"109519",
            "name":"Single-item discount-6",
            "scope":"SINGLE",
            "type":"DISCOUNT",
            "amount":1,
            "currency":"HKD",
            "activity_id":"931386",
            "wechatpay_contribute_amount":1,
            "merchant_contribute_amount":0,
            "other_contribute_amount":0,
            "goods_detail":[
                {
                    "goods_id":"iphone6s_16G",
                    "goods_remark":"Product remarks",
                    "quantity":1,
                    "price":528800
                }
            ]
        }
    ]
}

Payment Success Notification Parameters

Returned Result

After the merchant's backend has properly processed the notification, HTTP status code 200 or 204 needs to be returned. No specific content is required for 204.If other HTTP status codes are returned, WeChat Pay will deem the notification as a failure, and will send the notification regularly by following the aforesaid policies.

Note：If the merchant's backend fails to process a response, WeChat Pay will record the response message. It is recommended to return in the following format.

{
    "code": "SYSTEM_ERROR",
    "message": "System failure"
}

Returned Status Code Description