Need help with your APIs? I offer API discovery, governance & evangelism services. Explore services →
API Evangelist API Evangelist
Discovery
Learnings
Guidance
Toolbox
Alignment
API Evangelist LLC
Discovery
Learnings
Guidance
Toolbox
Alignment
API Evangelist LLC

Need help?

Contact us
Kin Lane

Chat with Kin

AI assistant · trained on my blog

WeChat

WeChat Pay APIv3 (Direct-Connect Merchant)

WeChat Pay's third-generation REST API for mainland-China direct-connect merchants. Authenticates with merchant API certificates and platform-key signed requests over HTTPS/JSON. Covers JSAPI / Native / App / H5 / Mini Program payments, refunds, bill download, merchant transfers, WeChat Pay Score, vouchers, marketing red packets, profit sharing, consumer complaints, and platform certificate rotation. Replaces the legacy XML-based APIv2.

Documentation Provider Profile APIs.io AsyncAPI GitHub

WeChat Pay APIv3 (Direct-Connect Merchant) is one of 16 APIs that WeChat publishes on the APIs.io network, described by an AsyncAPI event-driven specification.

Tagged areas include Payments, WeChat Pay, Refunds, Marketing, and Profit Sharing. The published artifact set on APIs.io includes an API reference, API documentation, code examples, and an AsyncAPI specification.

This event API exposes 20 operations across 20 channels, and defines 45 schemas. It is described by AsyncAPI 2.6.0, at version 1.0.0.

The API connects through 3 servers: https://{yourDomain}{callbackPath} (https), https://{yourDomain}{notifyPath} (https), https://{yourDomain}{callbackPath} (https).

20 operations 20 channels 45 schemas

Metadata

The identity and technical contract details declared by the specification.

Specification
AsyncAPI 2.6.0
API Version
1.0.0
Base URL
https://api.mch.weixin.qq.com
Contact
WeChat Developer Community
License
Proprietary
Resource Areas
1

Channels & Operations 20

Across 20 channels, the API surfaces 20 operations. Each is listed below with its action, channel, parameters, and response codes.

Channels 20
PUB
officialaccount/message/text
Receive a text message from a follower.
receiveOfficialAccountTextMessage body
PUB
officialaccount/message/image
Receive an image message from a follower.
receiveOfficialAccountImageMessage body
PUB
officialaccount/message/voice
Receive a voice message from a follower.
receiveOfficialAccountVoiceMessage body
PUB
officialaccount/message/video
Receive a video message from a follower.
receiveOfficialAccountVideoMessage body
PUB
officialaccount/message/shortvideo
Receive a short video message from a follower.
receiveOfficialAccountShortVideoMessage body
PUB
officialaccount/message/location
Receive a location message from a follower.
receiveOfficialAccountLocationMessage body
PUB
officialaccount/message/link
Receive a link message from a follower.
receiveOfficialAccountLinkMessage body
PUB
officialaccount/event/subscribe
Receive a subscribe event.
receiveOfficialAccountSubscribeEvent body
PUB
officialaccount/event/unsubscribe
Receive an unsubscribe event.
receiveOfficialAccountUnsubscribeEvent body
PUB
officialaccount/event/scan
Receive a SCAN event from a subscribed user.
receiveOfficialAccountScanEvent body
PUB
officialaccount/event/location
Receive a LOCATION event.
receiveOfficialAccountLocationEvent body
PUB
officialaccount/event/menu/click
Receive a CLICK menu event.
receiveOfficialAccountMenuClickEvent body
PUB
officialaccount/event/menu/view
Receive a VIEW menu event.
receiveOfficialAccountMenuViewEvent body
PUB
officialaccount/event/templatemessage/finish
Receive a TEMPLATESENDJOBFINISH event.
receiveOfficialAccountTemplateSendJobFinishEvent body
PUB
wechatpay/transaction/success
Receive a payment success notification.
receiveWechatPayTransactionSuccess body
PUB
wechatpay/refund/success
Receive a refund result notification.
receiveWechatPayRefundSuccess body
PUB
wecom/message/text
Receive a WeCom text message.
receiveWecomTextMessage body
PUB
wecom/event/subscribe
Receive a WeCom subscribe event.
receiveWecomSubscribeEvent body
PUB
wecom/event/unsubscribe
Receive a WeCom unsubscribe event.
receiveWecomUnsubscribeEvent body
PUB
wecom/event/menu/click
Receive a WeCom CLICK menu event.
receiveWecomMenuClickEvent body

Messages & Schemas 45

The contract defines 45 schemas that model the data carried by its messages. The most detailed are WechatPayNotificationEnvelope (6 properties), WecomBaseEnvelope (5 properties), WechatPayNotificationResource (5 properties), WechatPayNotificationHeaders (4 properties). Each schema is shown below with its type and property counts.

