Asynchronous Notification

For transactions processed through SparkPay, SparkPay will send payment results as parameters via POST request to the merchant's system using the notify_url (asynchronous notification address) specified in the [Unified Payment Order Creation. See the notification details below.

1 Asynchronous Notification Parameters

Parameter	Type	Required	Description
head	Object	Yes	Key-related information object
body	Object	Yes	Encrypted data object

Below is a body request example

{
    "head": {
        "charset": "UTF-8",
        "aes_key": "Ze/5ORmCGEoJJoofNtYijD6QRNc1IGsMoOBP0nYvgfGskFI+xiweDdifLiphX8K3icNEYS5rajflqIZ29HyIJXKd7XEsfiyTX9WdLxOKdZn/0A8COtJeVrme+5bi30yNJbjox/5C0gK6+39uKtFGW85rVGoKNuU/6SbH2pzTSNn8oc6OJjphTV52G8jAKPiQxnHFWAmPWmy1IvhbRmLjCTQaTk3mNsauRSZacF3xNtvuVkZ6ZnGyJimh834TOC9vp8KEdO8/eA8HjFAFOA/G0CqCg4Fqeb8kkbH+1rA9BWx7++a5qhQQRLKtu7CPRO+HaJt1xtYXSgbhL9u4P1PSZg==",
        "app_id": "qufsSeu0Eec",
        "sign": "L1W+wtcGyDfwTSMWz10Iv5kgPV4cbQQWhNU0k9hCVizLHFEzP0viL52INdxANo4imJyBqROLD86UXooSsPKHwTD0y8/nts9bdsQZ+6e+LTpzaUjHYGKqJd/5gocmoqkztNA+qkM/8YnZOcKHH8s8wwapTbiN/mZ39k4zVwuRLflsMkpoIklTROAikx832KEeQwY7L3AQI1VUe69oilBoWO8gMuobCU8gNzOIaPLlAsrPewydiXiMmpx/ZRGANoVlFsMufohWL6XWuOGh2ykUxS4aRcOKgx11c6sw73gHrUO0J9/Fwf76oPs2P96/TwbocVxBNKiRLFIMfO3R6vfWoQ=="
    },
    "body": "3L8m0wA4D2KziM10Oh5Lo/IaqFldsDhOj1sdUo0Yzmeq+TfMQZfJRtIQ5LJOzW5Mv9EQTQAhVWkrQSojLzZGm864qmcxFf9K0FKqLesG+SAT/C/Qt1TO24pfkeibvN60XYWR4+LInD3t0C3yLBGo8A46eSuV/+JLf/MFjnYv+rEhzXaArJ/D7r/dIjDXMmzW2lLvB2k/JW5T+nqy2io7MKp19ln9Ki+uCUgIIiA4tzfz9s7ZnGpptHJowuaqmeg2NMmcCGtMR6/m+qPKAVOps3RUe1PMZOILSqRZjkH7jhMmIvO+DCBBKGK3ZgLVfGVZ5zrgRMFz//4AK2Ta7ZO635pMLMKYKNpS0qPECLGZfwM9U1moCv4eSHUXWcVCdCmnJSf1Q+GQ23oWyxSMvnKfsSmrY3GsKYFGXUOeRLEB5mogdUr/vx5/OiTJaWlrCabDwdoyLEdfOC2ZChfBivNgUvWX+oC4fBuIlj8Geq18McrcinehnvFb5nbkGSSMn/2T3S0zw2t6+ZPvOjzhOUktPdc/KJlqAEYRz1ZOtT7V99rmVjdF/h8Yk30Cunz0Cv3KyHgRrawbcHARdbsCsVGfgCtAWEWgJuzx/Kvs4t5POezt1SvXyWf91X7A1AN/zFhhQtgloiSXsvlCfffKh2HDrLrjncE7FCyfpPIYKdRHbsCcbVaWB7dunb93ddf+C15i"
}

2 Asynchronous Notification Details

Notification Mechanism: If the payment platform receives a non-compliant response or timeout from the merchant, it considers the notification failed and will reinitiate notifications (at intervals of 10s/1m/5m/10m/30m/1h/2h) to maximize the success rate, though final success is not guaranteed.

Reception Mechanism: Asynchronous notification header is Content-Type:application/json

Request Business Message Encryption Details (Required for merchant application integration):

The public key used to encrypt the AES key is the merchant application's RSA public key. The RSA encryption uses RSAES-OAEP padding scheme, with SHA256 as the OAEP hash algorithm.

Request parameter JSON string encryption uses AES-256/CBC/PKCS5Padding algorithm, with the AES key being the pre-encrypted key (32-character string length, iv takes the first 16 characters of the key).

Both the encrypted request parameter JSON string and AES key use standard base64 encoding.

The signature value of the request parameter JSON string also uses base64 encoding.

Request Business Message Processing Method: Interface request field data uses standard base64 encoding and needs to be decoded first.

aes_key: Use merchant RSA private key to decrypt aes_key to obtain AESKEY.

body: Use AESKEY to decrypt and obtain payment result notification parameter JSON string.

sign: Verify signature using the payment platform public key with the notification parameter JSON string.

Response Method: Status code: 200; Response message: "SUCCESS".

Important Notes:

Asynchronous notification notify_url must be a complete URL starting with https:// or http://, ensuring the domain name and IP are publicly accessible.

notify_url code processing logic must not include login status verification.

The merchant's async address (notify_url) must be free of any characters like spaces or HTML tags, and cannot redirect.

Merchant systems must respond within the platform's specified timeframe after receiving notifications, or the platform will consider it failed and resend notifications.

Merchants with firewall restrictions must whitelist the payment center's specified IP ranges.

The same notification may be sent multiple times; merchant systems must handle duplicate notifications correctly. If already processed, return success to the payment platform.

3 Decrypted Parameter Description

3 Decrypted Parameter Specifications

Field Name	Type	Description	Required
notify_id	string	Unique notification ID	Required
notify_time	int64	Server timestamp when message was sent	Required
request_no	string	Merchant request number	Required
pay_order_no	string	Payment platform order number	Required
pay_status	string	Payment status COMPLETED: Completed	Required
completed_time	int64	Payment completion time	Required
merchant_order_no	string	Merchant platform order number	Required
goods_info	string	Product information	Required
real_pay_amount	string	(Deprecated) Payment amount, please use payment_amount	Required
pricing_amount	string	Pricing amount	Required
pricing_currency	string	Pricing currency	Required
total_amount	string	(Deprecated) Total amount, please use pricing_amount	Required
payment_amount	string	Payment amount	Required
merchant_application_user_id	string	Merchant platform user ID	Required
currency	string	(Deprecated) Payment currency, please use payment_currency	Required
payment_currency	string	Payment currency	Required
merchant_no	string	Merchant customer number	Required
payer_addr	string	Payer's chain address	Required
tx_hash	string	Transaction hash	Required
pay_network	int32	Payment network, see network enumeration	Required
app_id	string	Merchant app_id	Required

4 Transaction Status Description

Enum Name	Description
COMPLETED	Completed

5 Asynchronous Return Result Signature Verification

Please refer to the php code's Handle Asychronous Notification

1 Asynchronous Notification Parameters#

2 Asynchronous Notification Details#

3 Decrypted Parameter Description#

3 Decrypted Parameter Specifications#