The BIEASES payment system requires merchants to create a payment order before payment checkout. Once the payment order is created, BIEASES will return the payment order information.

The merchant platform should redirect to the checkout page to allow the consumer to complete the payment.

Request

Request payload

POST  /cgi/payment/api/v1/payment-order HTTP/1.1
Content-Type: application/json

{
    "merchantId": "string",
    "method": "string",
    "format": "string",
    "charset": "string",
    "encryptType": "string",
    "signType": "string",
    "sign": "string",
    "timestamp": "Number",
    "body": "[encrypted body string]"
}

Encrypted Body Structure:

{
    "order": {
        "orderNo": "string",
        "orderAmount": "Number",
        "orderDescription": "string",
        "goods": [{
            "referenceGoodsId": "string",
            "goodsName": "string",
            "goodsDesc": "string",
            "goodsUnitAmount": "Number",
            "goodsQuantity": "Number"
        }]
    },
    "channel": "string",
    "paymentAmount": "string",
    "currency": "string",
    "paymentTime": "Timestamp",
    "paymentExpiryTime": "Timestamp",
    "callbackUrl": "string",
    "redirectUrl": "string"
}

Please refer to Request Payload for more information regarding the payload JSON.

Set the method parameter to bieases.trade.create.
Set to body parameter to Body object.

Body object

The body parameter object in the Request Payload .

Key	Type	Mandatory?	Length	Description	Example
channel	String	Yes	*	The channel where the order was created. Supported value: • WEB • APP
paymentAmount	Number	Yes	*	The payment amount regarding the payment order. • An integer for currencies like JPY that are not typically fractional. • A decimal fraction for currencies like TND that are subdivided into thousandths.	25.37
currency	String	Yes	*	The currency code. ISO 4217	USD
paymentTime	Timestamp	Yes	*	The timestamp for the payment order time.
paymentExpiryTime	Timestamp	Yes	*	The timestamp for the payment expiration time. This determines how long the payment order will be kept on the BIEASES server before it expires. The time range for expiration can be 5 minutes to 24 hours.
callbackUrl	String	No	2048	The callback webhook address.	https://merchant_server_name/payment/callback
redirectUrl	String	No	2048	The redirect URL. Usually used to navigate back to the merchant order result page once the payment has been settled.	https://merchant_server_name/order/111/result
order	Object	Yes		Refer to the order object

Order object

Key	Type	Mandatory?	Length	Description	Example
orderNo	String	Yes	64	The order number on the merchant's platform	2013112111001004500000675971
orderAmount	Number	Yes	*	The total order amount should equal sum of amount * quantity across all items for a given goods. • An integer for currencies like JPY that are not typically fractional. • A decimal fraction for currencies like TND that are subdivided into thousandths.	25.37
tips	Number	No		The customer give merchant tips amount. • An integer for currencies like JPY that are not typically fractional. • A decimal fraction for currencies like TND that are subdivided into thousandths.	2.00
discount	Number	No		The order discount amount, if it has one. • An integer for currencies like JPY that are not typically fractional. • A decimal fraction for currencies like TND that are subdivided into thousandths.	0.37
totalTax	Number	No		The order total tax amount, should equal sum of tax * quantity across all items for a given goods. • An integer for currencies like JPY that are not typically fractional. • A decimal fraction for currencies like TND that are subdivided into thousandths.
insurance	Number	No		The order insurance amount, if it has one. • An integer for currencies like JPY that are not typically fractional. • A decimal fraction for currencies like TND that are subdivided into thousandths.
handlingFee	Number	No		The order handling fee, if it has one. • An integer for currencies like JPY that are not typically fractional. • A decimal fraction for currencies like TND that are subdivided into thousandths.
shipping	Object	No		The order shipping info
shippingDiscount	Number	No		The order shipping fee discount, if it has one
orderDescription	String	No	256	The order description	xxx
goods	Array	Yes	*	The goods object list (max 100 elements).

Goods object

Key	Type	Mandatory?	Length	Description	Example
referenceGoodsId	String	Yes	64	The goods item ID.	821e1c32-4a6c-442e-b5ce-8ec5b902d11c
goodsName	String	Yes	256	The goods item name.	Paper tower
goodsDesc	String	No	256	The goods item description.	White kitchen paper tower
goodsAmount	Number	No	*	The good amount per individual good. • An integer for currencies like JPY that are not typically fractional. • A decimal fraction for currencies like TND that are subdivided into thousandths.	2.45
tax	Number	No		The tax amount per individual good. • An integer for currencies like JPY that are not typically fractional. • A decimal fraction for currencies like TND that are subdivided into thousandths.	0.40
goodsQuantity	Number	No	*	The quantity for each individual good.	2

Shipping_ object

Key	Type	Mandatory?	Description	Example
shipType	String	Yes	The ship type where the order will be delivered. Supported values: • SHIPPING • PICKUP_IN_STORE • PICKUP_FROM_PERSON
amount	Number	No	The shipping fee amount. • An integer for currencies like JPY that are not typically fractional. • A decimal fraction for currencies like TND that are subdivided into thousandths.	2.45
name	String	Yes	The receiver name	John Doe
address	String	No	The receiver address

