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

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

Request

Request payload

POST  /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>" // the encrypted body string
    
    // the body data 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 integerfor currencies like JPY that are not typically fractional. A decimalfraction 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 payment order time.
paymentExpiryTime	Timestamp	Yes		Thetimestamp payment expiration time. How long will the payment order be kept on the BIEASES server before it gets paid the time range of the expiration can be5 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 integerfor currencies like JPY that are not typically fractional. A decimalfraction for currencies like TND that are subdivided into thousandths.	25.37
tips	Number	No		The customer give merchant tips amount. An integerfor currencies like JPY that are not typically fractional. A decimalfraction for currencies like TND that are subdivided into thousandths.	2.00
discount	Number	No		The order discount amount .if it have An integerfor currencies like JPY that are not typically fractional. A decimalfraction for currencies like TND that are subdivided into thousandths.	0.37
totalTax	Number	No		The order totalTax amount, should equal sum of tax * quantity across all items for a given goods An integerfor currencies like JPY that are not typically fractional. A decimalfraction for currencies like TND that are subdivided into thousandths.
insurance	Number	No		The order insurance amount, if it have An integerfor currencies like JPY that are not typically fractional. A decimalfraction for currencies like TND that are subdivided into thousandths.
handlingFee	Number	No		The order hand fee, if it have An integerfor currencies like JPY that are not typically fractional. A decimalfraction 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
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 individual good. An integerfor currencies like JPY that are not typically fractional. A decimalfraction for currencies like TND that are subdivided into thousandths.	2.45
tax	Number	No		The tax amount individual good. An integerfor currencies like JPY that are not typically fractional. A decimalfraction 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 shipType where the order will be give. Supported value: SHIPPING PICKUP_IN_STORE PICKUP_FROM_PERSON
amount	Number	No	The shipping fee amount An integerfor currencies like JPY that are not typically fractional. A decimalfraction for currencies like TND that are subdivided into thousandths.	2.45
name	String	Yes	The receiver name	Jacob
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 be returned with HTTP status code 200 if success and details included in the data object of the response payload.

data object defined as below

📘
Note
The response is returned synchronous 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 Merchant's platform.	2013112111001004500000675971
channel	String		The channel where the order was created. Supported value: 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 let the end user complete the payment order.	https://pay-eu.bieases.com/user/login?paymentId=tAjn4xewdsd0DJJCsfpocHHXuVaOL9
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": "hcsZg0q6sLm4gRQ97MBAlkNFAJCFXUAlnxlJCzjjwNwJJ9i8JIXoFjnzi6zRpyt6Vw7RGiUvUsLCq6PSUEIQ4B45ZaOCZCcs8SqCEP/ybxyacOnOD5Km8y7XbOJGYFgvepixo4BvigTvfrPydjtbeJMxoaRJnsvhgAtcwxErLwM3GARLMP4sEj/5xEheO1zvmD1BoacEBBxcE5uGXm0YSLE45NDeNvwVYPg9mJYmsVzHT7+NQngFFTHpPOoN5YaD+iI6PeU+h6r3ulq4+rDgjTc+3451Ce7g32ZXBRwOS3osAU9BBiW1bL97J4vXBhdBiL9iiEbE3BdbHlf03HPpIg==",

    "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 Payment 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: "7K2AyShlt1fOrKhCTC42EpqOnXxzSAiY+pLWGLo2AX4Q7uWjcv6SNQFUpgUpzrvRVXb4wQtTtdAelRk8YnqBGl/UlUR08cSWz4VALGT+YJB7FUEMfZ7m8Y3kLloe8Mv4Kg4D8uNNBmIUUZBPS782tQVoSNG+B0jLjqISTltY5UkqkidQnbPKxXO0XeFJApW00UZIJhuhUhaQgMT3/cmO5XzDtVjOa2FRszMi65zoeWyoFVXYxqJwiZ4PVv7FFRzoDbcbtXL1mJ/TeJ51UC2zdeJN9IW41aw6e2dE3xx++PLsLbzhtwJg/qra/+4/94kQw/gB3qWGbeb9icOC/A7TnFqOWkct7A9xYlm1mYbyBer1EYpNSZ/IB156ou+YS4S3aeqtDoXp+wRk0L9fYZher5cwy7GD2IPGMF9OLDd+5/ml7Lpik9dOmu9m8UljJLNM620o3j7R3clFB1Zztrd53i78/K/XOgj0Kd+rJt1CUkcAjFleTXDP63uFMcbFz36iHv6+/tPfisGGCX98jEGVWA=="

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": "hcsZg0q6sLm4gRQ97MBAlkNFAJCFXUAlnxlJCzjjwNwJJ9i8JIXoFjnzi6zRpyt6Vw7RGiUvUsLCq6PSUEIQ4B45ZaOCZCcs8SqCEP/ybxyacOnOD5Km8y7XbOJGYFgvepixo4BvigTvfrPydjtbeJMxoaRJnsvhgAtcwxErLwM3GARLMP4sEj/5xEheO1zvmD1BoacEBBxcE5uGXm0YSLE45NDeNvwVYPg9mJYmsVzHT7+NQngFFTHpPOoN5YaD+iI6PeU+h6r3ulq4+rDgjTc+3451Ce7g32ZXBRwOS3osAU9BBiW1bL97J4vXBhdBiL9iiEbE3BdbHlf03HPpIg==",

    "timestamp": 1706585572074,

    // Encrypted payment object
    "body": "7K2AyShlt1fOrKhCTC42EpqOnXxzSAiY+pLWGLo2AX4Q7uWjcv6SNQFUpgUpzrvRVXb4wQtTtdAelRk8YnqBGl/UlUR08cSWz4VALGT+YJB7FUEMfZ7m8Y3kLloe8Mv4Kg4D8uNNBmIUUZBPS782tQVoSNG+B0jLjqISTltY5UkqkidQnbPKxXO0XeFJApW00UZIJhuhUhaQgMT3/cmO5XzDtVjOa2FRszMi65zoeWyoFVXYxqJwiZ4PVv7FFRzoDbcbtXL1mJ/TeJ51UC2zdeJN9IW41aw6e2dE3xx++PLsLbzhtwJg/qra/+4/94kQw/gB3qWGbeb9icOC/A7TnFqOWkct7A9xYlm1mYbyBer1EYpNSZ/IB156ou+YS4S3aeqtDoXp+wRk0L9fYZher5cwy7GD2IPGMF9OLDd+5/ml7Lpik9dOmu9m8UljJLNM620o3j7R3clFB1Zztrd53i78/K/XOgj0Kd+rJt1CUkcAjFleTXDP63uFMcbFz36iHv6+/tPfisGGCX98jEGVWA=="
}

