BIEASES payment gateway supports a callback with the callback URL Setting in the Create Payment Operation. The callback URL can be changed for each of the requests. However, we do not recommend that as that might be blocked by the security control if you change the callback URL frequently. Please use a fixed callback URL if that is possible. You can change that anytime, but before that make sure the new callback URL is reachable.

Setup

Merchant customs can use the callback URL Parameter to get notified while the payment order gets processed.

The webhook process workflow

Event List

The webhook callback event list.

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 the below 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 a HTTP 200 success status.

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

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. And please refer to Webhook Event Names to find all of the supported event names.

Payment result objects

Created order callback

Refund order callback