Response

Response payload

200 OK
Content-Type: "application/json"

{
    "code": "20000",
    "msg": "SUCCESS",
    "data": 
    {
       "paymentId":"",
       "referOrderNo":"",
       "channel":"",
       "checkoutUrl":"",
       "status":"",
    }
}

The request will return an HTTP status code 200 if successful, with details included in the data object of the response payload.

data object defined as below

📘 Note

The response is returned synchronously and does not require signature verification and decryption.

Data object

Key	Type	Length	Description	Example
paymentId	String	32	The payment order number regarding the payment request.	1754349465357123584
referOrderNo	String	32	The order number from the merchant's platform.	2013112111001004500000675971
channel	String	*	The channel where the order was created. Supported values: • WEB • APP	APP
checkoutUrl	String	2048	The payment checkout URL. Once the merchant gets this URL, the merchant should be redirected to this page to allow the consumer to complete the payment order.	https://pay-eu.bieases.com/user/login?paymentId=tAjn4xewdsd0DJ12345pocHHXuVaOL9
status	String		The payment order status.	"pending"

Examples

Follow the steps below to construct the payment request message.

Construct the request object.

{
    "merchantId": "B131567545069",
    "method": "bieases.trade.create",
    "format": "json",
    "charset": "utf-8",
    "encryptType": "AES",
    "signType": "RSA",
    "timestamp": 1706585572074,
    "body": { 
        "order": {
            "orderNo": "111111111111111",
            "orderAmount": "10.0",
            "orderDescription": "",
            "goods": [{
                "referenceGoodsId": "213111131",
                "goodsName": "fans",
                "goodsDesc": "",
                "goodsUnitAmount": "1",
                "goodsQuantity": "3"
            }]
       },
       "channel": "Web",
       "paymentAmount": "100.0",
       "currency": "USD",
       "paymentTime": "7065855724",
       "paymentExpiryTime": "7065856724",
       "callbackUrl": "https://merchantserverhost/pay/complete/callback/url",
       "redirectUrl": "https://merchantserverhost/pay/complete/redirect/url"
   }
}

Sign the request and add the signature to the request body.

{
    "merchantId": "B131567545069",
    "method": "bieases.trade.create",
    "format": "json",
    "charset": "utf-8",
    "encryptType": "AES",
    "signType": "RSA",
	   
    // Add the signature to the request parameter
    "sign": "hcsZg0q6...E3BdbHlf03HPpIg==",

    "timestamp": 1706585572074,
    "body": { 
        "order": {
            "orderNo": "111111111111111",
            "orderAmount": "10.0",
            "orderDescription": "",
            "goods": [{
                "referenceGoodsId": "213111131",
                "goodsName": "fans",
                "goodsDesc": "",
                "goodsUnitAmount": "1",
                "goodsQuantity": "3"
            }]
       },
       "channel": "Web",
       "paymentAmount": "100.0",
       "currency": "USD",
       "paymentTime": "7065855724",
       "paymentExpiryTime": "7065856724",
       "callbackUrl": "https://merchantserverhost/pay/complete/callback/url",
       "redirectUrl": "https://merchantserverhost/pay/complete/redirect/url"
   }
}

Encrypt the Body Object
Refer to the Request Sandbox Access Or Request production secure keys To get your AES encrypt key.

String body ="{Payment Object JSON String}";// The payment object JSON string which is constructed in step 1.

//encrypt the body with the given AES encrypt key from BIEASES.
String encryptedBody = AesEncrypt.encrypt(body, aesEncryptKey, "UTF-8");
//for example: "7K2AyShlt...CX98jEGVWA=="

Replace the body parameter with the encrypted value.

{
    "merchantId": "B131567545069",
    "method": "bieases.trade.create",
    "format": "json",
    "charset": "utf-8",
    "encryptType": "AES",
    "signType": "RSA",
  	
     // Add the signature to the request parameter
    "sign": "hcsZ...3HPpIg==",

    "timestamp": 1706585572074,

    // Encrypted payment object
    "body": "7K2A...VWA=="
}

Send the request to the BIEASES payment API.

POST /cgi/payment/api/v1/payment-order HTTP 1.1
Content-Type: "application/json"

{
    "merchantId": "B131567545069",
    "method": "bieases.trade.create",
    "format": "json",
    "charset": "UTF-8",
    "encryptType": "AES",
    "signType": "RSA",
    "sign": "hcsZ...3HPpIg==",
    "timestamp": "1706585572074",
    "body": "7K2AySh...VWA=="
}

The following JSON shows an example of the Create Payment request being returned when you requested.

200 OK
Content-Type: "application/json"

{
    "code": "20000",
    "msg": "SUCCESS",
    "data": 
    {
       "paymentId":"",
       "referOrderNo":"",
       "channel":"",
       "checkoutUrl":"",
       "status":"",
    }
}

Verify the signature and decrypt The body to hand the response as your logic.

Request payload​

Body object​

Order object​

Goods object​

Shipping_ object​