Step 1: Enable RSA Secret Key

Merchants can enable the RSA Secret Key - useepay Public Key in the mc backend - Configuration Center - Secret Key Management. This secret key is used by merchants for signature verification.

Step 2: Create a Webhook

Merchants create a webhook URL via the webhook creation API.

Step 3: Receive Asynchronous Notifications

When an event associated with your webhook URL is triggered, UseePay will send a corresponding asynchronous notification to this URL (in HTTPS format).
After receiving the message, you need to return an HTTP 200 response to UseePay. UseePay will consider the asynchronous notification delivery successful only after receiving the 200 response; otherwise, it will retry delivery.

Step 4: Signature Verification

The format of the asynchronous message content is as follows:

Request Headers

before 2026-04

Parameter	Example
merchant_no	50000000000xxxx
api_version	2024-10
app_id	www.pay.com
Content-Type	application/x-www-form-urlencoded
sign	Z8hLld5yZlZKNnQqZiwlZEYBJ4F2PAAxxxxxxxxxxxxxxx...

Payload

data=%7B%22id%22%3A%22evt_7f560319eabb4127a9a282d1937b60dc%22%2C%22name%22%3A%22payment_intent.succeeded%22%2C%22data%22%3A%7B%22id%22%3A%221012506201612797898%22%2C%22amount%22%3A10%2C%22currency%22%3A%22USD%22%2C%22status%22%3A%22succeeded%22%2C%22customer%22%3A%7B%22id%22%3A%22cus_VEN6A8LP1G00%22%2C%22address%22%3A%7B%22country%22%3A%22CN%22%2C%22city%22%3A%22shanghai%22%2C%22postcode%22%3A%22200100%22%2C%22state%22%3A%22shanghai%22%2C%22line1%22%3A%22pudong%20zhangjiang%22%2C%22line2%22%3A%22room%201002%22%7D%2C%22description%22%3A%22test%20customer%22%2C%22name%22%3A%22team.liu%22%2C%22email%22%3A%22victor.yang%40useepay.com%22%2C%22phone%22%3A%2213127921181%22%2C%22metadata%22%3A%7B%22testkey%22%3A%2212233%22%7D%2C%22shipping%22%3A%7B%22address%22%3A%7B%22country%22%3A%22CN%22%2C%22city%22%3A%22shanghai%22%2C%22postcode%22%3A%22200100%22%2C%22state%22%3A%22shanghai%22%2C%22line1%22%3A%22minghang%20pushenglu%22%2C%22line2%22%3A%22room%202002%22%7D%2C%22name%22%3A%22zhangsan%22%2C%22phone%22%3A%2213527189021%22%7D%2C%22merchant_no%22%3A%22500000000009133%22%2C%22app_id%22%3A%22www.pay.com%22%2C%22create_at%22%3A%222025-06-20T08%3A12%3A09Z%22%2C%22modify_at%22%3A%222025-06-20T08%3A12%3A09Z%22%2C%22first_name%22%3A%22team%22%2C%22last_name%22%3A%22liu%22%2C%22merchant_customer_id%22%3A%22100002025062016041%22%7D%2C%22description%22%3A%22UseePay%20-%20T-shirt%22%2C%22order%22%3A%7B%22category%22%3A%22Apparel%20and%20accessories%22%2C%22products%22%3A%5B%7B%22name%22%3A%22IPHONE7%22%2C%22code%22%3A%2212334455%22%2C%22desc%22%3A%22IPHONE%207%22%2C%22quantity%22%3A5%2C%22sku%22%3A%22100004%22%2C%22type%22%3A%22physical%22%2C%22url%22%3A%22https%3A%2F%2Fwww.xxx.com%2Fitem%2F12345%22%2C%22effective_end_at%22%3A%222020-12-31T23%3A59%3A59Z%22%2C%22effective_start_at%22%3A%222020-01-01T00%3A00%3A00Z%22%7D%2C%7B%22name%22%3A%22IPHONE7%22%2C%22code%22%3A%2212334455%22%2C%22desc%22%3A%22IPHONE%207%22%2C%22quantity%22%3A5%2C%22sku%22%3A%22100004%22%2C%22type%22%3A%22physical%22%2C%22url%22%3A%22https%3A%2F%2Fwww.xxx.com%2Fitem%2F12345%22%2C%22effective_end_at%22%3A%222020-12-31T23%3A59%3A59Z%22%2C%22effective_start_at%22%3A%222020-01-01T00%3A00%3A00Z%22%7D%5D%2C%22shipping%22%3A%7B%22address%22%3A%7B%22city%22%3A%22Shanghai%22%2C%22postcode%22%3A%22100000%22%2C%22state%22%3A%22Shanghai%22%2C%22line1%22%3A%22Pudong%20District%22%7D%2C%22first_name%22%3A%22John%22%2C%22last_name%22%3A%22Doe%22%2C%22shipping_method%22%3A%22sameday%22%7D%7D%2C%22metadata%22%3A%7B%22id%22%3A1%7D%2C%22confirm%22%3Afalse%2C%22orderType%22%3A%22sale%22%2C%22mode%22%3A%22subscription%22%2C%22subscriptionId%22%3A%22sub_VEN6A9FT1G00%22%2C%22sale%22%3Atrue%2C%22merchant_no%22%3A%22500000000009133%22%2C%22app_id%22%3A%22www.pay.com%22%2C%22create_at%22%3A%222025-06-20T08%3A12%3A09Z%22%2C%22modify_at%22%3A%222025-06-20T08%3A12%3A09Z%22%2C%22merchant_order_id%22%3A%2220250620161209695%22%2C%22invoice_id%22%3A%22inv_VEN6AA6P1G00%22%2C%22customer_id%22%3A%22cus_VEN6A8LP1G00%22%2C%22available_payment_method_types%22%3A%5B%2217%22%2C%2212%22%2C%2215%22%2C%2213%22%2C%2212%22%2C%2215%22%2C%2214%22%2C%2201%22%2C%2202%22%2C%2202%22%2C%2205%22%2C%2202%22%2C%2202%22%2C%2202%22%2C%2202%22%2C%2202%22%2C%2205%22%5D%2C%22payment_method_options%22%3A%7B%22type%22%3A%22card%22%2C%22card%22%3A%7B%22three_ds_action%22%3A%22force_3ds%22%2C%22authorization_type%22%3A%22final_auth%22%2C%22auto_capture%22%3Atrue%7D%7D%2C%22next_action%22%3A%7B%22type%22%3A%22redirect%22%2C%22redirect%22%3A%7B%22method%22%3A%22GET%22%2C%22url%22%3A%22https%3A%2F%2Fcheckout1.uat.useepay.com%2Fv4%3Fpid%3D1012506201612797898%26secret%3Dd5d92897f4cbf1507c3149182ae0adde%22%2C%22content_type%22%3A%22application%2Fjson%22%7D%7D%2C%22return_url%22%3A%22http%3A%2F%2Fwww.baidu.com%22%2C%22client_secret%22%3A%22d5d92897f4cbf1507c3149182ae0adde%22%2C%22device_data%22%3A%7B%22browser%22%3A%7B%22java_enabled%22%3Afalse%2C%22javascript_enabled%22%3Afalse%2C%22user_agent%22%3A%22Mozilla%2F5.0%20%28Macintosh%3B%20Intel%20Mac%20OS%20X%2010_15_7%29%20AppleWebKit%2F537.36%20%28KHTML%2C%20like%20Gecko%29%20Chrome%2F90.0.4430.212%20Safari%2F537.36%22%7D%2C%22language%22%3A%22EN%20or%20en-US%22%2C%22location%22%3A%7B%22lat%22%3A%22-37.81892%22%2C%22lon%22%3A%22144.95913%22%7D%2C%22mobile%22%3A%7B%22device_model%22%3A%22Apple%20IPHONE%207%22%2C%22os_type%22%3A%22IOS%20or%20ANDROID%22%2C%22os_version%22%3A%22IOS%2014.5%22%7D%2C%22timezone%22%3A%22-2%20or%203%3A30%22%2C%22accept_header%22%3A%22*%2F*%22%2C%22device_id%22%3A%2200000000-000000000000000%22%2C%22ip_address%22%3A%22139.224.227.218%22%2C%22screen_color_depth%22%3A24%2C%22screen_height%22%3A1080%2C%22screen_width%22%3A1920%7D%2C%22auto_capture%22%3Atrue%2C%22mandate_id%22%3A%22man_VEN6AAQ11G00%22%2C%22order_id%22%3A%221012506201612797899%22%7D%7D

