Skip to main content

Webhooks

Binance uses webhooks to notify you when an event happens to your account. We will send you real-time notification automatically, keeping you up-to-date on what's happening.

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

Setting up Webhooks#

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.

How it works#
  1. Identify the events you want to monitor and be notified by configuring the webhook endpoints in Merchant Management Portal (MMP).

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

  3. Get notified now on your order status.

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

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".

Request 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"}
Response Example#
{ "returnCode":"SUCCESS", "returnMessage":null}

Orders with no payment activity over 24 hours will be closed automatically, pls contact Binance Merchant Operation (merchant@binance.com) in order to get the notification.

Payout Notification#

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

Request Example#

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

{  "bizType": "PAYOUT",  "data": "{\"batchStatus\":\"SUCCESS\",\"currency\":\"BUSD\",\"merchantId\":100100006288,\"requestId\":\"gg8127129\",\"totalAmount\":2.00000000,\"totalNumber\":2}",  "bizId": 29383937493038367292,  "bizStatus": "SUCCESS"}
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".

Request 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"}
Response Example#
{  "returnCode":"SUCCESS",  "returnMessage":null}