API 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 a merchant accesses Binance payment.

RuleDescription
Transfer ModeUse HTTPS for secure transactions.
Submit ModePOST/GET, depends on the API.
Data Format (content-type)Data submitted and response are both in application/json format.
Char EncodingUse UTF-8 character encoding.
Signature AlgorithmHMAC-SHA512.
Signature RequirementSignature-checking is required for requesting and receiving data.
Logic JudgmentDetermine protocol field, service field and transaction status.

Request Header#

AttributesTypeRequiredLimitationDescription
content-typestringYapplication/jsoncontent type
BinancePay-TimestamplongYBinance pay only process request within 1sUnixTimestamp in millis that the requests send, guarantee the machine time is sync with the network
BinancePay-NoncestringYmust be 32 digitsA 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-SNstringY-Api key issued by Binance payment system
BinancePay-SignaturestringY-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#

Prod: https://bpay.binanceapi.com

Common Business Errors#

NameCodeReasonSolution
UNKNOW_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 key not found or invalid.Check api key
BAD_API_KEY_FMT400005Api key format invalid.Check api key.
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
ORDER_NOT_FOUND400202Order not found.
INVALID_ACCOUNT_STATUS400203Not support for this account, please check account status.