Skip to main content

Direct Debit/Pre Authorization Payment

This API is used for Merchant/Partner to apply for payment (like periodic and non-periodic debit), requests will be processed asynchronously and result will be notified via webhook.

*This API is only available for whitelisted merchants. If you need any help, you can contact us: merchant@binance.com

EndPoint#

POST /binancepay/openapi/pay/apply

Request Parameters#

AttributesTypeRequiredLimitationDescription
subMerchantIdstringNmaximum length 19The sub merchant account id, issued when sub merchant been created at Binance, The parameter subMerchantId is required when configuring show subMerchant info.
merchantRequestIdstringYletter or digit, no other symbol allowed, maximum length 32The order id, Unique identifier for the request, idempotent result will be returned for same requestId
tradeModestringY"DIRECT_DEBIT"
bizIdLongYnumberbusiness orderId like contractId
preBizIdLongNnumberprerequisite orderId like pay notification orderId for periodic debit scenario
amountdecimalYMax Unit Range: 8 decimal placesAmount to be deducted, please ensure the amount do not exceed the singleUpperLimit of the contract.
currencystringYonly "USDT" can be accepted, fiat NOT supported.order currency
productTypestringNmaximum length 16product type
productNamestringYmaximum length 256product name
productDetailstringNmaximum length 256product detail
webhookUrlstringNmaximum length 256. Can only start with http or https.The URL for order notification. If the webhookUrl is passed in the parameter, the webhook url configured on the merchant platform will not take effect, and the currently passed url will be called back first.
orderTagsObjectNorder tags refer to

orderTags#

AttributesTypeRequiredLimitationDescription
ifProfitSharingbooleanNif specified and true, order will be tagged as profitsharing.

Sample Request Body#

{    "subMerchantId": 123,    "merchantRequestId": "abcd",    "tradeMode": "DIRECT_DEBIT",    "bizId":123,    "productName": "test payment",    "amount": 6,    "currency":"USDT",    "webhookUrl": "https://abc.com"}

Response Parameters#

AttributesTypeRequiredLimitationDescription
statusstringY"SUCCESS" or "FAIL"status of the API request
codestringY-request result code, refer to
dataDataObjectN-response body, refer to
errorMessagestringNmaximum length 256

Child Attribute#

DataObject#

AttributesTypeRequiredLimitationDescription
orderIdstringYmaximum length 19unique id generated by binance
merchantRequestIdstringYletter or digit, no other symbol allowed, maximum length 32The order id, Unique identifier for the request
appliedTimelongY-transaction time in milli seconds
statusstringY"SUCCESS" or "FAILED" or "INIT" or "PROCESSING"status of the order

Sample Response#

applied success#

{    "status": "SUCCESS",    "code": "000000",    "data": {        "merchantRequestId": "abcd",        "orderId": "1111",        "appliedTime": 1672755315849,        "status": "INIT"    }}

Result Code#

NameCodeReasonSolution
UNKNOWN_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 supported.Check Request method.
MEDIA_TYPE_NOT_SUPPORTED400007Media type not supported.Check Request Media type.
INVALID_REQUEST_BODY400008Request body is not a valid json object.Check Request body
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
MERCHANT_TRANSFER_MERCHANT_TYPE_INVALID406107Merchant type not valid not support individual merchant
MERCHANT_TRANSFER_MERCHANT_TOO_FREQUENT406108Fail rate is high, please try again later