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.

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#

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


Build the content#

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

Sign the content#

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


  • ‘\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 "


Common Business Errors#

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.