WeChat Pay

Introduction

With over 1.2 billion Chinese users, WeChat Pay is one of China's most popular payment methods. Users can make payments through WeChat Pay at supermarkets, restaurants, shopping malls, online e-commerce, and other merchants that support WeChat Pay around the world.
EGMS allows merchants to use WeChat Pay in different online transaction scenarios.

Merchant Supported

Only the merchants with a Hong Kong entity can access WeChat Pay.

Payment Scenarios

The payment scenarios of WeChat Pay include:

PC: QR Payment

Mobile: Redirecting Payment, In-App Payment, Mini Program Payment, and Official Account Payment

Implementation

Latest API version: v1

Payment Steps

To conduct WeChat Pay through EGMS, you need to perform the following steps:

Create a Payment: Use POST｜Payment to initiate a WeChat Pay transaction request to EGMS. Specify:

       (1) the payment brand

        paymentMethod.e-wallet.paymentBrand = WeChat_Pay

       (2) the payment scenario

       e.g. transInitiator.platform = WEB

Take Action: Get the response result and perform different actions according to the action information.
Receive the Payment Result: After the user completes the payment, you can obtain the payment information and update the payment status by the webhook (notification).
After Payment: Cancel the transaction or refund via POST | Cancel or POST | Refund

🚧
Tips
All merchants accessing the EGMS system will be assigned a SID and a SignKey to initiate API requests. Contact [email protected] for relevant parameters.

Create a Payment

📘
Applicable when
The merchant initiates a WeChat Pay payment request to the EGMS system.

📘
Endpoint
POST
https://{URL}/g2/v1/payment/mer/{sid}/evo.e-commerce.payment

📘
Parameter

Field	Type	Required?	Description
merchantTransInfo	object	Required	Define your merchantTransID and merchantTransTime.
transAmount	object	Required	The currency and value of the payment.
paymentMethod	object	Required	1. Specify paymentMethod.type with e-wallet and paymentMethod.e-wallet.paymentBrand with WeChat_Pay. 2. Specify paymentMethod.e-wallet.subOpenID with the customer ID on your mini-program and specify paymentMethod.e-wallet.subAppID with the APP ID assigned by WeChat if the customer makes payment in your App or mini-program.
transInitiator	object	Required	For WeChatPay, you can specify: 1. _WEB in transInitiator.platform for Scenario: Scan QR Code on PC 2. WAP in transInitiator.platform for Scenario: Redirect to WAP Page 3. APP in transInitiator.platform for Scenario: Redirect to WeChat Pay App 4. MINI intransInitiator.platform for Scenario: Pay in Mini-Program 5. INWALLET intransInitiator.platform for Scenario: Pay in Official Account.
storeInfo	object	Optional	Specify storeInfo.mcc for the transaction if you have different MCCs.
validTime	integer	Optional	Specify it for the payment available period in minute if needed. For example, 120.
returnURL	string	Optional	The URL redirecting the customer back after the customer completes or cancels the payment.
webhook	string	Optional	The URL receiving the payment result notification.
metadata	string	Optional	The same value will be echoed back in RESPONSE.

📘
Sample: Create a Payment
Following is an example of a customer using WeChat Pay to make a 10 USD payment.

curl -X POST https://{URL}/g2/v1/payment/mer/{sid}/evo.e-commerce.payment \  
-H "Content-Type: application/json" \  
-H "DateTime: 2021-12-31T08:30:59+0800" \  
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \  
-H "SignType: SHA256" \  
-H "Authorization: YOUR_MESSAGE_SIGNATURE" \  
-d '{  
    "merchantTransInfo": {  
        "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
        "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",  
        "merchantTransTime": "2021-12-31T08:30:59+08:00"  
    },  
    "storeInfo": {  
        "mcc": "5411"  
    },  
    "transAmount": {  
        "currency": "USD",  
        "value": "10.00"  
    },  
    "validTime": "120",  
    "returlUrl": "https://YOUR_COMPANY.com/RETURNURL",  
    "paymentMethod": {  
        "type": "e-wallet",  
        "e-wallet": {  
            "paymentBrand": "WeChat_Pay"  
        }  
    },  
    "transInitiator": {  
        "platform": "WEB"  
    },  
    "webhook": "https://YOUR_COMPANY.com/WEBHOOK",  
    "metadata": "This is a metadata"  
}