Send the request to the BIEASES payment gateway.

POST /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": "hcsZg0q6sLm4gRQ97MBAlkNFAJCFXUAlnxlJCzjjwNwJJ9i8JIXoFjnzi6zRpyt6Vw7RGiUvUsLCq6PSUEIQ4B45ZaOCZCcs8SqCEP/ybxyacOnOD5Km8y7XbOJGYFgvepixo4BvigTvfrPydjtbeJMxoaRJnsvhgAtcwxErLwM3GARLMP4sEj/5xEheO1zvmD1BoacEBBxcE5uGXm0YSLE45NDeNvwVYPg9mJYmsVzHT7+NQngFFTHpPOoN5YaD+iI6PeU+h6r3ulq4+rDgjTc+3451Ce7g32ZXBRwOS3osAU9BBiW1bL97J4vXBhdBiL9iiEbE3BdbHlf03HPpIg==",
    "timestamp": "1706585572074",
    "body": "7K2AyShlt1fOrKhCTC42EpqOnXxzSAiY+pLWGLo2AX4Q7uWjcv6SNQFUpgUpzrvRVXb4wQtTtdAelRk8YnqBGl/UlUR08cSWz4VALGT+YJB7FUEMfZ7m8Y3kLloe8Mv4Kg4D8uNNBmIUUZBPS782tQVoSNG+B0jLjqISTltY5UkqkidQnbPKxXO0XeFJApW00UZIJhuhUhaQgMT3/cmO5XzDtVjOa2FRszMi65zoeWyoFVXYxqJwiZ4PVv7FFRzoDbcbtXL1mJ/TeJ51UC2zdeJN9IW41aw6e2dE3xx++PLsLbzhtwJg/qra/+4/94kQw/gB3qWGbeb9icOC/A7TnFqOWkct7A9xYlm1mYbyBer1EYpNSZ/IB156ou+YS4S3aeqtDoXp+wRk0L9fYZher5cwy7GD2IPGMF9OLDd+5/ml7Lpik9dOmu9m8UljJLNM620o3j7R3clFB1Zztrd53i78/K/XOgj0Kd+rJt1CUkcAjFleTXDP63uFMcbFz36iHv6+/tPfisGGCX98jEGVWA=="
}

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

Request payload

Body object

Order object

Goods object

Shipping_ object

Response

Response payload

📘Note

Data object

Examples

📘
Note