Skip to main content

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 .

KeyTypeMandatory?LengthDescriptionExample
channelStringYes*The channel where the order was created. Supported value:
WEB
APP
paymentAmountNumberYes*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
currencyStringYes*The currency code. ISO 4217USD
paymentTimeTimestampYes*The timestamp for the payment order time.
paymentExpiryTimeTimestampYes*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.
callbackUrlStringNo2048The callback webhook address.https://merchant_server_name/payment/callback
redirectUrlStringNo2048The 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
orderObjectYesRefer to the order object

Order object

KeyTypeMandatory?LengthDescriptionExample
orderNoStringYes64The order number on the merchant's platform2013112111001004500000675971
orderAmountNumberYes*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
tipsNumberNoThe 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
discountNumberNoThe 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
totalTaxNumberNoThe 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.
insuranceNumberNoThe 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.
handlingFeeNumberNoThe 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.
shippingObjectNoThe order shipping info
shippingDiscountNumberNoThe order shipping fee discount, if it has one
orderDescriptionStringNo256The order descriptionxxx
goodsArrayYes*The goods object list (max 100 elements).

Goods object

KeyTypeMandatory?LengthDescriptionExample
referenceGoodsIdStringYes64The goods item ID.821e1c32-4a6c-442e-b5ce-8ec5b902d11c
goodsNameStringYes256The goods item name.Paper tower
goodsDescStringNo256The goods item description.White kitchen paper tower
goodsAmountNumberNo*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
taxNumberNoThe 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
goodsQuantityNumberNo*The quantity for each individual good.2

Shipping_ object

KeyTypeMandatory?DescriptionExample
shipTypeStringYesThe ship type where the order will be delivered. Supported values:
SHIPPING
PICKUP_IN_STORE
PICKUP_FROM_PERSON
amountNumberNoThe 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
nameStringYesThe receiver nameJohn Doe
addressStringNoThe 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

KeyTypeLengthDescriptionExample
paymentIdString32The payment order number regarding the payment request.1754349465357123584
referOrderNoString32The order number from the merchant's platform.2013112111001004500000675971
channelString*The channel where the order was created. Supported values:
WEB
APP
APP
checkoutUrlString2048The 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
statusStringThe payment order status."pending"

Examples

Follow the steps below to construct the payment request message.

  1. 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"
    }
    }
  2. 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"
    }
    }
  3. 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=="
  4. 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=="
    }


  5. 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=="
    }
  6. 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.