Skip to main content

Webhooks

Binance uses webhooks to notify you when something happens. We will automatically send you a notification immediately to keep you up-to-date on your order status.

You will be able to configure webhook endpoints via the Merchant Management Platform.

Setting up Webhooks#

For security purposes, Binance will add a signature for webhook notification. Merchants need to verify the signature using the public key issued from Binance Pay.

How it works#
  1. Configure the webhook endpoints in the Merchant Management Platform (MMP).

  2. Build the payload and verify the signature on your application. Please note that the certificate endpoint is fixed.

  3. Identify the events you want to be notified of.

  4. Get notified automatically on your order status.

  5. After receiving the notification, please acknowledge it by returning a HTTP 200 and “SUCCESS” in the response body.

Webhooks 1

Webhook Configuration in MMP#

Under the [Developer] tab, select [Webhooks] then [Edit], input your site URL to receive the webhook notification and description.

You can also view if the webhook notification has been successfully pushed to your site from the [Notification Log] tab.

Webhooks 3

Webhooks Common Rules#

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

Please follow the below rules for calling the Webhook Notification from Binance Pay.

RuleDescription
Transfer ModeUse HTTPS for secure transactions.
Submit ModePOST/GET, depends on the API.
Data FormatThe transaction has been paid.
Char EncodingUse UTF-8 character encoding.
Signature AlgorithmRSA, asymmetric cryptographic algorithm
Signature RequirementSignature-checking is required for requesting and receiving data
Logic JudgmentDetermine protocol field, service field and transaction status.
Rule
Transfer Mode
Description
Use HTTPS for secure transactions.
Rule
Submit Mode
Description
POST/GET, depends on the API.
Rule
Data Format
Description
The transaction has been paid.
Rule
Char Encoding
Description
Use UTF-8 character encoding.
Rule
Signature Algorithm
Description
RSA, asymmetric cryptographic algorithm
Rule
Signature Requirement
Description
Signature-checking is required for requesting and receiving data
Rule
Logic Judgment
Description
Determine protocol field, service field and transaction status.
Request Header#
AttributesTypeRequiredDescription
BinancePay-Certificate-SNlongYMD5 hash value of public key
BinancePay-NoncestringYA random string with 32 bytes, e.g. random asci...
BinancePay-TimestampstringYUnixTimestamp in milliseconds
BinancePay-SignaturestringYSignature, generated by Binance Pay
Attributes
BinancePay-Certificate-SN
Type
long
Required
Y
Description
MD5 hash value of public key
Attributes
BinancePay-Nonce
Type
string
Required
Y
Description
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
Attributes
BinancePay-Timestamp
Type
string
Required
Y
Description
UnixTimestamp in milliseconds
Attributes
BinancePay-Signature
Type
string
Required
Y
Description
Signature, generated by Binance Pay

For full protocol rules specification, please go to Webhook Common Rules.

Verify Signatures#

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#

Java

 // 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 );

Note: Hash algorithm should use SHA256

Query Certificate#

Merchants can use the “query certificate” API to obtain the public key and Hash Key.

End Point#
POST   /binancepay/openapi/certificates
Response Parameters#
AttributesTypeRequiredDescription
certSerialstringYpublic key hash value
certPublicstringYpublic key
Attributes
certSerial
Type
string
Required
Y
Description
public key hash value
Attributes
certPublic
Type
string
Required
Y
Description
public key

Webhook Example#

Merchants can use the “query certificate” API to obtain the public key and Hash Key.

Order Notification#

Binance Pay will notify Merchant the final status of the order through webhooks. Orders that are successfully closed will be under bizStatus = "PAY_CLOSED".

Payload Example#

You can either use “merchantTradeNo” or “prepayId” to search for a specific order. Please input at least one of them.

{  "bizType": "PAY",  "data": "{\"merchantTradeNo\":\"9825382937292\",\"totalFee\":0.88000000,\"transactTime\":1619508939664,\"currency\":\"BUSD\",\"openUserId\":\"1211HS10K81f4273ac031\",\"productType\":\"Food\",\"productName\":\"Ice Cream\",\"tradeType\":\"WEB\",\"transactionId\":\"M_R_282737362839373\"}",  "bizId": 29383937493038367292,  "bizStatus": "PAY_SUCCESS"}

To ensure that your server has received and accepted the notifications, please acknowledge every notification with a HTTP 200 and SUCCESS response in the body.

Response Example#
{ "returnCode":"SUCCESS", "returnMessage":null}

Orders with no payment activity over 24 hours will be closed automatically, please contact Binance Merchant Operation (https://merchant.binance.com/en/help) in order to get the notification.

Payout Notification#

Binance Pay will notify Merchant of the final status of the batch payout request initiated.

Payload Example#
{  "bizType": "PAYOUT",  "data": "{\"batchStatus\":\"SUCCESS\",\"currency\":\"BUSD\",\"merchantId\":100100006288,\"requestId\":\"gg8127129\",\"totalAmount\":2.00000000,\"totalNumber\":2}",  "bizId": 29383937493038367292,  "bizStatus": "SUCCESS"}

To ensure that your server has received and accepted the notifications, please acknowledge every notification with a HTTP 200 and SUCCESS response in the body.

Response Example#
{ "returnCode":"SUCCESS", "returnMessage":null}

Refund Notification#

Binance Pay will send refund order events with final status when you use the refund open API.

Successful close result for the close refund order request will be notified through this webhook bizStatus is "REFUND_SUCCESS" or "REFUND_REJECTED".

Payload Example#
{  "bizType": "PAY_REFUND",  "data":"{\"merchantTradeNo\":\"6177e6ae81ce6f001b4a6233\", \"totalFee\":0.01,\ "transactTime\":1635248421335,\"refundInfo\":{\"orderAmount\":\"0.01000000\",\"duplicateRequest\":\"N\",\"payerOpenId\":\"9aa0a8bb21cf5fbf049aad7db35dc3d3\",\"prepayId\":\"123289163323899904\",\"refundRequestId\":\"68711039982968853\",\"refundedAmount\":\"0.01000000\",\"remainingAttempts\":9,\"refundAmount\":\"0.01000000\"},\"currency\":\"BUSD\",\"commission\":0,\"openUserId\":\"b5ec36baaa5ab9a5cfb1c29c2057bd81\",\"productType\":\"LIVE_STREAM\",\"productName\":\"LIVE_STREAM\",\"tradeType\":\"APP\"}",  "bizId": 123289163323899904,  "bizStatus": "REFUND_SUCCESS"}

To ensure that your server has received and accepted the notifications, please acknowledge every notification with a HTTP 200 and SUCCESS response in the body.

Response Example#
{  "returnCode":"SUCCESS",  "returnMessage":null}