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. xxx@gmail.com | ||
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) | Attributes (3rd 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
|
Create Order in Fiat
|
Sample Request Body For Channel Partner
Create Order in Crypto
|
Create Order in Fiat
|
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
|
Create Order in Fiat
|
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. |