The data attribute can be decoded via URL-decode to obtain the original message content.

after 2026-04

Parameter	Example
merchant_no	50000000000xxxx
api_version	2026-04
app_id	www.pay.com
Content-Type	application/json
sign	Z8hLld5yZlZKNnQqZiwlZEYBJ4F2PAAxxxxxxxxxxxxxxx...

Payload

{
    "id": "evt_5fcb36845625461794bfa8xxx",
    "name": "payment_intent.succeeded",
    "data": {
        "id": "10125082016088xxx",
        "amount": 50,
        "currency": "USD",
        "status": "succeeded",
        "customer": {
            "id": "cusxxx",
            "address": {
                "country": "CN",
                "city": "shanghai",
                "postcode": "200100",
                "state": "shanghai",
                "line1": "pudong zhangjiang",
                "line2": "room 1002"
            },
            "description": "test customer",
            "name": "??",
            "email": "xxx@useepay.com",
            "phone": "xx",
            "metadata": {
                "testkey": "12233"
            },
            "shipping": {
                "address": {
                    "country": "CN",
                    "city": "shanghai",
                    "postcode": "200100",
                    "state": "shanghai",
                    "line1": "minghang pushenglu",
                    "line2": "room 2002"
                },
                "name": "zhangsan",
                "phone": "13527189021"
            },
            "merchant_no": "50000000000xxxx",
            "app_id": "www.xxx.com",
            "create_at": "2025-08-20T08:08:50Z",
            "modify_at": "2025-08-20T08:08:50Z",
            "first_name": "??",
            "last_name": "",
            "merchant_customer_id": "10000202508201xxxx"
        },
        "description": "T-shirt",
        "order": {
            "category": "Apparel and accessories",
            "products": [
                {
                    "name": "IPHONE7",
                    "code": "12334455",
                    "desc": "IPHONE 7",
                    "quantity": 5,
                    "sku": "100004",
                    "type": "physical",
                    "url": "https://www.xxx.com/item/12345",
                    "effective_end_at": "2020-12-31T23:59:59Z",
                    "effective_start_at": "2020-01-01T00:00:00Z"
                }
            ],
            "shipping": {
                "address": {
                    "city": "Shanghai",
                    "postcode": "100000",
                    "state": "Shanghai",
                    "line1": "Pudong District"
                },
                "first_name": "John",
                "last_name": "Doe",
                "shipping_method": "sameday"
            }
        },
        "metadata": {
            "id": 1
        },
        "confirm": false,
        "orderType": "sale",
        "sale": true,
        "merchant_no": "50000000000xxxx",
        "app_id": "www.xxx.com",
        "create_at": "2025-08-20T08:08:54Z",
        "modify_at": "2025-08-20T08:09:43Z",
        "merchant_order_id": "2025082016085xxx",
        "invoice_id": "inv_xxx",
        "customer_id": "cus_xxx",
        "payment_method_options": {
            "type": "card",
            "card": {
                "three_ds_action": "force_3ds",
                "authorization_type": "final_auth",
                "auto_capture": true
            }
        },
        "next_action": {
            "type": "redirect",
            "redirect": {
                "method": "GET",
                "url": "https://secure-auth.sandbox.useepay.com/threeDs?id=xxx",
                "content_type": "application/json"
            }
        },
        "return_url": "http://www.baidu.com",
        "client_secret": "xxx",
        "device_data": {
            "browser": {
                "java_enabled": false,
                "javascript_enabled": false,
                "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.212 Safari/537.36"
            },
            "language": "EN or en-US",
            "location": {
                "lat": "-37.81892",
                "lon": "144.95913"
            },
            "mobile": {
                "device_model": "Apple IPHONE 7",
                "os_type": "IOS or ANDROID",
                "os_version": "IOS 14.5"
            },
            "timezone": "-2 or 3:30",
            "accept_header": "*/*",
            "device_id": "00000000-000000000000000",
            "ip_address": "xx.xx.xx.xx",
            "screen_color_depth": 24,
            "screen_height": 1080,
            "screen_width": 1920
        },
        "auto_capture": true,
        "mandate_id": "xxx",
        "last_payment_error": {},
        "order_id": "xxx"
    }
}

