Asynchronous Notifications

Throughout an order's lifecycle, we send an asynchronous notification to notify_url for every status change. The receiving endpoint must use https. Notifications include a signature and payment parameters (in json format).

Tip

1. The notification URL is the submitted notify_url. After payment completion, YabandPay sends the relevant payment and user information to this URL. The third-party acquiring institution must receive the notification and verify its signature before taking any further action.

2. During server notification exchanges, if the third-party acquiring institution returns a non-success response or the request times out, YabandPay considers the notification unsuccessful. YabandPay periodically retries notifications according to its retry strategy to maximize delivery success, but does not guarantee eventual delivery.

3. Because server notifications may be retried, the same notification may be sent to the partner system multiple times. The partner system must handle duplicate notifications correctly. We recommend first checking the state of the corresponding business data when processing a notification to determine whether it has already been handled. Process it only if it has not been handled; otherwise, return success immediately. Before checking and processing the business data, use data locks for concurrency control to prevent data inconsistencies caused by function reentry.

4. YabandPay sends asynchronous notifications from the following IP addresses. We recommend adding them to your firewall allowlist. 8.211.41.31 8.211.10.244 8.211.8.123

1. Asynchronous payment notifications

3DS response statuses:

Example asynchronous notification:

{
	"sign": "YOUR_SIGNATURE",
	"data": {
		"type": "payment",
		"user": "YOUR_CASHIER_UID",
		"order_id": "YOUR_ORDER_ID",
		"trade_id": "8a8aa7c7-66d7-e2cc-e2a6-fff7c77aaefd",
		"transaction_id": "4200000298201905227377147799",
		"acquirer_id": "4200000298201905227377147799",
		"yb_transaction_id": "c8823612-383f-35fc-f28d-c0eae039e870",
		"amount": "1.00",
		"tip_amount": "0.10",
		"currency": "EUR",
		"settlement_amount": "1.00",
		"settlement_currency": "EUR",
		"exchange_rate": "1",
		"amount_cny": "0.77",
		"settlement_rate": "7.779779",
		"description": "yaband test",
		"createDate": "1558510731",
		"pay_method": "online",
		"state": "paid",
		"demo": "test",
		"out_trade_no": "a4d7684a-e326-44c1-bea5-0601f7a9b191",
		"sub_pay_method": "WeChat Pay",
		"paid_time": "1603355159",
		"3ds_status": "Y",
		"3ds_trxid": "1d0c6eb3-6282-4cf9-9549-884410918d2d",
		"3ds_version": "2.2.0"
	}

}

2. Asynchronous refund notifications

Notification information：

{
	"sign": "YOUR_SIGNATURE",
	"data":  {
		"type": "refund",
		"user": "YOUR_CASHIER_UID",
		"refund_id": "b20d3668-d71f-432f-8809-f84f0d9139d4",
		"m_refund_id":"20240301143029616187",
        "transaction_id":"cf483d9e-637c-a92d-0716-5b8199d10f8c",
		"refund_amount": "1.00",
		"refund_currency": "EUR",
		"order_id": "YOUR_ORDER_ID",
		"refund_description": "test",
		"refund_time": "0",
		"state": "refunded",
		"pay_method": "online",
		"sub_pay_method": "WeChat Pay"}
}   

Tip

1. After a refund is submitted, we return the status refund processing.

2. Once the refund is complete, we send a notification with the status refunded.

3. Asynchronous notification frequency

Please note: The notification response must return status-code 200 and “ok” in the body. If “ok” is not returned, we will send the notification again.

The notification frequency is as follows:

If we do not receive the correct ok response, we stop sending notifications after 15 attempts.

4. Payment status descriptions in asynchronous notifications

1. Payment statuses:

2. Refund statuses: