Merchant QR Code Notification

Binance Pay pushes a Merchant QR Code event to the webhook endpoint configured in the Merchant Management Platform each time a Binance user scans a merchant-owned QR code in the Binance App.

If the merchant endpoint does not return HTTP 200 OK (or the delivery fails), Binance Pay retries up to 6 times.

This is exclusively for Binance Pay official partnering partners. If you are interested, please contact your BD contact or email us at [email protected]

---

Request Body

Attribute	Type	Required	Description
bizType	string	Y	Constant MERCHANT_QR_CODE
bizId	long	Y	Unique identifier of this QR-scan event (equals referId)
bizIdStr	string	Y	bizId in string format
bizStatus	string	Y	Constant MERCHANT_QR_CODE_SCANED
data	object	Y	See Data Object

Data Object

Attribute	Type	Required	Description
qrContent	string	Y	Plain text extracted from the scanned QR code (usually a URL or payment string)
referId	string	Y	The same value as bizIdStr. Pass this value to the Create Prepay Order V3 API parameter qrCodeReferId so that Binance Pay can link the scan event to the order

Sample Payload

{
  "bizType": "MERCHANT_QR_CODE",
  "bizId": 368899096379834368,
  "bizIdStr": "368899096379834368",
  "bizStatus": "MERCHANT_QR_CODE_SCANED",
  "data": {
    "qrContent": "https://pay.partner.com/xx",
    "referId": "368899096379834368"
  }
}

---

Handling the Notification

1. Receive the notification and parse qrContent and referId.
2. Create a payment order through Create Prepay Order V3 and put
   referId into the request parameter qrCodeReferId. One qrCodeReferId only can be used once.
3. Reply to the webhook with HTTP 200 OK and the following body:

Response Body

Attributes	Type	Required	Limitation	Description
returnCode	string	Y	"SUCCESS" or "FAIL"	result code of notification processing, if process fail, Binance Pay will retry
returnMessage	string	N	-	return message refer to

{
  "returnCode": "SUCCESS",
  "returnMessage": null
}

If returnCode is not SUCCESS (or the HTTP status is not 200), Binance Pay will retry delivery up to 6 times.

ReturnMessage Object For Error Case

Attribute	Type	Required	Description
status	string	Y	Status of the operation. In error cases, this value is typically "REJECTED"
code	string	Y	Error code that identifies the specific type of error (e.g., "AMOUNT_EXCEEDS_THRESHOLD")

{
  "returnCode": "SUCCESS",
  "returnMessage": {
    "status": "REJECTED",
    "code": "AMOUNT_EXCEEDS_THRESHOLD"
  }
}

Error Codes

Error Code	Description	Binance Pay Behavior
AMOUNT_EXCEEDS_THRESHOLD	The payment amount exceeds the merchant's threshold limit	Binance Pay will prompt the user to use their device's native camera app to scan the QR code.

---

Event Life-cycle Diagram

User scan QR → Binance Pay → Merchant Webhook
                           ↘ receives (qrContent, referId)
                            Merchant creates order
                            Create Prepay Order V3  (qrCodeReferId = referId)

---