X. Preamble
Compared to Alipay, WeChat Pay's support for .Net is not as adequate, and no official SDK is provided.
But thankfully, there are big guys in the community who have packaged a v3 version of the .
Link to original article:/community/develop/article/doc/00020aadc384a0a5f01c3526b56813。
SDK name: .TenpayV3, supports .NET Core / Framework, complete package of all v3 API.
In this article, we will also use this SDK for the application, mainly introducing two interfaces for refund and refund status query.
I. Access preparation
1.1 Introducing the SDK
Name: .TenpayV3, supports .Net Standard 2.0, .Net Framework 4.6.2-4.7.1, .
NuGet Profile Address:/packages/.TenpayV3。
Introduction：Based on WeChat Pay API v3 version of the client, support for merchants (direct connection), partners (service providers, channel operators, organizations, banks) mode, support for basic payment, vouchers, merchant coupons, commissioned marketing, consumer cards, payment gifts, bank directed to promote the activities of the WeChat Payments, WeChat Payment Score, WeChat First Enjoyment Card, Payment as a Service, Points of Gold Program, intelligent business circle, e-commerce payment collection and delivery, the platform payment collection and delivery, the second-level merchant entry, small and micro-merchant entry, consumer complaints, merchant risk management, merchant violation notification, batch transfer to zero money, banking components, customs declaration, fusion wallet, micro-worker card, e-invoice, e-ticket, vehicle owner platform, education renewal pass, campus easy payment and other functions.
1.2 Required account information
| name (of a thing) | typical example | synopsis |
| trader number (computing) | 110 ... ... | 10 Bit, Digital |
| Merchant API Certificate Serial Number | D566D2 ... ... | 40 Digits, Capital Letters, Numbers, Combinations |
| Merchant API v3 key | gSk0EA ... ... | 32-Bit, Numeric, Upper Case, Lower Case, Combination |
| Merchant API Certificate Private Key | -----BEGIN PRIVATE KEY-----\r\nMIIEv ... ... | Typically the contents of the `apiclient_key.pem` file |
About WeChat's service providers and general merchants:
ordinary merchant
Funds are settled by WeChat directly with the merchant, and there is no freezing of funds or splitting of accounts involved;
You can apply independently, and you can make payments and refunds through the interface by yourself;
Suitable for large corporations or branded merchants with their own technical team and payment system.
service provider
The funds will be frozen by WeChat first, and WeChat will make the split only after the service provider initiates the split;
An unlimited number of sub-merchants can be applied for free, but the service provider's merchant number requires an annual certification fee;
You can't receive payment directly, but you need to apply for "Authorized Merchant" to receive payment;
"Special Merchants" can collect payments like regular merchants, but the refund interface must be initiated by the service provider;
Ideal for third-party organizations that provide payment solutions to multiple specialty merchants, especially those with complex scenarios where they need to handle multi-merchant bill splits or collect service fees.
Special Note: Special merchants, that is, sub-merchants under the service provider, do not have the authority to call the refund interface directly, and can only be based on the service provider's account information plus sub-merchant number.
II. Interface calls
2.1 Create a shared client object based on account information client
var manager = new InMemoryCertificateManager(); var options = new WechatTenpayClientOptions()
var options = new WechatTenpayClientOptions()
{
MerchantId = "MerchantId", // MerchantId
MerchantV3Secret = "Merchant API v3 key", // Merchant API v3 key
MerchantCertificateSerialNumber = "Merchant API Certificate Serial Number", // Merchant API Certificate Serial Number
MerchantCertificatePrivateKey = "-----BEGIN PRIVATE KEY-----\r\nMIIEv ... ... Q71AG\r\n-----END PRIVATE KEY-----", // Merchant API Certificate Private Key
PlatformCertificateManager = manager
}; var client = new WechatTrader
var client = new WechatTenpayClient(options);2.2 Refund interface
Here is the code for the refund interface, where the entry parameterOnly the required fields are exemplified, see the official documentation for additional details.
Official Documentation:/docs/merchant/apis/refund/refunds/
var request = new CreateRefundDomesticRefundRequest()
{
//OutTradeNumber = "MerchantOrderNumber", // [MerchantOrderNumber] The merchant order number of the original payment transaction, choose one or the other with transaction_id.
TransactionId = "WeChat Order Number", // [WeChat Payment Order Number] The WeChat order number corresponding to the original payment transaction, one or the other with out_trade_no.
// The merchant's customized refund unique identifier, to be well-documented, and mandatory for refund status inquiries
OutRefundNumber = $"WX{("yyyyMMddHHmmssffffffff")}",
//NotifyUrl = "https://..." , // Callback address
Amount = new ()
{
Total = 100, // in cents
Refund = 99, // in cents
Currency = "CNY" // [Refund Currency] Currently only supports CNY.
}
};
//string json = Json_Object.ObjectToJsonstr(request); var response = await (request); var json = Json_Object.
var response = await (request);
if (())
{
("RefundId:", ); // [WeChat Payment Refund Number] WeChat Payment Refund Number
("OutRefundNumber:", ); // [MerchantRefundNumber] Refund order number within the merchant system, unique within the merchant system
("TransactionId:", ); // [WeChat Payment Order Number]
("OutRefundNumber:", ); // [MerchantOrderNumber] The merchant order number corresponding to the original payment transaction.
}
else
{
("HTTP Status: " + ()); // [Merchant Order Number] The merchant order number corresponding to the original payment transaction.
("Error Code:" + ); ("Error Description.
("Error Description:" + ); ("Error Code:" + ); }
}2.3 Refund Status Inquiry Interface
The following is the code for the refund status query interface, which actually has only one input parameter: the merchant refund order number. The documentation requires that it be directly followed by the interface request path, but in the SDK it is encapsulated in the Request model.
Official Documentation:/docs/merchant/apis/refund/refunds/
var request = new GetRefundDomesticRefundByOutRefundNumberRequest()
{
OutRefundNumber = "WX20240806104450972506",
};
//string json = Json_Object.ObjectToJsonstr(request);
var response = await (request);
if (())
{
("RefundId:", ); // [WeChat Payment Refund Number] WeChat Payment Refund Number
("OutRefundNumber:", ); // [MerchantRefundNumber] Refund number within the merchant system, unique within the merchant system
("OutRefundNumber:", ); // [WeChat Payment Order Number]
("OutRefundNumber:", ); // [Merchant Order Number] The merchant order number corresponding to the original payment transaction.
}
else
{
("HTTP Status: " + ()); // [Merchant Order Number] The merchant order number corresponding to the original payment transaction.
("Error Description:" + ); ("Error Code:" + ); }
}2.4 Corresponding Logic for the Request and Response Models of the Interface
Below is a list of the two interface information used above:
| interface name | interface address | Request | Response |
| refund | 【POST】/v3/refund/domestic/refunds | CreateRefundDomesticRefundRequest | CreateRefundDomesticRefundResponse |
| Refund Status Inquiry | 【GET】/v3/refund/domestic/refunds/{out_refund_no} | GetRefundDomesticRefundByOutRefundNumberRequest | GetRefundDomesticRefundByOutRefundNumberResponse |
As can be seen from the above table comparison, the corresponding model is actually based on the interface address, and the other interfaces can then follow this logic to correspond one by one.