Create a tokenization session

Use this endpoint to begin the Tokenization workflow. The response provides a URL to the BBMSL-hosted card entry page where your customer saves their card details for future payments.

Endpoint summary

Path: /tokenization/add-token
Method: POST
Content-Type: application/json

Request parameters

Parameter	Type	Mandatory	Default	Description
merchantId	String	M		Merchant identifier
userId	String(56)	M		Merchant's user identifier, value is case sensitive
reason	String	O		Reason to create token
callbackUrl	Object	M
callbackUrl.success	String	M		An URL to redirect after successful tokenize
callbackUrl.fail	String	M		An URL to redirect after failed tokenize
callbackUrl.cancel	String	O		An URL to redirect when payment is cancelled, back button will not show if value is not given
callbackUrl.notify	String	M		An API URL in merchant's backend to receive notification
lang	String	O	Web browser default	Default language, value can be zh-HK or en
showLang	Boolean	O	true	Show/hide language options
showPoweredBy	Boolean	O	true	Show/hide Powered by BBMSL text at the bottom
allowedBinRanges	Array	O		Allow only the card matches the provided bin ranges
allowedBinRanges[index].binStart	String(4-8)	M		Start of bin range, e.g., 4812,540820.
allowedBinRanges[index].binEnd	String(4-8)	M		End of bin range, must be the same length as binStart. e.g., 4814,540870.
allowedCardType	String	O		Allow only the provided card type to proceed if given. Available card type: VISA, MASTER
themeColor	String	O		Order page background color, e.g., #1F2F3F
buttonBackgroundColor	String	O		Background color of all buttons, e.g., #1F2F3F
buttonFontColor	String	O		Font color of all buttons, e.g., #1F2F3F
issuingCountryCode	String	O	HK	Default issuing country or region option: HK, TW, CA, UK, US or OTHER

Request example

{
  "request": "{\"merchantId\":3,\"userId\":\"abc\",\"callbackUrl\":{\"success\":\"https://www.bbmsl.com/success\",\"fail\":\"https://www.bbmsl.com/fail\",\"cancel\":\"https://www.bbmsl.com/cancel\"}}",
  "signature": "zjo6xEhFokI9LpSleJiyUukmouGQP6xQ8NLEPily36vqyQ+Zrt4/4ZmBL0sBb6KdSDHiG6VKxZXLmlJaTqoLtuC+ZS1vbrrSblcilHgCCKASMDlFG1NdF8Xt+lGuhqhvn2Det/URoslou1YmLgAfEXKWrEfScdel+ieixMiIv0K1VKwswc4lvlljCmJhgYSeiJK51djnlecMNZyTMcHwofnGV0SMuB8sGWFcAFFF6N3ZbeY3unV4NYJATrCM8OYsd2K40V4FjXR3rWsIqWr9U0u8GoQq79+dY7+Mbf84IJC0YP+KP18cz1wMz75EVpIMghChzWEa3+iwSFFtf++mOw=="
}

Response parameters

Parameter	Type	Mandatory	Description
responseCode	String	M	Payment Gateway response code
message	String	M	Payment Gateway response message
data	String	M	URL to hosted tokenize page

note

• After receiving the data URL, redirect your customer to that URL to complete the tokenization of their credit card, Apple Pay, or Google Pay.

Response example

{
  "responseCode": "0000",
  "message": "SUCCESS",
  "data": "https://checkout.sit.bbmsl.com/token?sid=559a191620984bf5b5e9c32be0215150"
}