Notify Payment

Notify Scenario

• After the payment is completed, the payment center will send the relevant payment results and related information to the merchant, and the merchant needs to receive and process it and return a response. When interacting with notifications in the background, if the payment center receives a response from the merchant that is not successful or timed out, the payment center considers the notification to fail, and will periodically re-send the notification within a certain strategy to increase the success rate of the notification as much as possible. However, there is no guarantee that the notification will ultimately succeed. (The notification frequency is 15/15/30/180/1800/1800/1800/1800/3600 , unit: seconds)

Tips

• The same notification may be sent to the merchant system multiple times. Merchant systems must be able to properly handle duplicate notifications. The recommended practice is that when receiving a notification for processing, first check the status of the corresponding business data to determine whether the notification has been processed. Before checking and processing business data, use data locks for concurrency control to avoid data confusion caused by function reentrancy.

• Special reminder: The merchant system must perform signature verification on the content of the order callback, and verify whether the returned order amount is consistent with the order amount on the merchant side, to prevent data leakage from causing "false notifications", cause financial loss.

Notify Gateway

• Unify the settings of the parameter notify_url submitted by the order interface.
• If the link cannot be accessed, your business system will not be able to receive notifications from the payment center.

Notify Request

Parameter Name	Variable Name	Type	Required	Example	Comment
Return Code	result_code	string	TRUE	OK	Result Code. OK: Success, Other: Failure
Return Message	result_msg	string	TRUE	SUCCESS	Prompt Information. SUCCESS: success
Payload	charge	object	TRUE		Return the payment payload object (please see the specific data below)

Example:

{
	"result_code": "OK",
	"result_msg": "SUCCESS",
	"charge": {
		"uid": 100000,
		"userid": "U123456789",
		"out_trade_no": "23092024181832904",
		"trade_no": "03e1afadd4dee63f69e111804b09d400",
		"in_trade_no": "",
		"subject": "pay_test",
		"body": "pay_test",
		"channel": "vnpay_napas_vietqr",
		"paytype": 1,
		"extra": "[]",
		"currency": "VND",
		"amount": "15000.000",
		"order_amount": "15000.000",
		"pay_amount": "15000.000",
		"amount_paid": "15000.000",
		"keyword": null,
		"urate": "0.015",
		"ufixed_fee": "0.000",
		"user_in": "14775.000",
		"client_ip": "127.0.0.1",
		"return_url": "http://localhost:8001/demo.html",
		"notify_url": "http://localhost:8001/cashier/demonotify",
		"image_list": null,
		"image_text": null,
		"remark": null,
		"create_time": 1727086713,
		"update_time": 1727087865,
		"out_status": 23,
		"status": 2,
		"is_status": 0,
		"merchant_wallet": {
			"uid": 100000,
			"currency": "VND",
			"total_limit_credits": "-1000000000.00",
			"total_security_deposit_credits": "0.00",
			"total_unsettled_credits": "136131.33",
			"total_hold_credits": "0.00",
			"total_commission_credits": "229.47",
			"total_available_credits": "-42728.13"
		}
	}
}

Tips

The following is the data sample of the successful callback

• [status] is order business status

  • 0-closed
  • 1-waiting
  • 2-success
  • 3-failure
  • 4-paying
  • 5-settled
  • 6-refunded
  • 7-dispute

• [out_status] is merchant trade order status

  • 0-player cancel payment
  • 10-merchant cancel payment
  • 1-waiting
  • 21-player confirm success
  • 22-merchant confirm success
  • 23-gateway confirm success
  • 24-bank confirm success
  • 31-player confirm failure
  • 32-merchant confirm failure
  • 33-gateway confirm failure
  • 34-bank confirm failure
  • 4-paying
  • 5-settled
  • 6-refunded
  • 7-dispute

• [amount] Credit amount: Merchants and members should credit this amount

• [order_amount] Order amount: The original amount of the payment order placed by the merchant

• [pay_amount] Cashier amount: The payable amount shown to members in cashier page

• [amount_paid] Received amount: the actual amount received by our bank/wallet

Notify Response

• The following is a sample data for a successful response

{
    "result_code": "OK",
    "result_msg": "SUCCESS"
}

• The following is a sample data of a failed response

{
    "result_code": "OK",
    "result_msg": "FAIL"
}

Tips

• if receive our notify and verify signature successfully, then give back successful response
• if want to receive same notify continuedly, then give back failed response