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 Version | Version 2 | Changes | |
|---|---|---|---|
| EndPoint | /binancepay/openapi/order | /binancepay/openapi/v2/order | Value changed |
| Request Properties | merchantId | Removed | |
| subMerchantId | merchant.subMerchantId | Path Changed | |
| merchantTradeNo | merchantTradeNo | Unchanged | |
| tradeType | env.terminalType | Path and Name Changed, new enum values added | |
| totalFee | orderAmount | Name Changed | |
| currency | currency | Unchanged | |
| productType | goods.goodsType | Path and Name Changed, value restricted to enum values and required to be provide | |
| productName | goods.goodsName | Path and Name Changed, it's required to be provide | |
| productDetail | goods.goodsDetail | Path and Name Changed | |
| returnUrl | returnUrl | Unchanged | |
| cancelUrl | cancelUrl | Unchanged | |
| orderExpireTime | orderExpireTime | Unchanged | |
| supportPayCurrency | supportPayCurrency | Unchanged | |
| goods.goodsCategory | New required | ||
| goods.referenceGoodsId | New required | ||
| Response | Unchanged |
EndPoint#
Request Parameters#
| Attributes (1st Level) | Attributes (2nd Level) | Attributes (3rd Level) | Type | Required | Description |
|---|---|---|---|---|---|
| merchant | object | N | |||
| subMerchantId | string(19] | N | The sub merchant account id, issued when sub merchant been created at Binance, The parameter subMerchantId is required when configuring show subMerchant info. | ||
| 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) | Y | Amount Range: 0.01 - 20000 | ||
| currency | string | Y | order currency in upper case. only "BUSD","USDT","MBOX" can be accepted, fiat NOT supported. | ||
| goods | object | Y | |||
| 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 | ||
| goodsDetail | string(256] | N | |||
| goodsUnitAmount | object | N | Price of goods | ||
| currency | string | Y | |||
| amount | decimal | Y | |||
| goodsQuantity | string | N | Quantity of goods | ||
| 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 | The unique ID to identify the buyer | ||
| 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 | |||
| returnUrl | string(256] | N | The URL to redirect to when the payment is successful. | ||
| cancelUrl | string(256] | N | The URL to redirect to when payment is failed. | ||
| orderExpireTime | long | N | orderExpireTime 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. | ||
| 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. "BUSD,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. |
Sample Request Body#
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 contend 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 |
Sample Response#
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. |