Asynchronous Notification

List of Interfaces Supporting Asynchronous Notification

When the notifyUrl parameter is passed in the following interface requests, an asynchronous notification will be sent upon completion of the transaction.

Interface Name	Description
basicexpay.trade.precreate	Transaction Pre-Creation
basicexpay.trade.cashier	Cashier Payment
basicexpay.trade.agentpay	Agent Payment

Notification Security

1. IP Whitelist: To ensure the security of system transactions, we recommend adding our notification service external IP to your whitelist. When you receive a notification callback from us, please verify the external IP of the sender. Please contact our customer service team to obtain the notification service external IP.

2. Signature Verification: The notification callback we send also includes a sign parameter. Please make sure to refer to the Security Requirements -> Signature Method and Security Requirements -> Message Signature to sign and verify the content of the notification callback.

3. Data Validation: After validating the signature, please rigorously verify whether the merOrderNo in the notification data matches the order number created in the merchant's system. If the verification fails, it means that the notification is abnormal, and it should be ignored.

Signature Verification

For example, if the merchant initiates a payment transaction and sets the notification address to https://api.xx.com/receive_notify.htm, the received notification will have the following format:

{
  "code": "0000",
  "data": "{\"attach\":\"\",\"currency\":\"USDT\",\"merOrderNo\":\"Mt72csbcTW5x8ypD\",\"orderNo\":\"40620230325105240025986621030533\",\"status\":2,\"totalAmount\":11.75}",
  "message": "Transaction Successful",
  "method": "basicexpay.trade.notify",
  "nonce": "ziOWAlDvaQCMegoy",
  "sign": "42FEB0B73D3F79F0C8E056AEF88F5E3FA655D2AEC2AB8D561FB9EDBE85A9A872F49428BD3B327A8C3629929629D7CFF8B59736911894419A13B8970482F4E10C",
  "signType": "HmacSHA512",
  "timestamp": "20230325130255"
}

Step 1: In the notification response parameter list, remove the sign parameter. All remaining parameters are the ones to be verified.

Step 2: Sort the remaining parameters in alphabetical order and arrange them in URL key-value format to form a string, resulting in the string to be signed:

{
code=0000&data={"attach":"","currency":"USDT","merOrderNo":"Mt72csbcTW5x8ypD","orderNo":"40620230325105240025986621030533","status":2,"totalAmount":11.75}&message=Transaction Successful&method=basicexpay.trade.notify&nonce=ziOWAlDvaQCMegoy&signType=HmacSHA512&timestamp=20230325130255
}

Step 3: Append the key parameter to the end of the string. The value of the key is the apikey secret. This creates the string to be signed, signTemp. Then, apply HMAC-SHA512 operation on signTemp using the secretkey secret, convert the resulting string to uppercase, and obtain the final signature value, signValue:

{
code=0000&data={"attach":"","currency":"USDT","merOrderNo":"Mt72csbcTW5x8ypD","orderNo":"40620230325105240025986621030533","status":2,"totalAmount":11.75}&message=Transaction Successful&method=basicexpay.trade.notify&nonce=ziOWAlDvaQCMegoy&signType=HmacSHA512&timestamp=20230325130255&key=xxxxxxxxxxx
}

Step 4: Verify the signature's correctness.

Notification Content

1. The common parameters of the notification callback are consistent with the Common Parameters -> Response Parameter Description.
2. The method parameter of the notification callback is basicexpay.trade.notify.
3. The response parameters for completed payment transactions in the notification callback are consistent with the Transaction Message -> Transaction Result Query response parameters.
4. The response parameters for completed agent payment transactions in the notification callback are consistent with the Transaction Message -> Agent Payment Result Query response parameters.

Notification Response

After the merchant receives the notification callback and completes the processing, please directly return the string "success" to indicate successful receipt. If the system receives anything other than "success," it will retry the notification according to a certain strategy. Merchants should implement idempotent handling on their side. When BasicEx receives a response other than "success," it will consider the notification as a failure and will periodically retry the notification according to a specific strategy. The interval for notifications is: 15s, 15s, 30s, 180s, 300s, 600s, 1200s, 1800s, 3600s.