7.3.2 Create a scan-code payment order with a limited amount of digital currency (merchant-defined exchange rate)

#Brief description: Digital currency recharge business interface, users can recharge USDT (Tether) to their digital wallet account by scanning the QR code (merchant’s customized exchange rate, need to log in to the merchant’s backend settings)

• Request method: POST
• Request interface: https://gateway-domain/wallet-trade-merchant/v1/receive/blockchain/fixed/custom/rate/create
• Request media type (JSON data format)Content-Type: application/json

Request parameters

Parameter name	Type	Required	Parameter meaning	Parameter description
key	string	Yes	Merchant key	apiKey
localOrderId	string	Yes	Merchant platform local order number	Merchant platform generates unique order number locally
localUserId	string	No	Merchant platform local user ID	Merchant platform local user ID
notifyUrl	string	No	Callback address	After the order is successfully placed, the address of the merchant will be notified by API callback (callback details are at the bottom)
successRedirectUrl	string	No	Jump address	Automatically jump to address after success
userCurrency	string	Yes	Currency	The currency that the user needs to pay (the wallet supports digital currencies)
quoteCurrency	string	Yes	Customized quotation currency	Customized quotation currency (you need to log in to the merchant backend to set the quotation currency exchange rate)
quoteAmount	number	Yes	Custom quotation amount	Order pricing amount
isBlockchain	boolean	No	Whether to return blockchain information (default false)	When true, the callback request will carry the transaction information on the order chain
networkLimits	array	No	Mainnet	Designated payment mainnet, such as TRON, BSC, POLYGON, ETHEREUM
expireSecond	Long	No	Expiration timestamp (seconds)
sign	string	Yes	Signature	See Signature Algorithm for details

Request json sample

{
  "key": "dNNTJZpgFVWlYrVv",
  "localOrderId": "CONANTEST01140",
  "userCurrency": "USDT",
  "quoteCurrency": "CNY",
  "quoteAmount": "20",
  "networkLimits": ["TRON", "BSC"],
  "sign": "401c6541a4ba99794981233794f29a56"
}

Response json example

{
  "code": 0,
  "success": true,
  "message": null,
  "data": {
    "orderId": 474108977750213,
    "localUserId": null,
    "localOrderId": "CONANTEST01140",
    "orderType": "PAYMENT",
    "orderBizType": "PAYMENT_FIXED_DIGITAL_SCAN",
    "paymentUrl": "https://dxpay.dxstudio.org/fixed-amount-pay/JhpkZduKiBYPyn3WhobAWJnzwLMmvWxGwqrBFTRRDBf6VX7UUJeqL52ERxX6",
    "publicKey": "JhpkZduKiBYPyn3WhobAWJnzwLMmvWxGwqrBFTRRDBf6VX7UUJeqL52ERxX6",
    "currency": "CNY",
    "userCurrency": "USDT",
    "amount": "20",
    "userReceivableAmount": "1.83",
    "rate": "10.9",
    "rateExpression": "1USDT≈10.9CNY"
  }
}

The returned paymentUrl pops up the payment page, as shown below: 

data parameter description

Parameter name	Type	Parameter meaning	Parameter description
orderId	string	Order ID
localUserId	string	Merchant local user ID
localOrderId	string	Merchant local order number
orderType	enum	Order Type	PAYMENT:支付订单 | WITHDRAW:提款订单
orderBizType	enum	Order business type	orderBizType type description is as follows
paymentUrl	string	Payment address
publicKey	string	Key	Public Access Key
currency	string	Order currency
userCurrency	string	User payment currency
amount	string	Order amount
userReceivableAmount	string	Amount payable by the user
rate	string	Exchange rate
rateExpression	string	Order exchange rate expression

orderBizType type description:

1. PAYMENT_WALLET_SCAN VAPY wallet scan code payment
2. PAYMENT_TRANSFER digital currency binding address direct deposit
3. PAYMENT_ANY_DIGITAL_SCAN Scan the QR code to pay any amount of digital currency
4. WITHDRAW_WALLET withdraw money to VAPY wallet
5. WITHDRAW_ANY_DIGITAL_WALLET Withdraw digital currency to any wallet
6. PAYMENT_FIXED_DIGITAL_SCAN digital currency limited amount scan code payment
7. BATCH_PAY batch payment

Callback details

The callback method is: POST application/json

Example of jsonization of callback parameters

{
  "amount": 1,
  "bizType": "PAYMENT_FIXED_DIGITAL_SCAN",
  "blockchain": {
    "network": "TRON",
    "receiverAddress": "TA1jptT16DssYWVGdVyFWxonku6hWK7En3",
    "senderAddress": "TPutFhYUQnrRxHSmKVwjp55vgk9QY6r5nS",
    "txId": "24d0d0e5d417bd2195c45d64724760ae47fc3b359ee31c5fedf25b40f3584b36"
  },
  "currency": "USDT",
  "extra": {
    "quoteAmount": 10,
    "quoteCurrency": "CNY",
    "quotePrice": 10
  },
  "key": "h3cS7dBltRU4W1wD",
  "localOrderId": "2820",
  "merchantActualAmount": 22.72,
  "merchantCurrency": "CNY",
  "merchantId": 303122065665,
  "merchantPaidAmount": 7.33,
  "notifyTime": 1736744168370,
  "orderCreateTime": 1731572133082,
  "orderId": "273124814912907",
  "sign": "699806308a9e055114c378671b0d2a15",
  "status": "SUCCESS",
  "type": "WITHDRAW",
  "userAmount": 1,
  "userCurrency": "USDT",
  "userReceivableAmount": 1
}

Parameter name	Type	Participating signature	Parameter meaning	Parameter description
amount	decimal	Yes	Order Amount
bizType	enum	Yes	Order Type
blockchain	object	Yes	Chain transaction information	When the order request parameter isBlockchain is true, the callback request will carry this object information. (When only on-chain transactions are involved, the isBlockchain parameter will take effect)
└network	String	Yes	Mainnet
└receiverAddress	String	Yes	Receiver Address
└senderAddress	decimal	Yes	Sending address
└txId	String	Yes	Transaction ID
currency	String	Yes	Currency
key	String	Yes	Merchant key
localOrderId	String	Yes	Local order number
merchantActualAmount	decimal	Yes	Merchant’s actual payment amount
merchantCurrency	String	Yes	Merchant payment currency	Default currency
merchantId	String	Yes	Merchant ID
merchantPaidAmount	decimal	Yes	Merchant payment amount
merchantUserId	String	Yes	User id
notifyTime	long	Yes	Callback time
orderCreateTime	long	Yes	Order Creation Time
orderId	String	Yes	Order number
status	String	Yes	Payment Status
type	String	Yes	Order Type	PAYMENT:支付 WITHDRAW：提款
userAmount	decimal	Yes	User payment amount
userCurrency	String	Yes	User payment currency
sign	String	No	md5 signature	See signature algorithm for details
extra	object	Yes	Contains the following parameters
└quoteAmount	number	Yes	Order quote amount
└quoteCurrency	number	Yes	Order quote currency
└quotePrice	string	Yes	Order quotation price
userReceivableAmount	string	Yes	Amount payable by the user

When you receive the callback notification, please directly return the string success after the processing is completed, indicating that the message has been successfully received and processed. After the system receives the success response, it will no longer send the callback repeatedly. If the expected response is not received (success is not returned or an exception is returned), the system will resend the callback notification according to the stepped retry mechanism, retrying up to 14 times. The current retry intervals are: 15s, 15s, 30s,180s, 600s, 1200s, 1800s, 1800s, 1800s,3600s,10800s,10800s,21600s, 21600s