Take Action

After you initiate a POST | Payment request, in the API response, when the result.code = S0000, you can view the action to perform subsequent payment operations.

Scenario: Scan QR Code on PC

📘
Instruction
When you send WEB in the transInitiator.platform, the API will return an action.type = presentQRCode.

{  
    "result": {  
        "code": "S0000",  
        "message": "Success",  
        "pspResponseCode": "PAYMENT_IN_PROCESS",  
        "pspMessage": "Payment is processing."
    },  
    "action": {  
        "type": "presentQRCode",  
        "qrData": {  
            "qrCode": "weixin://wxpay/bizpayurl?pr=XXXXXXXXX"
        }  
    },  
    "paymentMethod": {  
        "e-wallet": {  
            "paymentBrand": "WeChat_Pay"  
        }  
    },  
    "payment": {  
        "status": "Pending",  
        "merchantTransInfo": {  
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",  
            "merchantTransTime": "2021-12-31T08:30:59+08:00"  
        },  
        "evoTransInfo": {  
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",  
            "evoTransTime": "2021-12-31T00:30:59Z"  
        },  
        "pspTransInfo": {  
            "pspTransID": "012650163996361073624683217162626594RAUmxGgaUF202112190006141885",  
            "pspTransTime": "2021-12-31T08:30:59+08:00"  
        },  
        "transAmount": {  
            "currency": "USD",  
            "value": "10.00"  
        }  
    },  
    "pspData": {  
        "name": "WeChat_Pay"
    },  
    "metadata": "This is a metadata"  
}

You can get the QR Code in action.qrData and show it to the user on your front end.

Scenario: Redirect to WAP Page

📘
Instruction
When you send WAP in the transInitiator.platform, the API will return an action.type = redirectUser.

