Skip to main content

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)
TypeRequiredDescription
merchantobjectN
subMerchantIdstring(19]NSub-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.
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)NWhen currency is not null. Minimum amount: 0.00000001
currencystringNCurrency 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.
fiatAmountdecimal(.8)NMinimum amount: 0.00000001 ,We will convert this fiat amount to order amount based on market currency rate.
fiatCurrencystringNCurrency 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
goodsDetailsList[Goods]YList of Goods. refer to
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
referenceBuyerIdstringNRestrict specific Binance ID to make payment. Only whitelisted merchant can use this restriction feature
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
buyerBrowserLanguagestringNThe language of the merchant's platform shows the buyer
returnUrlstring(256]NThe 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 (✖)
cancelUrlstring(256]NThe 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 (✖)
orderExpireTimelongNorderExpireTime 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.
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. "USDT,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.
directDebitContractobjectNIf 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.
merchantContractCodestring(32]YThe unique ID assigned by the merchant to identify a direct debit contract request. letter or digit, no other symbol allowed.
serviceNamestring(32]YService name
scenarioCodestringYScenario code, please refer to
singleUpperLimitdecimal(.8)YUpper limit related to scenarioCode, for more please refer to
periodicbooleanYThis contract support periodic debit or not
cycleDebitFixedbooleanNMandatory if periodic = true. true = fixed amount, false = variable amount
cycleTypestringNMandatory if periodic = true. Values: MONTH or DAY
cycleValueintegerNMandatory 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.
firstDeductTimelongNMandatory 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)
merchantAccountNostring(64]NThe userID/user account in merchant side e.g. xxx@gmail.com
contractEndTimelongNIf not specified, contractEndTime will be the time after 1095 days (about 3 years). maximum is 1095 days in milliseconds.
orderTagsobjectNObject to tag order for specific features such as profit sharing.
ifProfitSharingbooleanNif specified and true, order will be tagged as profit sharing.
descriptionstring(256]YGoods description will be displayed as both Product Name and Product Details in the checkout page
voucherCodestringN

Goods

Attributes
(1st Level)
Attributes
(2nd Level)
Attributes
(3rd Level)
TypeRequiredDescription
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.
Special character is prohibited Example: \ " or emoji
goodsDetailstring(256]N
goodsUnitAmountobjectNPrice of goods
currencystringY
amountdecimalY

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

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 content 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
currencystringYorder currency
totalFeedecimal(.8)Yorder total amount
fiatCurrencystringNorder fiat currency ,only return when create in fiat
fiatAmountdecimal(.8)Norder 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

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.