Signature Verification

Before using the actual message content, to verify whether the message content has been tampered with during transmission, merchants can perform signature verification:
During signature verification, use the RSA Secret Key (UseePay Public Key) enabled in the mc backend to calculate the sign value using the following verification method. Compare this calculated sign value with the sign value in the request header. If they match, the signature verification is successful; otherwise, discard the current message.

For signature verification, you can refer to the following method:

Webhook 启用/验签步骤

第1步启用RSA秘钥

商户在mc后台-配置中心-秘钥管理处开启RSA秘钥-useepay公钥。此秘钥供商户验签使用。

第2步创建webhook

商户通过webhook创建接口创建webhookurl。

第3步接收异步通知

当触发了您的webhookurl所关联的事件后，UseePay会向该url（https格式）发送对应的异步通知。
您接收到消息后需要向UseePay响应http200，UseePay收到200即认为一次异步通知任务发送成功，否则重试发送。

第4步验签

异步消息内容格式如下：

请求头

参数	示例
merchant_no	50000000000xxxx
api_version	2024-10-10
app_id	www.pay.com
Content-Type	application/x-www-form-urlencoded
sign	Z8hLld5yZlZKNnQqZiwlZEYBJ4F2PAAxxxxxxxxxxxxxxx...

参数	示例
merchant_no	50000000000xxxx
api_version	2025-11-06
app_id	www.pay.com
Content-Type	application/json (暂不支持)
sign	Z8hLld5yZlZKNnQqZiwlZEYBJ4F2PAAxxxxxxxxxxxxxxx...