{
    "result": {
        "code": "S0000",
        "message": "Success",
    },
    "action": {
        "type": "redirectUser",
        "redirectData": {
            "url": "https://wx.tenpay.com/xxxxxxxxxx",
            "method": "GET"
        }
    },
    "paymentMethod": {
        "e-wallet": {
            "paymentBrand": "WeChat_Pay"
        }
    },
    "payment": {
        "status": "Pending",
        "merchantTransInfo": {
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
            "merchantTransTime": "2021-12-31T08:30:59+08:00"
        },
        "evoTransInfo": {
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
            "evoTransTime": "2021-12-31T00:30:59Z"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "metadata": "This is a metadata"
}

You can show the user the URL returned in action.redirectData.url. After the user jumps to the WAP page of WeChat, the follow-up payment operation is completed.

Scenario: Redirect to WeChat Pay App

📘
Instruction
If you need to use WeChat App to complete the payment, you need to send the APP ID assigned to you by WeChat in paymentMethod.e-wallet.subAppID in the POST | Payment request.
When you send APP in the transInitiator.platform, the API will return an action.type = invokeWallet.

{
    "result": {
        "code": "S0000",
        "message": "User paying, password required"
    },
    "action": {
        "type":"invokeWallet",
        "walletData": {
            "paymentString": "{\"appid\":\"xxxxxxxxxx\",\"timestamp\":\"1656063051\",\"noncestr\":\"C_6Nrs0TQh-HhK-9G5ojrgd3fh5R8VtP\",\"package\":\"Sign=WXPay\",\"partnerid\":\"1234567890\",\"prepayid\":\"wx241730516598085bd581677e53ba2b0000\",\"sign\":\"2757539935D78B1DFBE25BE032BA5A48\"}"
        }
    },
    "paymentMethod": {
        "e-wallet": {
            "paymentBrand": "WeChat_Pay"
        }
    },
    "payment": {
        "status": "Pending",
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",  
            "merchantTransTime": "2021-12-31T08:30:59+08:00"  
        },
        "evoTransInfo": {  
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",  
            "evoTransTime": "2021-12-31T00:30:59Z"  
        },  
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "metadata": "This is a metadata"
}

You will get action.walletData.paymentString and invoke WeChat App by calling the WeChat SDK Service. After the user jumps to the WeChat App payment page, the follow-up payment operation is completed.

Scenario: Pay in Mini-Program

📘
Instruction
If you need to use WeChat Mini-Program to complete the payment, you need to send the user's mini-program customer ID in paymentMethod.e-wallet.subOpenID in the POST | Payment request, and send the APP ID assigned by WeChat in paymentMethod.e-wallet.subAppID.
When you send MINI in the transInitiator.platform, the API will return an action.type = invokeWallet.

{
    "result": {
        "code": "S0000",
        "message": "User paying, password required"
    },
    "action": {
        "type":"invokeWallet",
        "walletData": {
            "paymentString": "{\"timeStamp\":\"1656553742\",\"nonceStr\":\"vD5kPDfreQ9ESO9GiwEJ5WIpcTajwpEJ\",\"package\":\"prepay_id=wx300949025065388dffac8bed1d50ed0000\",\"signType\":\"MD5\",\"paySign\":\"CEC9BF5714624FEAF7F35782E97626DC\"}"
        }
    },
    "paymentMethod": {
        "e-wallet": {
            "paymentBrand": "WeChat_Pay"
        }
    },
    "payment": {
        "status": "Pending",
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",  
            "merchantTransTime": "2021-12-31T08:30:59+08:00"  
        },
        "evoTransInfo": {  
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",  
            "evoTransTime": "2021-12-31T00:30:59Z"  
        },  
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "metadata": "This is a metadata"
}

You will get action.walletData.paymentString and invoke WeChat Mini-Program payment by calling EGMS SDK Service. After the user jumps to the WeChat mini-program payment page, the follow-up payment operation is completed.

Scenario: Pay in Official Account

📘
Instruction
When you send INWALLET in the transInitiator.platform, the API will return an action.type = redirectUser.

{
    "result": {
        "code": "S0000",
        "message": "User paying, password required"
    }, 
    "action": {
        "type":"redirectUser",
        "redirectData": {
            "method": "GET",
            "url": "https://open.weixin.qq.com/xxxxxxxxxx"
        }
    },
    "paymentMethod": {
        "e-wallet": {
            "paymentBrand": "WeChat_Pay"
        }
    },
    "payment": {
        "status": "Pending",
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",  
            "merchantTransTime": "2021-12-31T08:30:59+08:00"  
        },
        "evoTransInfo": {  
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",  
            "evoTransTime": "2021-12-31T00:30:59Z"  
        },  
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "metadata": "This is a metadata"
}

You can show the user the URL returned in action.redirectData.url. After the user jumps to the WeChat official account payment page, the subsequent payment operation is completed.

Receive the Payment Result

📘
Applicable when
If you send the webhook address in the webhook in POST | Payment request, when the transaction is completed or failed, you will receive a status change notification, which has an eventCode = Payment, pushed by EGMS to this address.

📘
Sample: Notification

{
    "eventCode": "Payment",
    "paymentMethod": {
        "e-wallet": {
            "paymentBrand": "WeChat_Pay"
        }
    },
    "payment": {
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",  
            "merchantTransTime": "2021-12-31T08:30:59+08:00"  
        },
        "evoTransInfo": {  
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",  
            "evoTransTime": "2021-12-31T00:30:59Z"  
        },  
        "status": "Captured",
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "metadata": "This is a metadata"
}

📘
Instruction
You can judge whether the user has completed the payment according to payment.status, and display the corresponding page to the user.

Inquire the Payment Status

📘
Applicable when
Merchant inquires WeChat Pay transaction from EGMS system.

📘
Endpoint
GET
https://{URL}/g2/v1/payment/mer/{sid}/evo.e-commerce.payment?merchantTransID={merchantTransID}

📘
Parameter

Query parameter	Type	Required?	Description
merchantTransID	object	Required	The merchantTransInfo.merchantTransID of the requesting payment.

📘
Sample: Inquire the Payment Status

curl GET '{URL}/g2/v1/payment/mer/{sid}/evo.e-commerce.payment?merchantTransID=e05b93cc849046a6b570ba144c328c7f' \  
-H "Content-Type: application/json" \  
-H "DateTime: 2021-12-31T08:30:59+0800" \  
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \  
-H "SignType: SHA256" \  
-H "Authorization: YOUR_MESSAGE_SIGNATURE" \

📘
Instruction
When the result.code = S0000, you will receive a successful response.

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "paymentMethod": {
        "e-wallet": {
            "paymentBrand": "WeChat_Pay"
        }
    },
    "payment": {
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",  
            "merchantTransTime": "2021-12-31T08:30:59+08:00"  
        },
        "evoTransInfo": {  
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",  
            "evoTransTime": "2021-12-31T00:30:59Z"  
        },  
        "status": "Captured",
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "metadata": "This is a metadata"
}

After Payment

You can initiate a request to cancel or refund payment via POST | Cancel and POST | Refund.

If the payment.status = Captured of the original transaction, only POST | Refund can be initiated.

If the payment.status = Pending of the original transaction, only POST | Cancel can be initiated.

After Payment - Cancel

Create a Cancel

📘
Applicable when
Merchant cancels WeChat Pay transaction to EGMS system.

📘
Endpoint
POST
https://{URL}/g2/v1/payment/mer/{sid}/evo.e-commerce.cancel?merchantTransID={merchantTransID}

📘
Parameter
merchantTransID is the merchantTransInfo.merchantTransID in the POST｜Payment request.

Field	Type	Required?	Description
merchantTransInfo	object	Required	Define your merchantTransID and merchantTransTime for the cancellation transaction.
initiatingReason	string	Optional	The reason for cancellation.
webhook	string	Optional	The URL receiving the cancellation result notification.
metadata	string	Optional	The same value will be echoed back in RESPONSE.

📘
Sample: Create a Cancel

curl -X POST https://{URL}/g2/v1/payment/mer/{sid}/evo.e-commerce.cancel?merchantTransID=e05b93cc849046a6b570ba144c328c7f\  
-H "Content-Type: application/json" \  
-H "DateTime: 2021-12-31T08:35:59+0800" \  
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \  
-H "SignType: SHA256" \  
-H "Authorization: YOUR_MESSAGE_SIGNATURE" \  
-d '{  
    "merchantTransInfo": {  
        "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",      
        "merchantTransID": "b570ba144c328c7fe05b93cc849046a6",  
        "merchantTransTime": "2021-12-31T08:35:59+08:00"   
    },  
    "webhook": "https://YOUR_COMPANY.com/WEBHOOK",  
    "initiatingReason": "Customer cancels order",  
    "metadata": "This is a metadata"  
}'

