Skip to main content

Direct Debit/Pre Authorization Create Contract

This API is for merchant/partner to create direct debit/ pre authorization contract for user authorization.

  • This API is only available for whitelisted merchants. You may apply for direct debit on the merchant dashboard under Products > Debit Management. Alternatively, you may contact us at merchant@binance.com, along with your Merchant ID, background and use case.

EndPoint​

POST /binancepay/openapi/direct-debit/contract

Request Parameters​

AttributesTypeRequiredLimitationDescription
subMerchantIdstringNmaximum length 19The sub merchant account id, issued when sub merchant been created at Binance.
merchantContractCodestringYletter or digit, no other symbol allowed, maximum length 32The unique ID assigned by the merchant to identify a direct debit contract request.
serviceNamestringYmaximum length 32service name
scenarioCodestringYeg. General_Travel, for more please refer to
singleUpperLimitdecimalYMax Unit Range: 8 decimal placesupper limit related to scenarioCode, for more please refer to
currencystringYonly "USDT" or "USDC" is accepted and "USDC" for mica user, fiat not supportedOrder currency also the settlement currency
periodicbooleanYtrue/falsethis contract support periodic debit or not
cycleDebitFixedbooleanNtrue/falsemandatory if periodic = true. true = fixed amount, false = variable amount
cycleTypestringNMONTH or DAYmandatory if periodic = true. Values: MONTH or DAY
cycleValueintegerN-mandatory if periodic = true. Values: if cycleType=MONTH: 1~24, cycleType=DAY: interval days >7

Combining with another parameter cycleType to determine the deduction period, for example, cycleType is DAY, cycleValue=30, then the deduction period is 30 days; cycleType is MONTH, cycleValue=3, then the deduction period is 3 natural months.
firstDeductTimelongN-mandatory if periodic = true. first deduct time, must be a future time in milli seconds. if cycleType=MONTH, the firstDeductTime is not allowed to pass the date after the 28th UTC (can pass the 28th)
merchantAccountNostringNmaximum length 64the userID/user account in merchant side e.g. xxx@gmail.com
requestExpireTimelongN-If not specified, requestExpireTime will be 1 hour. maximum is 1 hour in milliseconds.
contractEndTimelongN-If not specified, contractEndTime will be the time after 1095 days (about 3 years). maximum is 1095 days in milliseconds.

scenario-code​

Scenario CodeDefault Upper limit
General_Ecommerce_Platform50 USD equivalent
General_Travel50 USD equivalent
Car_Rental50 USD equivalent
Car_Parking50 USD equivalent
Lease50 USD equivalent
Catering50 USD equivalent
Digital_Media50 USD equivalent
Membership50 USD equivalent
Utility50 USD equivalent
Repayment50 USD equivalent
Investment50 USD equivalent
Ticket50 USD equivalent
Mobile_Communication50 USD equivalent
Virtual_Goods50 USD equivalent
Others50 USD equivalent

Sample Request Body​

{
    "merchantContractCode": "c0ecfb465e454560a5d8e307bbc407c5",
    "serviceName": "Tra Direct Debit",
    "scenarioCode":"Membership",
    "currency": "USDT",
    "singleUpperLimit": "30",
    "periodic": true,
    "cycleDebitFixed":true,
    "cycleType": "DAY",
    "cycleValue": 8,
    "firstDeductTime": 1677628800000,
    "merchantAccountNo": "sss@gmail.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
merchantIdLongYnumbermerchant Id in binance
preContractIdstringYmaximum length 19unique id generated by binance
contractEndTimelongY-contract will be expired at this time
requestExpireTimelongY-user can not sign contract after this time
qrContentstringYmaximum length 256qr content info
qrcodeLinkstringYmaximum length 256qr code img link
deeplinkstringYmaximum length 256deeplink to open binance app to sign contract

Sample Response​

applied success​

{
    "status": "SUCCESS",
    "code": "000000",
    "data": {
        "merchantId": 1000855410,
        "preContractId": "203616506788478976",
        "requestExpireTime": 1672656724308,
        "contractEndTime": 1767261124308,
        "qrContent": "https://app.binance.com/qr/xxx",
        "qrcodeLink": "https://public.bnbstatic.com/static/payment/20230405/xxx.jpg",
        "deeplink": "bnc://app.binance.com/mp/app?appId=V6tETccUyFTfoyMsGYH6aK&startPagePath=cGFnZXMvY29udHJhY3Qtc2lnbi9pbmRleA&startPageQuery=cHJlQ29udHJhY3RJZD0yMDM2MTY1MDY3ODg0Nzg5NzY="
    }
}

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
PAYMENT_INVALID_PARAM400702Invalid request parameter
MERCHANT_ACCESS_FORBIDDEN400606Account has no accessibility to this function
INVALID_REQUEST_CURRENCY_NOT_SUPPORTED400105Invalid request, currency is not supported
PAYMENT_DIRECT_DEBIT_EXCEED_LIMIT406200The singleUpperLimit exceed direct debit limit
PAYMENT_DIRECT_DEBIT_CONTRACT_CODE_INVALID406201merchantContractCode is invalid or duplicated
PAYMENT_DIRECT_DEBIT_AMOUNT_PRECISION_INVALID406202The singleUpperLimit precision is not valid