Udun Wallet API development interface document
1、Directory
1.1.Generate addresses 1.2.Withdrawal 1.3.Payment on behalf 1.4.Trade callback 1.5.Verify address legality 1.6.Obtain the information of tokens supported by merchants
2、Interface details
1. Generate addresses
1.1 Scenario description
Request the address of the designated tokens. Tokens must be saved in the wallet and supported by the wallet in order to get the address successfully,For more information, please refer to
1.2. Interface details
1.2.1 Interface addresses
| Interface details | |
| URL | 【/mch/address/create】 |
| Application method | POST |
1.2.2 Parameters
1.2.2.1 Parameter description
| Parameters | Type | Required or not | Description | Note |
| timestamp | String | is | Timestamp | See Verification description |
| nonce | String | is | Random number | See Verification description |
| sign | String | is | Sign | See Verification description |
| body | String | is | Message | json string, in the following format |
[
{
"merchantId":"300015",
"coinType":520,
"callUrl":"http://localhost:8080/callBack"
}
]
1.2.2.2 Body parameter field
| Body parameter name | Type | Required or not | Description |
| merchantId | String | is | Merchant ID |
| coinType | Integer | is | Main coin number. Use the interface to get merchant coin information. |
| callUrl | String | Is | The deposit information about the callback address created through the interface will be notified to you through the callback address you specified. See the trade callback interface for specific examples. |
| walletId | String | No | Wallet number. By default, the address is generated according to the main wallet. |
| alias | String | No | Address alias |
1.2.2.3 Examples
{
"timestamp":1535005047,
"nonce":10000,
"sign":"a230def43c1a12b14393880a28d4e005",
"body":"[{\"merchantId\":\"300015\",\"coinType\":520,\"callUrl\":\"http://localhost:8080/callBack\"}]"
}
1.2.3 Return to status code
| code | Explain |
| -1 | Failed to generate addresses |
| 200 | Generate addresses successfully |
| 4001 | No merchant |
| 4005 | Illegal parameters |
| 4045 | Wrong coin information |
| 4162 | Abnormal signature |
| 4163 | Wrong signature |
| 4166 | The merchant has no configuration package |
| 4168 | The merchant address reaches the upper limit |
| 4169 | The merchant has disabled |
| 4175 | Wrong wallet number |
| 4017 | The merchant does not create a wallet |
| 4176 | The coin is not added to the wallet |
| 4188 | Not supported now |
| 4226 | The merchant's general account is banned |
| 4261 | The merchant's administrator account is banned |
| 4262 | The account does not exist |
1.3 Call examples
1.3.1 Success
{
"data":{
"coinType":520,
"address":"0xbe4e3699cb870bc95365fe04a187dd279a651a58"
},
"message":"SUCCESS",
"code":200
}
1.3.2 Failure
{
"code":"4101",
"message":"SIGN_MSG_ERROR"
}
2、Send withdrawal application
2.1 Scenario description
Withdrawal application
2.2 Interface details
2.2.1 Interface address
| Interface details | |
| URL | 【/mch/withdraw】 |
| Application method | POST |
2.2.2 Parameters
2.2.2.1 Parameter description
| Parameters | Type | Required or not | Description | Note |
| timestamp | String | is | Timestamp | See Verification description |
| nonce | String | is | Random number | See Verification description |
| sign | String | is | Sign | See Verification description |
| body | String | is | Message | json string, in the following format |
[
{
"address":"raadSxrUhG5EQVCY75CSGaVLWCeXd6yH6s",
"amount":"0.11",
"merchantId":"100109",
"mainCoinType":"144",
"coinType":"144",
"callUrl":"http://localhost:8080/mch/callBack",
"businessId":"15",
"memo":"10112"
}
]
2.2.2.2 Body parameter field
| Body parameter name | Required or not | Type | Description |
| address | is | String | Withdrawal address |
| amount | is | String | Withdrawal amount |
| merchantId | is | String | Merchant ID |
| mainCoinType | is | String | Main coin number. Use the interface to get merchant coin information. |
| coinType | is | String | Child coin number. Use the interface to get merchant coin information. |
| callUrl | is | String | Callback address. You are informed of the status of the coin withdrawal transaction through the callUrl. For specific examples, See the trade callback interface for specific examples.Trade callback interface |
| businessId | is | String | Business id must be ensured that this field is unique in the system. If it is duplicated, the withdrawal will not be received by the wallet. |
| memo | no | String | Please note that this field is optional for withdrawal applications for XRP and EOS and other types of coins are not filled in. |
2.2.2.3 Examples
{
"timestamp":"1535005047",
"nonce":100000,
"sign":"6df1512ee650431632ce1541a6b064e1",
"body":"[{\"address\":\"raadSxrUhG5EQVCY75CSGaVLWCeXd6yH6s\",\"amount\":\"0.11\",\"merchantId\":\"100109\",\"mainCoinType\":\"144\",\"coinType\":\"144\",\"callUrl\":\"http://localhost:8080/callBack\",\"businessId\":\"15\",\"memo\":\"10112\"}]"
}
2.2.3 Return to status code
| code | Explain |
| 200 | Withdrawal success |
| 523 | The parameter is null |
| 581 | Invalid withdrawal amount |
| 4005 | Illegal parameters |
| 4014 | Coin type is null |
| 4034 | The coin information is not found |
| 4162 | Abnormal signature |
| 4163 | Wrong signature |
| 4169 | The merchant has been banned |
| 4183 | Abnormal arrival address |
| 4193 | EOS amount exceeds 4 decimal places in length |
| 4214 | No available coins now |
| 4226 | The merchant's general account is banned |
| 4261 | The merchant's administrator account is banned |
| 4284 | No merchant |
| 4288 | Business ID is duplicate. Please do not apply repeatedly |
| 4598 | All the merchant ID in the list passed into the body must be consistent |
| 4001 | No merchant |
2.3 Call examples
2.3.1 Success
{
"message":"SUCCESS",
"code":200
}
2.3.2 Failure
{
"code":"4101",
"message":SIGN_MSG_ERROR
}
3、Payment on behalf
3.1 Scenario description
Payment on behalf. Send automatic payment application and if payment on behalf information is not set or payment on behalf fails, it will enter the audit status.
3.2 Interface details
3.2.1 Interface address
| Interface details | |
| URL | 【/mch/withdraw/proxypay】 |
| Application method | POST |
3.2.2 Parameters
3.2.2.1 Parameter description
| Parameters | Type | Required or not | Description | Note |
| timestamp | String | is | Timestamp | See Verification description |
| nonce | String | is | Random number | See Verification description |
| sign | String | is | Sign | See Verification description |
| body | String | is | Message | json string, in the following format |
[
{
"address":"raadSxrUhG5EQVCY75CSGaVLWCeXd6yH6s",
"amount":"0.1",
"merchantId":"100146",
"mainCoinType":"144",
"coinType":"144",
"callUrl":"http://localhost:8080/callBack",
"businessId":"571001",
"memo":"10112"
}
]
3.2.2.2 Body parameter description
| Body parameter name | Type | Required or not | Description |
| merchantId | String | is | Merchant ID |
| address | String | is | Withdrawal address |
| mainCoinType | String | is | Main coin number. Use the interface to get merchant coin information. |
| coinType | String | is | Child coin number. Use the interface to get merchant coin information. |
| amount | String | is | Trade amount |
| callUrl | String | is | Callback address. The result of withdrawal (audit, transaction) will be called back through this address. See transaction callback interface for specific examples. |
| businessId | String | is | Business id must be ensured that this field is unique in the system. If it is duplicated, the withdrawal will not be received by the wallet. |
| memo | String | is | Please note that this field is optional for withdrawal applications for XRP and EOS and other types of coins are not filled in. |
3.2.2.3 Examples
{
"timestamp":1535005047,
"nonce":100000,
"sign":"e1bee3a417b9c606ba6cedda26db761a",
"body":"[{\"address\":\"raadSxrUhG5EQVCY75CSGaVLWCeXd6yH6s\",\"amount\":\"0.1\",\"merchantId\":\"100146\",\"mainCoinType\":\"144\",\"coinType\":\"144\",\"callUrl\":\"http://localhost:8080/callBack\",\"businessId\":\"571001\",\"memo\":\"10112\"}]"
}
3.2.3 Return to status code
| code | Explain |
| 200 | Withdrawal success |
| 4005 | Illegal parameters |
| 4001 | No merchant |
| 4166 | The merchant has no configuration package |
| 4169 | The merchant has been banned |
| 4612 | Abnormal signature |
| 4163 | Wrong signature |
| 569 | Invalid address |
| 571 | Audit records already exist and will not be processed |
| 581 | Invalid withdrawal amount |
| 554 | The merchant does not support this coin |
| 4183 | Abnormal arrival address |
| 4193 | EOS amount exceeds 4 decimal places in length |
| 4214 | No available coins now |
| 4261 | The merchant's administrator account is banned |
| 4226 | The merchant's general account is banned |
| 4284 | No merchant |
3.3 Call examples
3.3.1 Success
{
"message":"SUCCESS",
"code":200
}
3.3.2 Failure
{
"code":4101
"message":"SIGN_MSG_ERROR",
}
4、Trade callback interface
4.1 Scenario description
The gateway receives the transaction processing result and calls the callback interface provided by the merchant to notify the merchant of the specific change information. The interface gateway sends you the content of the callback address specified by you to process your business information. There are callbacks for deposit and withdrawal, of which up to two callbacks will be made for withdrawals (audit callback and transaction result callback)
4.2 Interface details
4.2.1 Interface address
| Interface details | |
| URL | |
| Application method | POST |
4.2.2 Parameters
4.2.2.1 Parameter description
| Parameters | Type | Required or not | Description | Note |
| timestamp | String | is | Timestamp | See Verification description |
| nonce | String | is | Random number | See Verification description |
| sign | String | is | Sign | See Verification description |
| body | String | is | Message | json string, in the following format |
{
"address":"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW",
"amount":"12345678",
"blockHigh":"102419",
"coinType":"206",
"decimals":"8",
"fee":"452000",
"mainCoinType":"206",
"status":3,
"tradeId":"20181024175416907",
"tradeType":1,
"txId":"31689c332536b56a2246347e206fbed2d04d461a3d668c4c1de32a75a8d436f0",
"businessId":"",// The coin withdrawal callback is the business id passed from the coin withdrawal interface, and the coin has no value.
"memo":""
}
4.2.2.2 Body parameter description
| Body parameter name | Type | Description |
| address | String | address |
| amount | String | Trade amount. The actual amount is obtained according to the precision of the coins. The actual amount=amount/pow(10,decimals), that is, the actual amount is equal to amount divided by 10 decimals times |
| fee | String | Miner's fee. The actual amount is obtained according to the precision of the coins. The actual amount is obtained as above. |
| decimals | String | Coin precision |
| coinType | String | Child coin number. Use the interface to get merchant coin information. |
| mainCoinType | String | Main coin number. Use the interface to get merchant coin information. |
| businessId | String | Business number is passed in for the coin withdrawal request at the time of the coin withdrawal callback. No value for the coin withdrawal callback. |
| blockHigh | String | Block height |
| status | Integer | Status, see Callback interface status description |
| tradeId | String | Transaction serial number |
| tradeType | Integer | Transaction type, see Callback interface transaction type description |
| txid | String | Blockchain transaction hash |
| memo | String | Please note that XRP and EOS using the interface to obtain merchant coin information may have values for coin deposit and withdrawal. |
4.2.2.2 Examples
{
"timestamp":1535005047,
"nonce":100000,
"sign":"e1bee3a417b9c606ba6cedda26db761a",
"body":"{\"address\":\"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW\",\"amount\":\"12345678\",\"blockHigh\":\"102419\",\"coinType\":\"206\",\"decimals\":\"8\",\"fee\":\"452000\",\"mainCoinType\":\"206\",\"status\":3,\"tradeId\":\"20181024175416907\",\"tradeType\":1,\"txId\":\"31689c332536b56a2246347e206fbed2d04d461a3d668c4c1de32a75a8d436f0\"}"
}
5、Verify address legality
5.1 Scenario description
Check the legality of the address. You can check the legality of the address first when adding addresses, withdrawing coins and other scenarios, see Verification rule
5.2 Interface details
5.2.1 Interface address
| Interface details | |
| URL | 【/mch/check/address】 |
| Application method | POST |
5.2.2 Parameters
5.2.2.1 Parameter description
| Parameters | Type | Required or not | Description | Note |
| timestamp | String | is | Timestamp | |
| nonce | String | is | Random number | |
| sign | String | is | Sign | |
| body | String | is | Message | json string, in the following format |
{
"merchantId":200000,
"mainCoinType":"206",
"address":"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW",
}
5.2.2.2 Body parameter description
| Body parameter name | Type | Required or not | Description |
| merchantId | Long | is | Merchant ID |
| mainCoinType | String | is | Main coin number. Use the interface to get merchant coin information. |
| address | String | is | Addresses to be verified |
5.2.2.2 Examples
{
"timestamp":1535005047,
"nonce":100000,
"sign":"e1bee3a417b9c606ba6cedda26db761a",
"body":"[{\"merchantId\":200000,\"mainCoinType\":\"206\",\"address\":\"DJY781Z8qbuJeuA7C3McYivbX8kmAUXPsW\"}]"
}
5.2.3 Return to status code
| code | Explain |
| 200 | Success |
| 4005 | Illegal parameters |
| 4162 | Abnormal signature |
| 4163 | Wrong signature |
| 4165 | Address is not legal |
5.3 Call examples
5.3.1 Success
{
"code":200,
"message":"SUCCESS"
}
5.3.2 Failure
{
"code":4005,
"message":"PARAM_ERROR"
}
6、Obtain the information of tokens supported by merchants
6.1 Scenario description
Obtain the tokens supported by merchants and the balance
6.2 Interface details
6.2.1 Interface address
| Interface details | |
| URL | 【/mch/support-coins】 |
| Application method | POST |
6.2.2 Parameters
6.2.2.1 Parameter description
| Body parameter name | Type | Required or not | Description |
| timestamp | String | is | Timestamp |
| nonce | String | is | Random number |
| sign | String | is | Sign |
| body | String | is | Message |
6.2.2.2 Body parameter description
| Body parameter name | Type | Required or not | Description |
| merchantId | Long | is | Merchant ID |
| showBalance | Boolean | is | Whether to check the balance. False is not to get it and true is to get it. |
6.2.2.3 Examples
{
"timestamp":1535005047,
"nonce":100000,
"sign":"e1bee3a417b9c606ba6cedda26db761a",
"body":"{\"merchantId\":\"200032\",\"showBalance\":true}",
}
6.2.3 Return to status code
| Status code | Explain |
| -1 | Query failed |
| 200 | Query successfully |
| 4005 | Illegal parameters |
6.3 Call examples
6.3.1 Success
{
"code":200,
"message":"SUCCESS",
"data":[
{
"name":"BTC", // Coin alias
"coinName":"Bitcoin", // Full name of the coin
"symbol":"BTC", // Coin unit
"mainCoinType":"0", //Main coin type
"coinType":"0", // Coin type
"decimals":"8", // Coin precision
"tokenStatus":"0", // 0： Main coin 1：Token
"mainSymbol":"BTC", //Main coin unit
"balance":"0", // Balance
"logo":"http://bipay-admin.oss-cn-hangzhou.aliyuncs.com/bipay-admin-release/coin-logo/BTC.png" // Coin log address
},
{
"name": "ETH", // Coin alias
"coinName":"Ethereum", // Full name of the coin
"symbol":"ETH", // Coin unit
"mainCoinType":"60", //Main coin type
"coinType":"60", // Coin type
"decimals":"18", // Coin precision
"tokenStatus":"0", // 0： Main coin 1：Token
"mainSymbol":"ETH", //Main coin unit
"balance":"0", // Balance
"logo":"https://bipay-admin.oss-cn-hangzhou.aliyuncs.com/bipay-admin-release/coin-logo/ETH.png" // Coin log address
}
]
}
6.3.2 Failure
{
"code":4005,
"message":"BGS_ILLEGAL_PARAMETER"
}
Appendix one
| Main coin number | Child coin number | Coin abbreviation | English name of the coin | Chinese name of the coin | Precision |
| 0 | 0 | BTC | Bitcoin | 比特币 | 8 |
| 60 | 60 | ETH | Ethereum | 以太坊 | 18 |
| 0 | 31 | USDT | Tether USD | 泰达币 | 8 |
| 520 | 520 | CNT | CNT | 测试币 | 18 |
| 5 | 5 | DASH | DASH | 达世币 | 8 |
| 133 | 133 | ZEC | ZEC | 大零币 | 8 |
| 145 | 145 | BCH | Bitcoincash | 比特币现金 | 8 |
| 61 | 61 | ETC | Ethereum Classic | 以太坊经典 | 18 |
| 2 | 2 | LTC | LTC | 莱特币 | 8 |
| 2301 | 2301 | QTUM | QTUM | 量子链币 | 8 |
| 502 | 502 | GCC | GalaxyChain | 8 | |
| 60 | Contract address | ETH | ETH | eth代币 | Depends on the token |
| 144 | 144 | XRP | Ripple | 瑞波币 | 6 |
| 194 | 194 | EOS | EOS | 柚子币 | 4 |
| 2304 | 2304 | IOTE | IOTE | IOTE | 8 |
| 2303 | 2303 | VDS | Vollar | Vollar币 | 8 |
Callback interface status description
| Status | Description |
| 0 | Pending review |
| 1 | Review successfully |
| 2 | Review rejected |
| 3 | Transaction success |
| 4 | Transaction failure |
Callback interface transaction type description
| Status | Description |
| 1 | Deposit callback |
| 2 | Withdrawal callback |
Verification description
In order to ensure that the parameter information transmitted by merchants to Udun will not be tampered
maliciously, the gateway provides MD5 encrypted digest authentication for merchant interface. The merchant can
use basic encryption parameters: time stamp, random number, signature key (the merchant's unique apikey) and
request plaintext parameters to perform MD5 encryption in the specified order to generate a verification
string sign. When the merchant requests the gateway interface, it takes time stamp, random number, request of
plaintext parameter and sign as parameters. The gateway gets the corresponding parameters and checks the
signature in the same way. Similarly, the gateway requests the merchant to verify in the same way.
sign=md5(body + key + nonce + timestamp)
Key is the interface authorization code APIKEY, which is assigned to the merchant by the gateway, and the
order of the encrypted fields cannot be wrong.
Coin address verification rules
| Main coin type | Coin abbreviation | English name of the coin | Chinese name of the coin | Address prefix | Address length interval |
| 0 | BTC | Bitcoin | 比特币 | 1 or 3 | [26,36] |
| 60 | ETH | Ethereum | 以太坊 | 0x | [42] |
| 145 | BCH | Bitcoincash | 比特币现金 | 1 | [26,36] |
| 61 | ETC | EthereumClassic | 以太坊经典 | 0x | [42] |
| 2 | LTC | Litecoin | 莱特币 | L or M | [26,36] |
| 508 | GX | GX | G | [26,36] | |
| 503 | NBTC | NBTC | N | No limit | |
| 99 | STO | STO | 证券型通证发行 | S | No limit |
| 5 | DASH | DASH | 达世币 | X | [26,36] |
| 2301 | QTUM | QTUM | 量子链币 | Q | [26,36] |
| 133 | ZEC | ZCash | 大零币 | t1 | No limit |
| 144 | XRP | Ripple | Ripple | r | [34] |
| 2303 | VDS | Vollar | Vollar | V |