OfficialAccountTextMessage
message
A follower sent a text message to the Official Account.
OfficialAccountImageMessage
message
A follower sent an image message to the Official Account.
OfficialAccountVoiceMessage
message
A follower sent a voice message to the Official Account.
OfficialAccountVideoMessage
message
A follower sent a video message to the Official Account.
OfficialAccountShortVideoMessage
message
A follower sent a short video message to the Official Account.
OfficialAccountLocationMessage
message
A follower sent a location message to the Official Account.
OfficialAccountLinkMessage
message
A follower sent a link message to the Official Account.
OfficialAccountSubscribeEvent
message
A user subscribed to the Official Account, or scanned a parameter QR code while not subscribed.
OfficialAccountUnsubscribeEvent
message
A user unsubscribed from the Official Account.
OfficialAccountScanEvent
message
A subscribed follower scanned a parameter QR code.
OfficialAccountLocationEvent
message
A follower reported their location.
OfficialAccountMenuClickEvent
message
A follower tapped a CLICK-type custom menu item.
OfficialAccountMenuViewEvent
message
A follower tapped a VIEW-type custom menu item.
OfficialAccountTemplateSendJobFinishEvent
message
Asynchronous delivery result for a template message send.
WechatPayTransactionSuccessNotification
message
Asynchronous notification that a payment succeeded.
WechatPayRefundNotification
message
Asynchronous notification that a refund was processed.
WecomTextMessage
message
A WeCom member sent a text message to a self-built app.
WecomSubscribeEvent
message
A WeCom member was added to a self-built app's visible range.
WecomUnsubscribeEvent
message
A WeCom member was removed from a self-built app's visible range.
WecomMenuClickEvent
message
A WeCom member tapped a CLICK-type custom menu item.
OfficialAccountBaseEnvelope
object
Common XML fields present in every Official Account message and event push. WeChat encodes payloads as XML inside a root ... element; the property names below…
4 properties 4 required
OfficialAccountTextMessagePayload
object
OfficialAccountImageMessagePayload
object
OfficialAccountVoiceMessagePayload
object
OfficialAccountVideoMessagePayload
object
OfficialAccountShortVideoMessagePayload
object
OfficialAccountLocationMessagePayload
object
OfficialAccountLinkMessagePayload
object
OfficialAccountEventBase
object
OfficialAccountSubscribeEventPayload
object
OfficialAccountUnsubscribeEventPayload
object
OfficialAccountScanEventPayload
object
OfficialAccountLocationEventPayload
object
OfficialAccountMenuClickEventPayload
object
OfficialAccountMenuViewEventPayload
object
OfficialAccountTemplateSendJobFinishEventPayload
object
WechatPayNotificationHeaders
object
HTTP headers attached by WeChat Pay to every APIv3 notification. These headers MUST be verified before the encrypted resource is decrypted.
4 properties 4 required
WechatPayNotificationEnvelope
object
Outer envelope of a WeChat Pay APIv3 notification. The business payload lives inside the resource object as AES-256-GCM ciphertext keyed by the merchant's APIv…
6 properties 5 required
WechatPayNotificationResource
object
Encrypted business payload of a WeChat Pay APIv3 notification. Decrypt ciphertext with AES-256-GCM using the merchant's APIv3 key, the supplied nonce, and asso…
5 properties 3 required
WecomBaseEnvelope
object
Common fields in WeCom message and event push XML payloads. WeCom uses the same root element as Official Accounts but adds AgentID to identify the self-built a…
5 properties 5 required
WecomTextMessagePayload
object
WecomEventBase
object
WecomSubscribeEventPayload
object
WecomUnsubscribeEventPayload
object
WecomMenuClickEventPayload
object

Specification

The full machine-readable AsyncAPI contract behind this narrative.

Source

wechat-webhooks-asyncapi.yml Raw ↑

Other APIs WeChat publishes across the network.

WeChat Mini Programs Server API
AE Profile APIs.io
WeChat Mini Programs Client API
AE Profile APIs.io
WeChat Pay APIv3 (Service Provider / Partner)
AE Profile APIs.io
WeChat Pay Global v3 API
AE Profile APIs.io
WeChat Open Platform — Mobile App Login (OAuth 2.0)
AE Profile APIs.io
WeChat Open Platform — Website Login (QR OAuth)
AE Profile APIs.io
WeChat Open Platform — Third-Party Platform API
AE Profile APIs.io
WeChat Official Accounts API
AE Profile APIs.io
WeChat Work (WeCom) API
AE Profile APIs.io
WeChat Cloud Hosting API
AE Profile APIs.io
WeChat Channels (Video Accounts) Developer Surface
AE Profile APIs.io
WeChat Shop (微信小店) API
AE Profile APIs.io
#Payments#WeChat Pay#Refunds#Marketing#Profit Sharing#Transfers
← Back to W APIs
API Details
ID
wechat:wechat-pay-apiv3-direct-merchant
Base URL
https://api.mch.weixin.qq.com
Docs
https://pay.weixin.qq.com/wiki/doc/apiv3/en/index.shtml
Provider
WeChat
APIs.io →  GitHub →
Explore more
All APIs Providers APIs.io Network