📘
Instruction
When the result.code = S0000, you will receive a successful response.

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "cancel": {
        "status": "Received",
        "evoTransInfo": {
            "evoTransID": "2f317565bf8a4094b6b1e26558843a14",
            "evoTransTime": "2021-12-31T08:35:59+08:00"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "b570ba144c328c7fe05b93cc849046a6",
            "merchantTransTime": "2021-12-31T08:35:59+08:00"
        }
    },
    "payment": {
        "status": "Cancelling",
        "evoTransInfo": {
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
            "evoTransTime": "2021-12-31T00:30:59Z"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
            "merchantTransTime": "2021-12-31T08:30:59+08:00"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "metadata": "This is a metadata"
}

📘
Instruction
You can judge whether the user has completed the cancellation according to cancel.status, and display the corresponding page to the user. If cancel.status = Received, you can get the final cancellation result by webhook, or query it through GET | Cancel.

Status	Description
cancel.status = Success	The cancellation is completed.
cancel.status = Failed	The cancellation failed.
cancel.status = Received	The cancellation is in processing.

Receive the Cancellation Result

📘
Applicable when
If you send the webhook address in the webhook in POST | Cancel request, when the cancellation is completed or failed, you will receive a status change notification, which has an eventCode = Cancel, pushed by EGMS to this address.

📘
Sample: Notification

{
    "eventCode": "Cancel",
     "cancel": {
        "status": "Success",
        "evoTransInfo": {
            "evoTransID": "2f317565bf8a4094b6b1e26558843a14",
            "evoTransTime": "2021-12-31T08:35:59+08:00"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "b570ba144c328c7fe05b93cc849046a6",
            "merchantTransTime": "2021-12-31T08:35:59+08:00"
        }
    },
    "payment": {
        "status": "Cancelled",
        "evoTransInfo": {
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
            "evoTransTime": "2021-12-31T00:30:59Z"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
            "merchantTransTime": "2021-12-31T08:30:59+08:00"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "metadata": "This is a metadata"
}

📘
Instruction
You can judge whether the transaction is successfully canceled according to the cancel.status, and display the corresponding page to the user.

Status	Description
cancel.status = Success	The cancellation is completed.
cancel.status = Failed	The cancellation failed.

Inquire the Cancellation Status

📘
Applicable when
The merchant inquires the Cancel status of the WeChat Pay transaction from the EGMS system.

📘
Endpoint
GET
https://{URL}/g2/v1/payment/mer/{sid}/evo.e-commerce.cancel?merchantTransID={merchantTransID}

📘
Parameter

Query parameter	Type	Required?	Description
merchantTransID	string	Required	The merchantTransInfo.merchantTransID of the initial cancellation.

📘
Sample: Inquire the Cancellation Status

curl GET '{URL}/g2/v1/payment/mer/{sid}/evo.e-commerce.cancel?merchantTransID=b570ba144c328c7fe05b93cc849046a6' \  
-H "Content-Type: application/json" \  
-H "DateTime: 2021-12-31T08:30:59+0800" \  
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \  
-H "SignType: SHA256" \  
-H "Authorization: YOUR_MESSAGE_SIGNATURE" \

📘
Instruction
When the result.code = S0000, you will receive a successful response.

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "cancel": {
        "status": "Success",
        "evoTransInfo": {
            "evoTransID": "2f317565bf8a4094b6b1e26558843a14",
            "evoTransTime": "2021-12-31T08:35:59+08:00"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "b570ba144c328c7fe05b93cc849046a6",
            "merchantTransTime": "2021-12-31T08:35:59+08:00"
        }
    },
    "payment": {
        "status": "Cancelled",
        "evoTransInfo": {
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
            "evoTransTime": "2021-12-31T00:30:59Z"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
            "merchantTransTime": "2021-12-31T08:30:59+08:00"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    }
}

After Payment - Refund

Create a Refund

📘
Applicable when
Merchant requests for WeChat Pay transaction refund to EGMS system.

📘
Endpoint
POST
https://{URL}/g2/v1/payment/mer/{sid}/evo.e-commerce.refund?merchantTransID={merchantTransID}

📘
Parameter
merchantTransID is the merchantTransInfo.merchantTransID in the POST | Payment request.

Field	Type	Required?	Description
merchantTransInfo	object	Required	Define your merchantTransID and merchantTransTime for the refund.
transAmount	object	Required	The currency and value of the refund.
initiatingReason	string	Optional	The reason for cancellation.
webhook	string	Optional	The URL receiving the cancellation result notification.
metadata	string	Optional	The same value will be echoed back in RESPONSE.

📘
Sample: Create a Refund

curl -X POST https://{URL}/g2/v1/payment/mer/{sid}/evo.e-commerce.refund?merchantTransID=e05b93cc849046a6b570ba144c328c7f\  
-H "Content-Type: application/json" \  
-H "DateTime: 2021-12-31T08:35:59+0800" \  
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \  
-H "SignType: SHA256" \  
-H "Authorization: YOUR_MESSAGE_SIGNATURE" \  
-d '{ 
    "merchantTransInfo": {  
        "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",      
        "merchantTransID": "b570ba144c328c7fe05b93cc849046a6",  
        "merchantTransTime": "2021-12-31T08:35:59+08:00"   
    },  
    "transAmount": {
        "currency": "USD",
        "value": "10.00"
    },
    "webhook": "https://YOUR_COMPANY.com/WEBHOOK",  
    "initiatingReason": "Customer cancels order",  
    "metadata": "This is a metadata"  
}

📘
Instruction
When the result.code = S0000, you will receive a successful response.

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "refund": {
        "status": "Received",
        "evoTransInfo": {
            "evoTransID": "2f317565bf8a4094b6b1e26558843a14",
            "evoTransTime": "2021-12-31T08:35:59+08:00"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "b570ba144c328c7fe05b93cc849046a6",
            "merchantTransTime": "2021-12-31T08:35:59+08:00"
        }
    },
    "payment": {
        "status": "Refunding",
        "evoTransInfo": {
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
            "evoTransTime": "2021-12-31T00:30:59Z"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
            "merchantTransTime": "2021-12-31T08:30:59+08:00"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "metadata": "This is a metadata"
}

📘
Instruction
You can judge whether the user has completed the refund according to refund.status, and display the corresponding page to the user. If refund.status = Received, you can get the final cancellation result by webhook, or query it through GET | Refund.

Status	Description
refund.status = Success	The refund is successful.
refund.status = Failed	The refund failed.
refund.status = Received	The refund is in processing.

Receive the Refund Result

📘
Applicable when
If you send the webhook address in the webhook in POST | Refund request, when the refund is completed or failed, you will receive a status change notification, which has an eventCode = Refund, pushed by EGMS to this address.

📘
Sample: Notification

{
    "eventCode": "Refund",
    "refund": {
        "status": "Success",
        "evoTransInfo": {
            "evoTransID": "2f317565bf8a4094b6b1e26558843a14",
            "evoTransTime": "2021-12-31T08:35:59+08:00"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "b570ba144c328c7fe05b93cc849046a6",
            "merchantTransTime": "2021-12-31T08:35:59+08:00"
        }
    },
    "payment": {
        "status": "Cancelled",
        "evoTransInfo": {
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
            "evoTransTime": "2021-12-31T00:30:59Z"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
            "merchantTransTime": "2021-12-31T08:30:59+08:00"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    },
    "metadata": "This is a metadata"
}

📘
Instruction
You can judge whether the transaction is successfully refunded according to the refund.status, and display the corresponding page to the user.

Status	Description
refund.status = Success	The refund is successful.
refund.status = Failed	The refund failed.

Inquire the Refund Status

📘
Applicable when
Merchant inquires the refund status of WeChat Pay transaction from EGMS system.

📘
Endpoint
GET
https://{URL}/g2/v1/payment/mer/{sid}/evo.e-commerce.refund?merchantTransID={merchantTransID}

📘
Parameter

Query parameter	Type	Required?	Description
merchantTransID	string	Required	The merchantTransInfo.merchantTransID of the initial refund.

📘
Sample: Inquire the Refund Status

curl GET '{URL}/g2/v1/payment/mer/{sid}/evo.e-commerce.refund?merchantTransID=b570ba144c328c7fe05b93cc849046a6' \  
-H "Content-Type: application/json" \  
-H "DateTime: 2021-12-31T08:30:59+0800" \  
-H "MsgID: 2d21a5715c034efb7e0aa383b885fc7a" \  
-H "SignType: SHA256" \  
-H "Authorization: YOUR_MESSAGE_SIGNATURE" \

📘
Instruction
When the result.code = S0000, you will receive a successful response.

{
    "result": {
        "code": "S0000",
        "message": "Success"
    },
    "refund": {
        "status": "Success",
        "evoTransInfo": {
            "evoTransID": "2f317565bf8a4094b6b1e26558843a14",
            "evoTransTime": "2021-12-31T08:35:59+08:00"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "b570ba144c328c7fe05b93cc849046a6",
            "merchantTransTime": "2021-12-31T08:35:59+08:00"
        }
    },
    "payment": {
        "status": "Refunded",
        "evoTransInfo": {
            "evoTransID": "6a3b2e6b5ab74d6da7202cdf8e97fa6e",
            "evoTransTime": "2021-12-31T00:30:59Z"
        },
        "merchantTransInfo": {
            "merchantOrderReference": "MERCHANT_REFERENCE_MESSAGE",
            "merchantTransID": "e05b93cc849046a6b570ba144c328c7f",
            "merchantTransTime": "2021-12-31T08:30:59+08:00"
        },
        "transAmount": {
            "currency": "USD",
            "value": "10.00"
        }
    }
}

Recognize the Result Code

To process the result, you have to recognize the result.code. In all successful RESPONSE, result.code = S0000 will be replied to your endpoint. If you receive a result.code ≠ S0000, you can review Handle the Result Code for further process.

Introduction

Merchant Supported

Payment Scenarios

Implementation

Payment Steps

🚧Tips

Create a Payment

📘Applicable when

📘Endpoint

📘Parameter

📘Sample: Create a Payment

Take Action

📘Instruction

📘Instruction

📘Instruction

📘Instruction

📘Instruction

Receive the Payment Result

📘Applicable when

📘Sample: Notification

📘Instruction

Inquire the Payment Status

📘Applicable when

📘Endpoint

📘Parameter

📘Sample: Inquire the Payment Status

📘Instruction

After Payment

After Payment - Cancel

📘Applicable when

📘Endpoint

📘Parameter

📘Sample: Create a Cancel

📘Instruction

📘Instruction

📘Applicable when

📘Sample: Notification

📘Instruction

📘Applicable when

📘Endpoint

📘Parameter

📘Sample: Inquire the Cancellation Status

📘Instruction

After Payment - Refund

📘Applicable when

📘Endpoint

📘Parameter

📘Sample: Create a Refund

📘Instruction

📘Instruction

📘Applicable when

📘Sample: Notification

📘Instruction

📘Applicable when

📘Endpoint

📘Parameter

📘Sample: Inquire the Refund Status

📘Instruction

Recognize the Result Code

🚧
Tips

📘
Applicable when

📘
Endpoint

📘
Parameter

📘
Sample: Create a Payment

📘
Instruction

📘
Instruction

📘
Instruction

📘
Instruction

📘
Instruction

📘
Applicable when

📘
Sample: Notification

📘
Instruction

📘
Applicable when

📘
Endpoint

📘
Parameter

📘
Sample: Inquire the Payment Status

📘
Instruction

📘
Applicable when

📘
Endpoint

📘
Parameter

📘
Sample: Create a Cancel

📘
Instruction

📘
Instruction

📘
Applicable when

📘
Sample: Notification

📘
Instruction

📘
Applicable when

📘
Endpoint

📘
Parameter

📘
Sample: Inquire the Cancellation Status

📘
Instruction

📘
Applicable when

📘
Endpoint

📘
Parameter

📘
Sample: Create a Refund

📘
Instruction

📘
Instruction

📘
Applicable when

📘
Sample: Notification

📘
Instruction

📘
Applicable when

📘
Endpoint

📘
Parameter

📘
Sample: Inquire the Refund Status

📘
Instruction