API Specification Common Rules

For Security Purpose, Binance and IPs will both ensure https-based call back endpoints. And signature checks for APIs.

Protocol Rules

The following specifies the rules for calling the API when accessing Binance payment.

Rule	Description
Transfer Mode	Use HTTPS for secure transactions.
Submit Mode	POST/GET, depends on the API.
Data Format (content-type)	Data submitted and response are both in application/json format.
Char Encoding	Use UTF-8 character encoding.
Signature Algorithm	HMAC-SHA512.
Signature Requirement	Signature-checking is required for requesting and receiving data.
Logic Judgment	Determine protocol field, service field and transaction status.

Request Header

Attributes	Type	Required	Limitation	Description
content-type	string	Y	application/json	content type
BinancePay-Timestamp	long	Y	Binance pay only process request within 1s	UnixTimestamp in milliseconds that the requests send, guarantee the machine time is sync with the network
BinancePay-Nonce	string	Y	must be 32 digits	A random string with 32 bytes, e.g. random ascii decimal within a-z and A-Z and loop 32 times to form a random string
BinancePay-Certificate-SN	string	Y	-	API identity key issued by Binance payment system
BinancePay-Signature	string	Y	this should use SHA512, and be in upper case	signature, signature generation

Signature

Build the content

String payload = timestamp + "\n" + nonce + "\n" + body + "\n";

Sign the content

String signature = hex(hmac("sha512", payload, secretKey)).toUpperCase()

---

NOTE

• ‘\n’ is LF, ASCII value is '0x0A'
• Parameter names are case-sensitive;
• When checking returned data or a push notification signature, the transferred sign parameter is excluded in this signature as it is compared with the created signature.
• When post the Json body, carefully check the quote, ' is not same as "

---

Hosts

https://bpay.binanceapi.com

Common Business Errors

Name	Code	Reason	Solution
UNKNOW_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	Use POST http method
MEDIA_TYPE_NOT_SUPPORTED	400007	Media type not supported	Add header Content-Type: application/json
INVALID_REQUEST_BODY	400008	Request body is not a valid json object	Check the request body format
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
ORDER_NOT_FOUND	400202	Order not found.
INVALID_ACCOUNT_STATUS	400203	Not support for this account, please check account status.