Create Order

Create order API Version 3 used for merchant/partner to initiate acquiring order.

Note: Create Order V2 is currently still available but will be deprecated in the future. Do migrate over to the latest version.

EndPoint

POST /binancepay/openapi/v3/order

Request Parameters

Attributes (1st Level)	Attributes (2nd Level)	Attributes (3rd Level)	Type	Required	Description
merchant			object	N
	subMerchantId		string(19]	N	Sub-merchant id (issued when sub-merchant is created at binance). Required for Channel Partner. Note: If you’re a Channel Partner and you’re placing order for your own business, you need to create a separate sub-merchant id accordingly.
env			object	Y
	terminalType		string	Y	Terminal type of which the merchant service applies to. Valid values are: APP: The client-side terminal type is a mobile application. WEB: The client-side terminal type is a website that is opened via a PC browser. WAP: The client-side terminal type is an HTML page that is opened via a mobile browser. MINI_PROGRAM: The terminal type of the merchant side is a mini program on the mobile phone. OTHERS: other undefined type
	osType		string	N	OS type. Valid values are: IOS: indicates the operation system is Apple's iOS. ANDROID: indicates the operation system is Google's Android.
	orderClientIp		string	N	IP of the client device when submit the order
	cookieId		string	N	The cookie ID of the buyer
merchantTradeNo			string(32]	Y	The order id, Unique identifier for the request letter or digit, no other symbol allowed, maximum length 32
orderAmount			decimal(.8)	N	When currency is not null. Minimum amount: 0.00000001
currency			string	N	Currency and fiatCurrency cannot be both null. must be in UPPERCASE. Only cryptocurrency is accepted e.g. "USDT", “BNB”, “BTC”, fiat NOT supported. You may refer to My Profile for the full list of supported currencies. From 17 June onwards, MICA user may use "EUR" or any other available cryptocurrency.
fiatAmount			decimal(.8)	N	Minimum amount: 0.00000001 ,We will convert this fiat amount to order amount based on market currency rate.
fiatCurrency			string	N	Currency and fiatCurrency cannot be both null. fiat currency in upper case. ex: "HKD". Order currency will be set to "USDT" if this filed has value. Click here to view supported fiat currencies
goodsDetails			List[Goods]	Y	List of Goods. refer to
shipping			object	N
	shippingName		object	N	The recipient name
		firstName	string	Y
		middleName	string	N
		lastName	string	Y
	shippingAddress		object	N	Shipping address
		region	string	Y	The 2-letter country/region code. For more information, see ISO 3166 Country Codes standard.
		state	string	N	The state, country, or province name.
		city	string	N	The city, district, suburb, town, or village name.
		address	string	N	Address, for example, the stress address/PO box/company name
		zipCode	string	N	ZIP or postal code
		shippingAddressType	string	N	shipping to 01: office 02: home 03: public box 04: others
	shippingPhoneNo		string	N	The phone number of a recipient (including extension)
buyer			object	N
	referenceBuyerId		string	N	Restrict specific Binance ID to make payment. Only whitelisted merchant can use this restriction feature
	buyerName		object	N	Name of buyer full name from merchants
		firstName	string	Y
		middleName	string	N
		lastName	string	Y
	buyerPhoneCountryCode		string	N
	buyerPhoneNo		string	N	Mobile phone number of the buyer from merchants
	buyerEmail		string	N	Email of the buyer from merchants
	buyerRegistrationTime		long	N	Buyer registration time on merchant side, epoch time milliseconds
	buyerBrowserLanguage		string	N	The language of the merchant's platform shows the buyer
