Create

---

• Description： Create an order and obtain URL to the hosted checkout page
• Path： /hosted-checkout/create
• Method： POST
• Request Header： Content-Type: application/json

Request Parameters

Parameter	Type	Required/optional	Default	Description
merchantId	string	Required		Merchant identifier
currency	string	Optional	HKD	3-Letters ISO currency code, supports HKD, USD
amount	number	Required		Order amount
merchantReference	string	Required		An unique reference to identify this order
callbackUrl	object	Optional
callbackUrl.success	string	Optional		An URL to redirect after successful payment
callbackUrl.fail	string	Optional		An URL to redirect after failed payment
callbackUrl.cancel	string	Optional		An URL to redirect when payment is cancelled
callbackUrl.notify	string	Optional		An API URL in merchant's backend to receive notification
isRecurring	boolean	Optional	false	Enable/disable recurring payment
expiryTime	datetime	Optional	now + 1000s	Time that this order will be expired in ISO 8601 format.
lineItems	array	Required		Line item list. There can be 1..n object with line item details
lineItems[index].quantity	number	Required		Number of items, must be an integer
lineItems[index].priceData	object	Required		Price data object with details
lineItems[index].priceData.unitAmount	number	Required		Unit amount of the item
lineItems[index].priceData.name	string	Required		Name of the item
lang	string	Optional	Web browser default	Default language, value can be zh-HK or en
showLang	boolean	Optional	true	Show/hide language options
showPoweredBy	boolean	Optional	true	Show/hide Powered by BBMSL text at the bottom
paymentMethods	string	Optional	All available payment methods	Supported payment methods by order, separated with comma. Available methods: CARD, APPLEPAY, GOOGLEPAY, ALIPAYHK, ALIPAYCN, WECHATPAY
defaultPaymentMethod	string	Optional		Preselected payment method, fallback to first method if it is not available. Available methods: CARD, APPLEPAY, GOOGLEPAY, ALIPAYHK, ALIPAYCN, WECHATPAY
allowedBinRanges	array	Optional		Allow only the card matches the provided bin ranges, support VISA and Mastercard only.
allowedBinRanges[index].binStart	string	Required		Start of bin range, e.g., 4812,540820.
allowedBinRanges[index].binEnd	string	Required		End of bin range, must be the same length as binStart. e.g., 4814,540870.
allowedCardType	string	Optional		Allow only the provided card type to proceed if given, applying only when CARD, APPLEPAY, or GOOGLEPAY is included in paymentMethods. Available card type: VISA, MASTER, UNIONPAY
showOrderDetail	boolean	Optional	true	Show/hide order item list
showEmail	boolean	Optional	true	Show/hide email input field
showMerchantReference	boolean	Optional	true	Show/hide order's merchant reference on the top right corner
showOrderId	boolean	Optional	true	Show/hide order ID
showResultPage	boolean	Optional	true	Show/hide result page, callbackUrl must be given if set to false
themeColor	string	Optional		Order page background color
buttonBackgroundColor	string	Optional		Background color of all buttons
buttonFontColor	string	Optional		Font color of all buttons

Example

{
  "request": "{\"currency\":\"HKD\",\"amount\":270,\"callbackUrl\":{\"success\":\"google.com\"},\"lineItems\":[{\"priceData\":{\"name\":\"Books\",\"unitAmount\":50},\"quantity\":5},{\"priceData\":{\"name\":\"Shipping Cost\",\"unitAmount\":20},\"quantity\":1}],\"allowedBinRanges\":[{\"binStart\":\"4812\",\"binEnd\":\"4816\"},{\"binStart\":\"540820\",\"binEnd\":\"540870\"}],\"merchantId\":\"3\",\"merchantReference\":\"merRef1709258105036\",\"isRecurring\":false,\"buttonBackgroundColor\":\"#3DAD02\",\"buttonFontColor\":\"#FFFFFF\",\"showPoweredBy\":false}",
  "signature": "lKjsmv+dpl9nPap5pTkNROzUdQYWOhkWJrjp+jyimGb74NL61DAvLq+5kUI8HEhKxGBzdyoGm1jp2Dq0aD3gIii3FHvpopTtWtIMawy2a4rsE8HA/zKUmEsw3YtEaYeT+5ULfDq4E6my0UvOA5VsgbfYYif0MvBPKsXOw6O0TMa4X3JoS8ZmEcsJ5RqNJB5DNh68GUclgaHotH4kcuaSzH0Hw1ZoXX/20j3lXsFgJNkHSsNsVMKfrFgzTUq/mcNkcnhcj5BKxhtU5APYAAzk0gWQZq14nnFog6IQSXInZU7f+cvm3N/AvxjwmvYkZVPLdMLDaRQaStHOVN4P+pWbtA=="
}

Response Parameters

Parameter	Type	Required/optional	Description
responseCode	string	Required	Payment Gateway response code
message	string	Required	Payment Gateway response message
checkoutUrl	string	Required	URL to hosted checkout page
order	object	Required	Object contains order details
order.id	number	Required	Order identifier. If it is recurring payment, save this value as next recurring payment's parentOrderId
order.merchantId	number	Required	Merchant identifier which own this order
order.merchantReference	string	Required	Your reference for the order
order.currency	string	Required	3-Letters ISO currency code of the order
order.amount	number	Required	Amount of order
order.netAmount	number	Required	Net amount of the order
order.createTime	datetime	Required	Timestamp when the order is created. Maintained by the Payment Gateway
order.updateTime	datetime	Required	Timestamp when the order is last updated. Maintained by the Payment Gateway
order.status	string	Required	Status of the order. Maintained by the Payment Gateway
order.recurring	boolean	Required	Flags the order is a recurring order or not

Example

{
  "responseCode": "0000",
  "message": "SUCCESS",
  "checkoutUrl": "https://checkout.sit.bbmsl.com/order?sid=77ce7651ac7d4703a94c74d4598fbf14",
  "order": {
    "id": 4920,
    "merchantId": 9000067,
    "merchantReference": "merRef1698373981165",
    "currency": "HKD",
    "amount": 550,
    "netAmount": 0,
    "createTime": "2023-10-27T02:33:02.307+00:00",
    "updateTime": "2023-10-27T02:33:02.493+00:00",
    "status": "OPEN",
    "recurring": false
  }
}