Webhook Common Rules

For Security Purpose, Binance will add signature for webhook notification. Partner needs to verify the signature using the public key issued from Binance Pay.

Protocol Rules

The following specifies the rules for calling the Webhook Notification from Binance payment.

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

Request Header

Binance Pay Webhook notification will contain the following in the header, which is used to verify the notification authenticity.

Attributes	Type	Required	Limitation	Description
BinancePay-Certificate-SN	long	Y	-	MD5 hash value of public key
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-Timestamp	string	Y	-	UnixTimestamp in milliseconds
BinancePay-Signature	string	Y	-	signature, generated by Binance Pay

Verify the Signature

Build the payload

Java

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

PHP

$payload = $headers['Binancepay-Timestamp'] . "\n" . $headers['Binancepay-Nonce'] . "\n" . $entityBody . "\n";

Note:

• ‘\n’ is LF, ASCII value is '0x0A'

Decode the Signature with Base64

Java

byte[] decodedSignature = Base64.getDecoder().decode(signature);

PHP

$decodedSignature = base64_decode ( $headers['Binancepay-Signature'] );

Verify the content with public key

Public key to verify the content can be queried from Query Certificate API - "certPublic"

Note:

• Hash algorithm should use SHA256

Sample Java code is here, together with org.bouncycastle toolkit.

 // input: pubKeyStr, decodedSignature, payload
    PEMParser pubParser = new PEMParser(new StringReader(pubKeyStr))
    SubjectPublicKeyInfo pubKeyObj = (SubjectPublicKeyInfo) pubParser.readObject();
    AsymmetricKeyParameter pubKey = PublicKeyFactory.createKey(pubKeyObj);

    byte[] payloadBytes = payload.getBytes(StandardCharsets.UTF_8);
    RSADigestSigner verifier = new RSADigestSigner(new SHA256Digest());
    verifier.init(false, pubKey);
    verifier.update(payloadBytes, 0, payloadBytes.length);

    return verifier.verifySignature(decodedSignature);

PHP

openssl_verify($payload, $decodedSignature, $publicKey, OPENSSL_ALGO_SHA256 );