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.