Skip to main content

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.

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 milliseconds 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 identity key issued by Binance payment system
BinancePay-SignaturestringYthis should use SHA512, and be in upper casesignature, 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

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 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 supportedUse POST http method
MEDIA_TYPE_NOT_SUPPORTED400007Media type not supportedAdd header Content-Type: application/json
INVALID_REQUEST_BODY400008Request body is not a valid json objectCheck the request body format
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.