returnUrl			string(256]	N	The URL to redirect to when the payment is successful. Url must begin with HTTP. Only one parameter is allowed per URL, for e.g. https://example.com/search?q=apples (✓) https://example.com/search?q=apples&p=orange (✖)
cancelUrl			string(256]	N	The URL to redirect to when payment is failed. Url must begin with HTTP. Only one parameter is allowed per URL, for e.g. https://example.com/search?q=apples (✓) https://example.com/search?q=apples&p=orange (✖)
orderExpireTime			long	N	orderExpireTime determines how long an order is valid for. If not specified, orderExpireTime will be 1 hour; maximum orderExpireTime is 15 days. Please input in milliseconds.
supportPayCurrency			string(1024]	N	SupportPayCurrency determines the currencies that a customer is allowed to use to pay for the order. If not specified, all Binance Pay supported currencies will be allowed. Input to be separated by commas, e.g. "USDT,BNB"
appId			string	N	The unique ID that is assigned by Binance to identify the mini program app. Note: This field is required when terminalType is MINI_PROGRAM.
universalUrlAttach			string(120)	N	the attachment parameter for the response field "universalUrl", e.g. "countryCode=1&phone=1234567"
passThroughInfo			string(512]	N	pass through info, returned as-is in query order API and payment webhook notification
webhookUrl			string(256]	N	The URL for order notification, can only start with http or https. If the webhookUrl is passed in the parameter, the webhook url configured on the merchant platform will not take effect, and the currently passed url will be called back first.
directDebitContract			object	N	If not empty, it means to create an order and direct debit contract. Use this function order currency can only accept "USDT". W.e.f 17 June, MICA user can create in "EUR" Only available to whitelisted merchant.
	merchantContractCode		string(32]	Y	The unique ID assigned by the merchant to identify a direct debit contract request. letter or digit, no other symbol allowed.
	serviceName		string(32]	Y	Service name
	scenarioCode		string	Y	Scenario code, please refer to
	singleUpperLimit		decimal(.8)	Y	Upper limit related to scenarioCode, for more please refer to
	periodic		boolean	Y	This contract support periodic debit or not
	cycleDebitFixed		boolean	N	Mandatory if periodic = true. true = fixed amount, false = variable amount
	cycleType		string	N	Mandatory if periodic = true. Values: MONTH or DAY
	cycleValue		integer	N	Mandatory if periodic = true. Values: if cycleType=MONTH: 1~24, cycleType=DAY: interval days >7 Combining with another parameter cycleType to determine the deduction period, for example, cycleType is DAY, cycleValue=30, then the deduction period is 30 days; cycleType is MONTH, cycleValue=3, then the deduction period is 3 natural months.
	firstDeductTime		long	N	Mandatory if periodic = true. first deduct time, must be a future time in milli seconds. if cycleType=MONTH, the firstDeductTime is not allowed to pass the date after the 28th UTC (can pass the 28th)
	merchantAccountNo		string(64]	N	The userID/user account in merchant side e.g. [email protected]
	contractEndTime		long	N	If not specified, contractEndTime will be the time after 1095 days (about 3 years). maximum is 1095 days in milliseconds.
orderTags			object	N	Object to tag order for specific features such as profit sharing.
	ifProfitSharing		boolean	N	if specified and true, order will be tagged as profit sharing.
description			string(256]	Y	Goods description will be displayed as both Product Name and Product Details in the checkout page
voucherCode			string	N

Goods

Attributes (1st Level)	Attributes (2nd Level)	Type	Required	Description
goodsType		string	Y	the type of the goods for the order: 01: Tangible Goods 02: Virtual Goods
goodsCategory		string	Y	0000: Electronics & Computers 1000: Books, Music & Movies 2000: Home, Garden & Tools 3000: Clothes, Shoes & Bags 4000: Toys, Kids & Baby 5000: Automotive & Accessories 6000: Game & Recharge 7000: Entertainament & Collection 8000: Jewelry 9000: Domestic service A000: Beauty care B000: Pharmacy C000: Sports & Outdoors D000: Food, Grocery & Health products E000: Pet supplies F000: Industry & Science Z000: Others
referenceGoodsId		string	Y	The unique ID to identify the goods.
goodsName		string(256]	Y	Goods name. Special character is prohibited Example: \ " or emoji
goodsDetail		string(256]	N
goodsUnitAmount		object	N	Price of goods
	currency	string	Y
	amount	decimal	Y

Sample Request Body For Direct Merchant

Create Order in Crypto

{
  "env": {
    "terminalType": "APP"
  },
  "merchantTradeNo": "9825382937292",
  "orderAmount": 25.17,
  "currency": "USDT",
  "description": "very good Ice Cream",
  "goodsDetails": [
    {
      "goodsType": "01",
      "goodsCategory": "D000",
      "referenceGoodsId": "7876763A3B",
      "goodsName": "Ice Cream",
      "goodsDetail": "Greentea ice cream cone"
    }
  ]
}

Create Order in Fiat

{
  "env": {
    "terminalType": "APP"
  },
  "merchantTradeNo": "9825382937292",
  "fiatAmount": 100,
  "fiatCurrency": "HKD",
  "description": "very good Ice Cream",
  "goodsDetails": [
    {
      "goodsType": "01",
      "goodsCategory": "D000",
      "referenceGoodsId": "7876763A3B",
      "goodsName": "Ice Cream",
      "goodsDetail": "Greentea ice cream cone"
    }
  ]
}

Sample Request Body For Channel Partner

Create Order in Crypto

{
  "env": {
    "terminalType": "APP"
  },
  "merchant": {
    "subMerchantId": "100100006288"
  },
  "merchantTradeNo": "9825382937292",
  "orderAmount": 25.17,
  "currency": "USDT",
  "description": "very good Ice Cream",
  "goodsDetails": [
    {
      "goodsType": "01",
      "goodsCategory": "D000",
      "referenceGoodsId": "7876763A3B",
      "goodsName": "Ice Cream",
      "goodsDetail": "Greentea ice cream cone"
    }
  ]
}

Create Order in Fiat

{
  "env": {
    "terminalType": "APP"
  },
  "merchant": {
    "subMerchantId": "100100006288"
  },
  "merchantTradeNo": "9825382937292",
  "fiatAmount": 100,
  "fiatCurrency": "HKD",
  "description": "very good Ice Cream",
  "goodsDetails": [
    {
      "goodsType": "01",
      "goodsCategory": "D000",
      "referenceGoodsId": "7876763A3B",
      "goodsName": "Ice Cream",
      "goodsDetail": "Greentea ice cream cone"
    }
  ]
}

Response Parameters

