Webhook

The BIEASES payment API supports callbacks through the callback URL setting in the Create Payment operation. The callback URL can be changed for each request. However, we do not recommend this as it might be blocked by security controls if you change the callback URL frequently. Please use a fixed callback URL if possible. You can change it anytime, but before doing so, ensure the new callback URL is reachable.

Setup

Merchant customers can use the callback URL parameter to receive notifications when the payment order is processed.

The webhook process workflow

Event List

The webhook callback event list.

Event Name	Description	Related Endpoint
payment.order.confirming	The consumer has submitted the payment request and it is pending for BIEASES backend to process.	Create Payment
payment.order.timeout	The payment order has not been paid within the given period.	Create Payment
payment.order.success	The payment order has been paid successfully by the consumer.	Create Payment
payment.order.failed	The payment order payment failed. Refer to the "msg" field in Payment result object for the failure reason.	Create Payment
payment.refund.success	The payment refund was completed successfully.	Refund Payment
payment.refund.failed	The payment refund request failed. Refer to the "msg" field in Payment result object for the failure reason.	Refund Payment

Handle callback

The callback message is constructed with two parts, one is used for the basic request information, and another represents the payment result details.

Please follow these steps to process the callback message:

1. Verify the signature.
2. Handle the callback message with your code.
3. Respond to the callback message synchronously with an HTTP 200 success status.

Webhook Response

200
Content-Type: application/json

{
  "code": 20000,
  "msg": ""
}

📘

Note:

• The confirmation message does not require signature and encryption. Just return a simple message through the HTTP response.
• Your listener should be an app or script deployed at the corresponding URL that listens on HTTPS port 443. For webhook message deliveries to be successful, the listener must respond with an HTTP 200 success status every time. Otherwise, BIEASES will retry each delivery up to 8 times over 7 days.
  • For example, if there is no response, BIEASES cannot connect, or if the server responds with a 404 or 500 error

Callback message structure

Webhook Request

POST  /callbackUrl/  HTTP/1.1
Content-Type: application/json

{
    "id":"string",//the webhook id
    "merchantId": "string",
    "eventName": "string",//webhook event name
  	"format":"string",
    "charset":"string",
    "encryptType":"string",
    "signType":"string",
    "sign": "string",
    "timestamp": "string",
    "body": "<encrypted body string>" // the encrypted body string
    
    // the body data structure example, for more information please refer to "Created order callback" and "Refund order callback" object defination.
    // "body": { 
    //     "merchantId":"string",
    //     "outOrderNo":"string",
    //     "status":"string",
    //     "msg":"string",
    //     "paymentAmount":"string",
    //     "currency":"string",
    //     "paymentTime":"string",
    //     "paidTime":"string"
    // }
}

Please refer to Webhook Callback Payload for more information. Also, please refer to Webhook Event Names to find all supported event names.

Payment result objects

Created order callback

Key	Type	Description	Example
merchantId	String	The merchant wallet ID which can be found at merchant wallet: Home->Merchant Information->BIEASES ID	B131567545069
referOrderNo	String	The order number on the Merchant's platform	2013112111001004500000675971
transactionId	String	The wallet transaction id	8zzsLUsjPaJBDQMM86bVh2ou7f6y8W
paymentAmount	Number	Payment amount.	21.55
currency	String	The payment currency code. Refer to ISO 4217.	USD
paymentTime	Timestamp	Payment creation time. It's a timestamp .	1706585572074
completeTime	Timestamp	Payment completion time. It's a timestamp .	1706585572074
status	String	The payment order status.
msg	String	The status message if there is any exception in the payment order.

Refund order callback

Key	Type	Description	Example
merchantId	String	The merchant wallet ID which can be found in the merchant wallet: Home->Merchant Information->BIEASES ID	B131567545069
refundId	String	The refund number for the payment	2013112111001004500000675973
paymentId	String	The payment order number for the payment request	01J143NWJFNGBV2YB9ZRB9T7PS
referRefundNo	String	The refund order number on the merchant's platform	2013112111001004500000675971
transactionId	String	The wallet transaction ID	8zzsLUsjPaJBDQMM86bVh2ou7f6y8W
refundAmount	Number	Refunded amount	21.55
refundTime	Timestamp	The refund creation time. It's a timestamp	1706585572074
completeTime	Timestamp	The refund request completion time. It's a timestamp. The request being completed does not mean the refund was successful. It just means that the transaction has completed either successfully or with failure.	1706585572074
status	String	The payment order status.
msg	String	The status message if there is any exception in the refund order.