Skip to main content

Create Order V2

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

Migration#

Comparing to old version of create order API(Create Order), changes summarized as below:

Old VersionVersion 2Changes
EndPoint/binancepay/openapi/order/binancepay/openapi/v2/orderValue changed
Request PropertiesmerchantIdRemoved
subMerchantIdmerchant.subMerchantIdPath Changed
merchantTradeNomerchantTradeNoUnchanged
tradeTypeenv.terminalTypePath and Name Changed, new enum values added
totalFeeorderAmountName Changed
currencycurrencyUnchanged
productTypegoods.goodsTypePath and Name Changed, value restricted to enum values and required to be provide
productNamegoods.goodsNamePath and Name Changed, it's required to be provide
productDetailgoods.goodsDetailPath and Name Changed
returnUrlreturnUrlUnchanged
cancelUrlcancelUrlUnchanged
orderExpireTimeorderExpireTimeUnchanged
supportPayCurrencysupportPayCurrencyUnchanged
goods.goodsCategoryNew required
goods.referenceGoodsIdNew required
ResponseUnchanged

EndPoint#

POST /binancepay/openapi/v2/order

Request Parameters#

Attributes
(1st Level)
Attributes
(2nd Level)
Attributes
(3rd Level)
TypeRequiredDescription
merchantobjectN
subMerchantIdstring(19]NThe sub merchant account id, issued when sub merchant been created at Binance, The parameter subMerchantId is required when configuring show subMerchant info.
envobjectY
terminalTypestringYTerminal 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
osTypestringNOS type. Valid values are:
IOS: indicates the operation system is Apple's iOS.
ANDROID: indicates the operation system is Google's Android.
orderClientIpstringNIP of the client device when submit the order
cookieIdstringNThe cookie ID of the buyer
merchantTradeNostring(32]YThe order id, Unique identifier for the request letter or digit, no other symbol allowed, maximum length 32
orderAmountdecimal(.8)YAmount Range: 0.01 - 20000
currencystringYorder currency in upper case. only "BUSD","USDT","MBOX" can be accepted, fiat NOT supported.
goodsobjectY
goodsTypestringYthe type of the goods for the order:
01: Tangible Goods
02: Virtual Goods
goodsCategorystringY0000: 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
referenceGoodsIdstringYThe unique ID to identify the goods.
goodsNamestring(256]YGoods name
goodsDetailstring(256]N
goodsUnitAmountobjectNPrice of goods
currencystringY
amountdecimalY
goodsQuantitystringNQuantity of goods
shippingobjectN
shippingNameobjectNThe recipient name
firstNamestringY
middleNamestringN
lastNamestringY
shippingAddressobjectNShipping address
regionstringYThe 2-letter country/region code. For more information, see ISO 3166 Country Codes standard.
statestringNThe state, country, or province name.
citystringNThe city, district, suburb, town, or village name.
addressstringNAddress, for example, the stress address/PO box/company name
zipCodestringNZIP or postal code
shippingAddressTypestringNshipping to
01: office
02: home
03: public box
04: others
shippingPhoneNostringNThe phone number of a recipient (including extension)
buyerobjectN
referenceBuyerIdstringNThe unique ID to identify the buyer
buyerNameobjectNName of buyer full name from merchants
firstNamestringY
middleNamestringN
lastNamestringY
buyerPhoneCountryCodestringN
buyerPhoneNostringNMobile phone number of the buyer from merchants
buyerEmailstringNEmail of the buyer from merchants
buyerRegistrationTimelongNBuyer registration time on merchant side, epoch time milliseconds
buyerBrowserLanguagestringN
returnUrlstring(256]NThe URL to redirect to when the payment is successful.
cancelUrlstring(256]NThe URL to redirect to when payment is failed.
orderExpireTimelongNorderExpireTime determines how long an order is valid for. If not specified, orderExpireTime will be 1 hour;
maximum orderExpireTime is 1 hour. Please input in milliseconds.
supportPayCurrencystring(1024]NSupportPayCurrency 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. "BUSD,BNB"
appIdstringNThe unique ID that is assigned by Binance to identify the mini program app. Note: This field is required when terminalType is MINI_PROGRAM.
universalUrlAttachstring(120)Nthe attachment parameter for the response field "universalUrl", e.g. "countryCode=1&phone=1234567"
passThroughInfostring(512]Npass through info, returned as-is in query order API and payment webhook notification
webhookUrlstring(256]NThe 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.

Sample Request Body#

{  "env" : {    "terminalType": "APP"  },  "merchantTradeNo": "9825382937292",  "orderAmount": 25.17,  "currency": "BUSD",  "goods" : {    "goodsType": "01",    "goodsCategory": "D000",    "referenceGoodsId": "7876763A3B",    "goodsName": "Ice Cream",    "goodsDetail": "Greentea ice cream cone"  }}

Response Parameters#

AttributesTypeRequiredLimitationDescription
statusstringY"SUCCESS" or "FAIL"status of the API request
codestringY-request result code, refer to
dataOrderResultN-response body, refer to
errorMessagestring(256]N-

Child Attribute#

OrderResult#

AttributesTypeRequiredLimitationDescription
prepayIdstring(19]Y-unique id generated by binance
terminalTypestring(20]Ysame as terminalType in request data
expireTimelongY-expire time in milli seconds
qrcodeLinkstring(256]Y-qr code img link
qrContentstring(256]Y-qr contend info
checkoutUrlstring(256]Y-binance hosted checkout page url
deeplinkstring(256]Y-deeplink to open binance app to finish payment
universalUrlstringYmaximum length 512universal url to finish the payment

Sample Response#

{  "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"  },  "errorMessage": ""}

Result Code#

NameCodeReasonSolution
UNKNOWN_ERROR400000An unknown error occurred while processing the request.Try again later
INVALID_REQUEST400001Parameter format is wrong or parameter transferring doesn't follow the rules.Please check whether the parameters are correct.
INVALID_SIGNATURE400002Incorrect signature resultCheck whether the signature parameter and method comply with signature algorithm requirements.
INVALID_TIMESTAMP400003Timestamp for this request is outside of the time window.Sync server clock
INVALID_API_KEY_OR_IP400004API identity key not found or invalid.Check API identity key
BAD_API_KEY_FMT400005API identity key format invalid.Check API identity key.
BAD_HTTP_METHOD400006Request method not supported.Check Request method.
MEDIA_TYPE_NOT_SUPPORTED400007Media type not supported.Check Request Media type.
INVALID_REQUEST_BODY400008Request body is not a valid json object.Check Request body
MANDATORY_PARAM_EMPTY_OR_MALFORMED400100A parameter was missing/empty/null, or malformed.
INVALID_PARAM_WRONG_LENGTH400101A parameter was not valid, was empty/null, or too long/short, or wrong format.
INVALID_PARAM_WRONG_VALUE400102A parameter was not valid, the value is out of range.
INVALID_PARAM_ILLEGAL_CHAR400103A parameter was not valid, contains illegal characters
INVALID_REQUEST_TOO_LARGE400104Invalid request, content length too large
INVALID_MERCHANT_TRADE_NO400201merchantTradeNo is invalid or duplicated
INVALID_ACCOUNT_STATUS400203Not support for this account, please check account status.
SUB_MERCHANT_INVALID400206The sub merchant does not exist or is in an unavailable state.