Attributes	Type	Required	Limitation	Description
status	string	Y	"SUCCESS" or "FAIL"	status of the API request
code	string	Y	-	request result code, refer to
data	OrderResult	N	-	response body, refer to
errorMessage	string(256]	N	-

Child Attribute

OrderResult

Attributes	Type	Required	Limitation	Description
prepayId	string(19]	Y	-	unique id generated by binance
terminalType	string(20]	Y		same as terminalType in request data
expireTime	long	Y	-	expire time in milli seconds
qrcodeLink	string(256]	Y	-	qr code img link
qrContent	string(256]	Y	-	qr content info
checkoutUrl	string(256]	Y	-	binance hosted checkout page url
deeplink	string(256]	Y	-	deeplink to open binance app to finish payment
universalUrl	string	Y	maximum length 512	universal url to finish the payment
currency	string	Y		order currency
totalFee	decimal(.8)	Y		order total amount
fiatCurrency	string	N		order fiat currency ,only return when create in fiat
fiatAmount	decimal(.8)	N		order fiat amount ,only return when create in fiat

Sample Response

Create Order in Crypto

{
  "status": "SUCCESS",
  "code": "000000",
  "data": {
    "prepayId": "29383937493038367292",
    "terminalType": "APP",
    "expireTime": 121123232223,
    "qrcodeLink": "https://qrservice.dev.com/en/qr/dplkb005181944f84b84aba2430e1177012b.jpg",
    "qrContent": "https://qrservice.dev.com/en/qr/dplk12121112b",
    "checkoutUrl": "https://pay.binance.com/checkout/dplk12121112b",
    "deeplink": "bnc://app.binance.com/payment/secpay/xxxxxx",
    "universalUrl": "https://app.binance.com/payment/secpay?_dp=xxx=&linkToken=xxx",
    "totalFee": "25.17",
    "currency": "USDT"
  },
  "errorMessage": ""
}

Create Order in Fiat

{
  "status": "SUCCESS",
  "code": "000000",
  "data": {
    "currency": "USDT",
    "totalFee": "12.77377391",
    "fiatCurrency": "HKD",
    "fiatAmount": "100",
    "prepayId": "230898625140047872",
    "terminalType": "WEB",
    "expireTime": 1685360951988,
    "qrcodeLink": "https://public.bnbstatic.com/static/payment/20230529/26b9d4ed-0a1d-47ab-802f-d23beecad1ff.jpg",
    "qrContent": "https://app.binance.com/qr/dplk677510ff75084d428657718ca71c23e6",
    "checkoutUrl": "https://pay.binance.com/en/checkout/362d8131e3c349a08c77455001f2f32b",
    "deeplink": "bnc://app.binance.com/payment/secpay?tempToken=1NgAZN9X3VRJWbQkh4viNWWpGYReMuNs",
    "universalUrl": "https://app.binance.com/payment/secpay?_dp=xxx=&linkToken=xxx"
  }
}

Result Code

Name	Code	Reason	Solution
UNKNOWN_ERROR	400000	An unknown error occurred while processing the request.	Try again later
INVALID_REQUEST	400001	Parameter format is wrong or parameter transferring doesn't follow the rules.	Please check whether the parameters are correct.
INVALID_SIGNATURE	400002	Incorrect signature result	Check whether the signature parameter and method comply with signature algorithm requirements.
INVALID_TIMESTAMP	400003	Timestamp for this request is outside of the time window.	Sync server clock
INVALID_API_KEY_OR_IP	400004	API identity key not found or invalid.	Check API identity key
BAD_API_KEY_FMT	400005	API identity key format invalid.	Check API identity key.
BAD_HTTP_METHOD	400006	Request method not supported.	Check Request method.
MEDIA_TYPE_NOT_SUPPORTED	400007	Media type not supported.	Check Request Media type.
INVALID_REQUEST_BODY	400008	Request body is not a valid json object.	Check Request body
MANDATORY_PARAM_EMPTY_OR_MALFORMED	400100	A parameter was missing/empty/null, or malformed.
INVALID_PARAM_WRONG_LENGTH	400101	A parameter was not valid, was empty/null, or too long/short, or wrong format.
INVALID_PARAM_WRONG_VALUE	400102	A parameter was not valid, the value is out of range.
INVALID_PARAM_ILLEGAL_CHAR	400103	A parameter was not valid, contains illegal characters
INVALID_REQUEST_TOO_LARGE	400104	Invalid request, content length too large
INVALID_MERCHANT_TRADE_NO	400201	merchantTradeNo is invalid or duplicated
INVALID_ACCOUNT_STATUS	400203	Not support for this account, please check account status.
SUB_MERCHANT_INVALID	400206	The sub merchant does not exist or is in an unavailable state.

EndPoint​

Request Parameters​

Goods​

Sample Request Body For Direct Merchant​

Sample Request Body For Channel Partner​

Response Parameters​

Child Attribute​

OrderResult​

Sample Response​

Result Code​

EndPoint

Request Parameters

Goods

Sample Request Body For Direct Merchant

Sample Request Body For Channel Partner

Response Parameters

Child Attribute

OrderResult

Sample Response

Result Code