Skip to main content

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

ParameterTypeRequired/optionalDefaultDescription
merchantIdstringRequiredMerchant identifier
currencystringOptionalHKD3-Letters ISO currency code, supports HKD, USD
amountnumberRequiredOrder amount
merchantReferencestringRequiredAn unique reference to identify this order
callbackUrlobjectOptional 
callbackUrl.successstringOptionalAn URL to redirect after successful payment
callbackUrl.failstringOptionalAn URL to redirect after failed payment
callbackUrl.cancelstringOptionalAn URL to redirect when payment is cancelled
callbackUrl.notifystringOptionalAn API URL in merchant's backend to receive notification
isRecurringbooleanOptionalfalseEnable/disable recurring payment
expiryTimedatetimeOptionalnow + 1000sTime that this order will be expired in ISO 8601 format.
lineItemsarrayRequiredLine item list. There can be 1..n object with line item details
lineItems[index].quantitynumberRequiredNumber of items, must be an integer
lineItems[index].priceDataobjectRequiredPrice data object with details
lineItems[index].priceData.unitAmountnumberRequiredUnit amount of the item
lineItems[index].priceData.namestringRequiredName of the item
langstringOptionalWeb browser defaultDefault language, value can be zh-HK or en
showLangbooleanOptionaltrueShow/hide language options
showPoweredBybooleanOptionaltrueShow/hide Powered by BBMSL text at the bottom
paymentMethodsstringOptionalAll available payment methodsSupported payment methods by order, separated with comma. Available methods: CARD, APPLEPAY, GOOGLEPAY, ALIPAYHK, ALIPAYCN, WECHATPAY
defaultPaymentMethodstringOptionalPreselected payment method, fallback to first method if it is not available. Available methods: CARD, APPLEPAY, GOOGLEPAY, ALIPAYHK, ALIPAYCN, WECHATPAY
allowedBinRangesarrayOptionalAllow only the card matches the provided bin ranges, support VISA and Mastercard only.
allowedBinRanges[index].binStartstringRequiredStart of bin range, e.g., 4812,540820.
allowedBinRanges[index].binEndstringRequiredEnd of bin range, must be the same length as binStart. e.g., 4814,540870.
allowedCardTypestringOptionalAllow 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
showOrderDetailbooleanOptionaltrueShow/hide order item list
showEmailbooleanOptionaltrueShow/hide email input field
showMerchantReferencebooleanOptionaltrueShow/hide order's merchant reference on the top right corner
showOrderIdbooleanOptionaltrueShow/hide order ID
showResultPagebooleanOptionaltrueShow/hide result page, callbackUrl must be given if set to false
themeColorstringOptionalOrder page background color
buttonBackgroundColorstringOptionalBackground color of all buttons
buttonFontColorstringOptionalFont 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

ParameterTypeRequired/optionalDescription
responseCodestringRequiredPayment Gateway response code
messagestringRequiredPayment Gateway response message
checkoutUrlstringRequiredURL to hosted checkout page
orderobjectRequiredObject contains order details
order.idnumberRequiredOrder identifier. If it is recurring payment, save this value as next recurring payment's parentOrderId
order.merchantIdnumberRequiredMerchant identifier which own this order
order.merchantReferencestringRequiredYour reference for the order
order.currencystringRequired3-Letters ISO currency code of the order
order.amountnumberRequiredAmount of order
order.netAmountnumberRequiredNet amount of the order
order.createTimedatetimeRequiredTimestamp when the order is created. Maintained by the Payment Gateway
order.updateTimedatetimeRequiredTimestamp when the order is last updated. Maintained by the Payment Gateway
order.statusstringRequiredStatus of the order. Maintained by the Payment Gateway
order.recurringbooleanRequiredFlags 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
  }
}