payload

data=%7B%22id%22%3A%22evt_7f560319eabb4127a9a282d1937b60dc%22%2C%22name%22%3A%22payment_intent.succeeded%22%2C%22data%22%3A%7B%22id%22%3A%221012506201612797898%22%2C%22amount%22%3A10%2C%22currency%22%3A%22USD%22%2C%22status%22%3A%22succeeded%22%2C%22customer%22%3A%7B%22id%22%3A%22cus_VEN6A8LP1G00%22%2C%22address%22%3A%7B%22country%22%3A%22CN%22%2C%22city%22%3A%22shanghai%22%2C%22postcode%22%3A%22200100%22%2C%22state%22%3A%22shanghai%22%2C%22line1%22%3A%22pudong%20zhangjiang%22%2C%22line2%22%3A%22room%201002%22%7D%2C%22description%22%3A%22test%20customer%22%2C%22name%22%3A%22team.liu%22%2C%22email%22%3A%22victor.yang%40useepay.com%22%2C%22phone%22%3A%2213127921181%22%2C%22metadata%22%3A%7B%22testkey%22%3A%2212233%22%7D%2C%22shipping%22%3A%7B%22address%22%3A%7B%22country%22%3A%22CN%22%2C%22city%22%3A%22shanghai%22%2C%22postcode%22%3A%22200100%22%2C%22state%22%3A%22shanghai%22%2C%22line1%22%3A%22minghang%20pushenglu%22%2C%22line2%22%3A%22room%202002%22%7D%2C%22name%22%3A%22zhangsan%22%2C%22phone%22%3A%2213527189021%22%7D%2C%22merchant_no%22%3A%22500000000009133%22%2C%22app_id%22%3A%22www.pay.com%22%2C%22create_at%22%3A%222025-06-20T08%3A12%3A09Z%22%2C%22modify_at%22%3A%222025-06-20T08%3A12%3A09Z%22%2C%22first_name%22%3A%22team%22%2C%22last_name%22%3A%22liu%22%2C%22merchant_customer_id%22%3A%22100002025062016041%22%7D%2C%22description%22%3A%22UseePay%20-%20T-shirt%22%2C%22order%22%3A%7B%22category%22%3A%22Apparel%20and%20accessories%22%2C%22products%22%3A%5B%7B%22name%22%3A%22IPHONE7%22%2C%22code%22%3A%2212334455%22%2C%22desc%22%3A%22IPHONE%207%22%2C%22quantity%22%3A5%2C%22sku%22%3A%22100004%22%2C%22type%22%3A%22physical%22%2C%22url%22%3A%22https%3A%2F%2Fwww.xxx.com%2Fitem%2F12345%22%2C%22effective_end_at%22%3A%222020-12-31T23%3A59%3A59Z%22%2C%22effective_start_at%22%3A%222020-01-01T00%3A00%3A00Z%22%7D%2C%7B%22name%22%3A%22IPHONE7%22%2C%22code%22%3A%2212334455%22%2C%22desc%22%3A%22IPHONE%207%22%2C%22quantity%22%3A5%2C%22sku%22%3A%22100004%22%2C%22type%22%3A%22physical%22%2C%22url%22%3A%22https%3A%2F%2Fwww.xxx.com%2Fitem%2F12345%22%2C%22effective_end_at%22%3A%222020-12-31T23%3A59%3A59Z%22%2C%22effective_start_at%22%3A%222020-01-01T00%3A00%3A00Z%22%7D%5D%2C%22shipping%22%3A%7B%22address%22%3A%7B%22city%22%3A%22Shanghai%22%2C%22postcode%22%3A%22100000%22%2C%22state%22%3A%22Shanghai%22%2C%22line1%22%3A%22Pudong%20District%22%7D%2C%22first_name%22%3A%22John%22%2C%22last_name%22%3A%22Doe%22%2C%22shipping_method%22%3A%22sameday%22%7D%7D%2C%22metadata%22%3A%7B%22id%22%3A1%7D%2C%22confirm%22%3Afalse%2C%22orderType%22%3A%22sale%22%2C%22mode%22%3A%22subscription%22%2C%22subscriptionId%22%3A%22sub_VEN6A9FT1G00%22%2C%22sale%22%3Atrue%2C%22merchant_no%22%3A%22500000000009133%22%2C%22app_id%22%3A%22www.pay.com%22%2C%22create_at%22%3A%222025-06-20T08%3A12%3A09Z%22%2C%22modify_at%22%3A%222025-06-20T08%3A12%3A09Z%22%2C%22merchant_order_id%22%3A%2220250620161209695%22%2C%22invoice_id%22%3A%22inv_VEN6AA6P1G00%22%2C%22customer_id%22%3A%22cus_VEN6A8LP1G00%22%2C%22available_payment_method_types%22%3A%5B%2217%22%2C%2212%22%2C%2215%22%2C%2213%22%2C%2212%22%2C%2215%22%2C%2214%22%2C%2201%22%2C%2202%22%2C%2202%22%2C%2205%22%2C%2202%22%2C%2202%22%2C%2202%22%2C%2202%22%2C%2202%22%2C%2205%22%5D%2C%22payment_method_options%22%3A%7B%22type%22%3A%22card%22%2C%22card%22%3A%7B%22three_ds_action%22%3A%22force_3ds%22%2C%22authorization_type%22%3A%22final_auth%22%2C%22auto_capture%22%3Atrue%7D%7D%2C%22next_action%22%3A%7B%22type%22%3A%22redirect%22%2C%22redirect%22%3A%7B%22method%22%3A%22GET%22%2C%22url%22%3A%22https%3A%2F%2Fcheckout1.uat.useepay.com%2Fv4%3Fpid%3D1012506201612797898%26secret%3Dd5d92897f4cbf1507c3149182ae0adde%22%2C%22content_type%22%3A%22application%2Fjson%22%7D%7D%2C%22return_url%22%3A%22http%3A%2F%2Fwww.baidu.com%22%2C%22client_secret%22%3A%22d5d92897f4cbf1507c3149182ae0adde%22%2C%22device_data%22%3A%7B%22browser%22%3A%7B%22java_enabled%22%3Afalse%2C%22javascript_enabled%22%3Afalse%2C%22user_agent%22%3A%22Mozilla%2F5.0%20%28Macintosh%3B%20Intel%20Mac%20OS%20X%2010_15_7%29%20AppleWebKit%2F537.36%20%28KHTML%2C%20like%20Gecko%29%20Chrome%2F90.0.4430.212%20Safari%2F537.36%22%7D%2C%22language%22%3A%22EN%20or%20en-US%22%2C%22location%22%3A%7B%22lat%22%3A%22-37.81892%22%2C%22lon%22%3A%22144.95913%22%7D%2C%22mobile%22%3A%7B%22device_model%22%3A%22Apple%20IPHONE%207%22%2C%22os_type%22%3A%22IOS%20or%20ANDROID%22%2C%22os_version%22%3A%22IOS%2014.5%22%7D%2C%22timezone%22%3A%22-2%20or%203%3A30%22%2C%22accept_header%22%3A%22*%2F*%22%2C%22device_id%22%3A%2200000000-000000000000000%22%2C%22ip_address%22%3A%22139.224.227.218%22%2C%22screen_color_depth%22%3A24%2C%22screen_height%22%3A1080%2C%22screen_width%22%3A1920%7D%2C%22auto_capture%22%3Atrue%2C%22mandate_id%22%3A%22man_VEN6AAQ11G00%22%2C%22order_id%22%3A%221012506201612797899%22%7D%7D

该data属性经过urldecode解码可以得到原始的消息内容

验签

在使用消息实际内容前，为了验证消息内容是否在传输中被篡改，商户可以进行验签：
验签时，使用mc后台启用的RSA秘钥（UseePay公钥）通过如下验签方法计算sign值，并和请求头中的sign值比对，一致则验签通过，否则丢弃当前消息。

验签可参考如下方法：

Webhook Activation/Signature Verification Steps

Step 1: Enable RSA Secret Key#

Step 2: Create a Webhook#

Step 3: Receive Asynchronous Notifications#

Step 4: Signature Verification#

Request Headers#

before 2026-04#

Payload#

after 2026-04#

Payload#

Signature Verification#

Webhook 启用/验签步骤#

第1步 启用RSA秘钥#

第2步 创建webhook#

第3步 接收异步通知#

第4步 验签#

请求头#

payload#

验签#

Step 1: Enable RSA Secret Key

Step 2: Create a Webhook

Step 3: Receive Asynchronous Notifications

Step 4: Signature Verification

Request Headers

before 2026-04

Payload

after 2026-04

Payload

Signature Verification

Webhook 启用/验签步骤

第1步启用RSA秘钥

第2步创建webhook

第3步接收异步通知

第4步验签

请求头

payload

验签