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	Mandatory	Default	Description
merchantId	String	M		Merchant identifier
currency	String	O	HKD	3-Letters ISO currency code, supports HKD, USD
amount	Number(9,2)	M		Order amount
merchantReference	String(64)	M		An unique reference to identify this order
callbackUrl	Object	O
callbackUrl.success	String	O		URL to redirect after successful payment
callbackUrl.fail	String	O		URL to redirect after failed payment
callbackUrl.cancel	String	O		URL to redirect when payment is cancelled
callbackUrl.notify	String	O		API URL in merchant's backend to receive notification
isRecurring	Boolean	O	false	Enable/disable recurring payment
expiryTime	Datetime	O	now + 1000s	Expiry time in ISO 8601 format.
lineItems	Array	M		List of line item objects (1..n items)
lineItems[index].quantity	Number(8)	M		Number of items, must be integer
lineItems[index].priceData	Object	M		Price data object
lineItems[index].priceData.unitAmount	Number(9,2)	M		Unit amount of the item
lineItems[index].priceData.name	String	M		Name of the item
lang	String	O	Web browser default	Default language: zh-HK or en
showLang	Boolean	O	true	Show/hide language options
showPoweredBy	Boolean	O	true	Show/hide Powered by BBMSL text at bottom
paymentMethods	String	O	All available payment methods	Supported payment methods, comma-separated: CARD, APPLEPAY, GOOGLEPAY, ALIPAYHK, ALIPAYCN, WECHATPAY
defaultPaymentMethod	String	O		Preselected payment method. Fallbacks to first if unavailable. See above for values.
allowedBinRanges	Array	O		Only allow card numbers within bin ranges (VISA & Mastercard)
allowedBinRanges[index].binStart	String(4-8)	M		Start of bin range, e.g., 4812, 540820, 3742
allowedBinRanges[index].binEnd	String(4-8)	M		End of bin range, must match binStart length, e.g., 4814, 540870, 3748
allowedCardType	String	O		Restrict to card type, applies to CARD, APPLEPAY, GOOGLEPAY: VISA, MASTER, UNIONPAY
showOrderDetail	Boolean	O	true	Show/hide order item list
showEmail	Boolean	O	true	Show/hide email input field
showMerchantReference	Boolean	O	true	Show/hide order's merchant reference (top right)
showOrderId	Boolean	O	true	Show/hide order ID
showResultPage	Boolean	O	true	Show/hide result page (requires callbackUrl if false)
themeColor	String	O		Order page background color, e.g., #1F2F3F
buttonBackgroundColor	String	O		Button background color, e.g., #1F2F3F
buttonFontColor	String	O		Button font color, e.g., #1F2F3F

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	Mandatory	Description
responseCode	String	M	Payment Gateway response code
message	String	M	Payment Gateway response message
checkoutUrl	String	M	URL to hosted checkout page
order	Object	M	Object contains order details
order.id	Number	M	Order identifier. If it is recurring payment, save this value as next recurring payment's parentOrderId
order.merchantId	Number	M	Merchant identifier which own this order
order.merchantReference	String	M	Your reference for the order
order.currency	String	M	3-Letters ISO currency code of the order
order.amount	Number	M	Amount of order
order.netAmount	Number	M	Net amount of the order
order.createTime	Datetime	M	Timestamp when the order is created. Maintained by the Payment Gateway
order.updateTime	Datetime	M	Timestamp when the order is last updated. Maintained by the Payment Gateway
order.status	String	M	Status of the order. Maintained by the Payment Gateway
order.recurring	Boolean	M	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
  }
}