3.0 SDK's Return Result Format

{
    "code": 0,
    "msg": "success",
    "count": 0,
    "data": {}
}

The main parameters returned include:

Variable Name	Type	Description
code	int	Request return result, 0 for success, other values for failure
msg	string	Error message, success for success, other values for failure
count	int	When data is a JSON array, count represents the number of elements in data
data	object	Specific returned data, data can be a single JSON object or a JSON object array

3.1 Querying Supported Chain Information

Querying Supported Chain Information

HashNut supports multiple chains and currencies. Before merchants create orders, they can first query the chains supported by HashNut, and then query the currencies supported by that chain through the chain's code.

curl --location --request POST 'https://testnet-web3.hashnut.io/api/v2.0.0/config/queryAllChainInfo'

The returned information is as follows:

{
    "code": 0,
    "msg": "success",
    "ui": null,
    "version": null,
    "count": 0,
    "data": [
        {
            "id": 1,
            "chain": "ETH",
            "chainDesc": "BlockChain Ethereum",
            "enable": true,
            "receiptAddress": "0x8126ac362f08ec6a58b43e537f3dbbb474c70595",
            "txConfirmCount": "3",
            "walletConnectEnable": true,
            "bridgeServerAddress": "https://bridge.hashnut.io",
            "decimals": 18,
            "baseChainSymbol": "Ethereum",
            "env": 1,
            "chainId": "11155111",
            "baseChainCoin": "ETH",
            "createTime": 1710938845128,
            "updateTime": 1710938845128,
            "eip712ChainId": "0",
            "eip1559Support": true
        }
        ...
    ]
}

The main parameters returned include:

Variable Name	Type	Description
chain	string	Abbreviation of the name of the public chain supported by Hashnut, for example: ETH, BSC, TRON, POLYGON, etc.
chainDesc	string	Description of the public chain
enable	boolean	Whether the public chain is available
receiptAddress	string	The receiving address of HashNut platform on the public chain
txConfirmCount	int	The number of confirmations required for transactions on the public chain. If the confirmation count is reached or exceeded, Hashnut considers the transaction of the payment order valid
walletConnectEnable	boolean	Whether the public chain supports walletconnect protocol for payment. If the walletconnect protocol is not supported, end users need to scan the payment QR code with a wallet app
bridgeServerAddress	string	Bridge server address for walletconnect
decimals	int	For example: the precision of ETH is 18 decimal places, and the precision of TRON is 6 decimal places
baseChainSymbol	string	The name of the base chain
env	int	The environment of the current payment platform 0-Production 1-Testing 2-Development
chainId	long	ChainID of the EVM compatible chain, for example: 137 for the mainnet of POLYGON, 80001 for the Mumbai testnet
baseChainCoin	int	Abbreviation of the base chain's currency, for example: ETH for Ethereum, MATIC for the base currency on POLYGON
eip712ChainId	string	The chainId of this chain in eip712, this value is only valid for public chains that support eip712
eip1559Support	int	Whether eip1559 is supported

3.2 Query supported chain and currency information

Query supported chain and currency information

After obtaining the chain code, obtain the currencies supported by that chain, for example: query supported erc20 currencies

curl --location --request POST 'https://testnet-web3.hashnut.io/api/v2.0.0/config/queryAllCoinInfo'

The returned information is as follows:

{
    "code": 0,
    "msg": "success",
    "ui": null,
    "version": null,
    "count": 0,
    "data": [
        {
            "id": 1,
            "chain": "ETH",
            "chainCode": "erc20",
            "coinCode": "usdt",
            "isToken": true,
            "enable": true,
            "contractAddress": "0xe2d7250b2ec3cd208ac5b42886edd162411529c4",
            "coinDesc": "tether usdt",
            "gateWayEnable": true,
            "decimals": "6",
            "createTime": 1710938845130,
            "updateTime": 1710938845130,
            "nftmarket": "opensea"
        }
        ...
    ]
}

The main return parameters are as follows:

Variable Name	Type	Description
chain	string	The name of the chain where the currency is located, for example: ETH
chainCode	string	The code of the chain supported by hashnut, currently hashnut supports erc20, trc20, bep20, polygon-erc20
coinCode	string	Currency code, currently erc20 supports usdt, usdc, bep20 supports busd, hashnut, trc20 supports usdt
isToken	boolean	Whether the currency is a token, if it is the basic token of a public chain, such as eth, bsc, trx, then this value is false
enable	boolean	Whether the currency is currently available on hashnut, if the currency is not available, then orders cannot be created
contractAddress	string	The smart contract address of the current currency on this public chain
coinDesc	string	Description information of the currency
gateWayEnable	boolean	If this field is true, users can make gateway payments through the Binance app or other apps. Currently, Hashnut only supports Binance gateway
decimals	int	The precision of the currency, for example, the precision of the USDT currency in erc20 is 6, so when paying 1 USDT, the amount needs to be filled in as 1000000. For example, the precision of BUSD is 18

3.3 Querying supported currency information by currency type

Querying supported currency information by currency type

curl --location 'https://testnet-web3.hashnut.io/api/v2.0.0/config/querySupportCoinsByChainCode' \
--header 'Content-Type: application/json' \
--data '{
    "chainCode":"erc20"
}'

The returned information is as follows:

{
    "code": 0,
    "msg": "success",
    "ui": null,
    "version": null,
    "count": 0,
    "data": [
        {
            "id": 2,
            "chain": "ETH",
            "chainCode": "erc20",
            "coinCode": "usdc",
            "isToken": true,
            "enable": true,
            "contractAddress": "0x4ca772bb3e6326647b8dd02ddbc758773aa7c650",
            "coinDesc": "usdc",
            "gateWayEnable": true,
            "decimals": "6",
            "createTime": 1710938845132,
            "updateTime": 1710938845132,
            "nftmarket": "opensea"
        },
        ...
    ]
}

Parameters carried in the request body:

Variable Name	Type	Description
chainCode	string	token type, currently supported by HashNut: erc20, trc20, bep20, polygon-erc20

The main return parameters are as follows:

Variable Name	Type	Description
chain	string	The name of the chain where the currency is located, for example: ETH
chainCode	string	The code of the chain supported by hashnut, currently hashnut supports erc20, trc20, bep20, polygon-erc20
coinCode	string	Currency code, currently erc20 supports usdt, usdc, bep20 supports busd, hashnut, trc20 supports usdt
isToken	boolean	Whether the currency is a token, if it is the basic token of a public chain, such as eth, bsc, trx, then this value is false
enable	boolean	Whether the currency is currently available on hashnut, if the currency is not available, then orders cannot be created
contractAddress	string	The smart contract address of the current currency on this public chain
coinDesc	string	Description information of the currency
gateWayEnable	boolean	If this field is true, users can make gateway payments through the Binance app or other apps. Currently, Hashnut only supports Binance gateway
decimals	int	The precision of the currency, for example, the precision of the USDT currency in erc20 is 6, so when paying 1 USDT, the amount needs to be filled in as 1000000. For example, the precision of BUSD is 18

3.5 Create Order

Create Order

HashNut supports multi-currency payments, merchants can create orders and choose payment channels for orders

Request:

curl --location 'https://testnet-web3.hashnut.io/api/v2.0.0/pay/createPayOrderWithApiKey' \
--header 'hashnut-request-uuid: xxxx' \
--header 'hashnut-request-timestamp: xxxx' \
--header 'hashnut-request-sign: xxxx' \
--header 'Content-Type: application/json' \
--data '{
    "accessKeyId": "ACC_1156690317534035968",
    "merchantOrderId": "100000",
    "chainCode": "polygon-erc20",
    "coinCode": "usdt",
    "amount": 1.13,
    "receiptAddress": "0x1a580cca96a3d1070cb23b63480b3afafe0bf025"
}'

Parameters carried in the request body:

Variable Name	Type	Description
accessKeyId	string	Merchant API KEY ID
merchantOrderId	string	Merchant order number, a unique order ID generated by the merchant
chainCode	string	Chain code
coinCode	string	Currency code
amount	Decimal(20)	Amount to be paid, accurate to a maximum of 2 decimal places
receiptAddress	string	Address of the smart contract deployed by the merchant

Parameters carried in the request header:

Variable Name	Type	Description
hashnut-request-uuid	string	UUID generate by merchant
hashnut-request-timestamp	string	timestamp
hashnut-request-sign	string	Sign (uuid+timestamp+body) with the API secret key, where the body is the JSON-serialized string of the request content.

The code for generating hashnut-request-sign is as follows:

    String uuid=request.getHeader("hashnut-webhook-uuid");
    String timeStamp=request.getHeader("hashnut-webhook-timestamp");
    // body is body is the JSON-serialized string of the request content
    String dataToSign=String.format("%s%s%s",uuid,timeStamp,body);
    String sign= PayDigestUtil.HMACSHA256Base64(HashNutConfig.secretKey,dataToSign);

the PayDigestUtil.HMACSHA256Base64 code:

    public static String HMACSHA256Base64(String key,String data) throws Exception {
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key = new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        sha256_HMAC.init(secret_key);
        sha256_HMAC.update(data.getBytes());
        byte[] array = sha256_HMAC.doFinal();
        return Base64.getEncoder().encodeToString(array);
    }

The returned information is as follows:

{
    "code": 0,
    "msg": "success",
    "ui": null,
    "version": null,
    "count": 0,
    "data": {
        "mchAddress": "0x6a0b7b0b95ce640b3fe3fede6ebfed4de9293019",
        "chain": "POLYGON",
        "chainCode": "polygon-erc20",
        "coinCode": "usdt",
        "createChannel": 1,
        "accessChannel": 0,
        "merchantOrderId": "10000",
        "payOrderId": "01HSKATBCK7CE20N88B25870M5",
        "tokenAddress": "0x0de51eb069fd04f5ff6fb48f1dad6766ac558b33",
        "receiptAddress": "0x78f43ee9985aacd8da1c6dd099213b402aa98672",
        "amount": 1.160000,
        "state": 4,
        "accessSign": "24625267842A4074D6332A59A7BE49069C63B0392340171F1E2F1FF8C6AA9879",
        "payTxId": "0xd77cd2e8488e3b8db02dc5e3f2bdac2da99795fbcf91408b6eae68da50d752fb",
        "confirmCount": "3",
        "walletConnectEnable": true,
        "bridgeServerAddress": "https://bridge.hashnut.io",
        "eip712ChainId": "0",
        "chainId": "80001",
        "createTime": "0",
        "rate": 80,
        "obtainAmount": 1.15072,
        "platformFee": 0.00928
    }
}

The parameters in the response include

Variable Name	Type	Description
chain	string	Chain where the payment order token is located
mchAddress	string	Merchant address for placing orders, which is the merchant address that created the payment smart contract
chainCode	string	Chain code
coinCode	string	Currency code
createChannel	int	Channel through which the merchant created the order, 0-Merchant system 1-ApiKey, since the order is created through the API key, the value is 1
accessChannel	byte	The channel through which the end user pays for the order, since it is a blockchain payment, the value is 0
merchantOrderId	string	Merchant order number, a unique order ID generated by the merchant
payOrderId	string	Hashnut's platform order number, a unique receiving address generated by Hashnut
contractAddress	string	The smart contract address of the currency, when users send transactions, 'to' needs to be filled with the smart contract address of the currency
receiptAddress	string	Smart contract address used to receive user funds
inputData	string	Input data of the transaction, encoded using web3j, including: Hashnut receiving address and order amount
accessSign	string	Signature of (platformId+mchOrderId) using the API key

Merchant concatenates the payment order URL

Merchants use the accessSign, merchantOrderId, and payOrderId from the create order response to concatenate a payment URL to send to the end user, for example:

https://testnet-web3.hashnut.io/pay?accessSign=42889E72DAAE0C4275F804DDDFA4707823FE30EB4D4BB6064859CB65AA3E6305&merchantOrderId=10000&payOrderId=01HSKATBCK7CE20N88B25870M5

The parameters in the URL are:

Variable Name	Type	Description
accessSign	string	Signature of (platformId+merchantOrderId) using the api key
merchantOrderId	string	Merchant order ID
payOrderId	string	HashNut platform order ID, a unique order ID generated by HashNut

3.6 Callback notification

Callback notification

The callback URL can be configured in the Create ApiKey interface, including backend callback URL and frontend callback URL, both of which contain the following parameters:

Variable Name	Type	Description
payOrderId	string	HashNut platform order ID, a unique order ID generated by HashNut

3.7 Query order

Query order information

After receiving the payment order URL, users need to use accessSign to query the order information first to confirm if the order has been paid to prevent duplicate payments

Request:

curl --location 'https://testnet-web3.hashnut.io/api/v2.0.0/pay/queryPayOrderWithAccessSign' \
--header 'Content-Type: application/json' \
--data '{
    "merchantOrderId": "a89206d0-7883-48dd-9316-e494f2679e72",
    "payOrderId": "01HSKATBCK7CE20N88B25870M5",
    "accessSign": "24625267842A4074D6332A59A7BE49069C63B0392340171F1E2F1FF8C6AA9879"
}'

The requested parameters include:

Variable Name	Type	Description
merchantOrderId	string	Merchant order number, a unique order ID generated by the merchant
payOrderId	string	Platform order number of hashnut
accessSign	string	Signature of (platformId+mchOrderId) using the API key

The returned information is as follows:

{
    "code": 0,
    "msg": "success",
    "ui": null,
    "version": null,
    "count": 0,
    "data": {
        "mchAddress": "0x6a0b7b0b95ce640b3fe3fede6ebfed4de9293019",
        "chain": "POLYGON",
        "chainCode": "polygon-erc20",
        "coinCode": "usdt",
        "createChannel": 1,
        "accessChannel": 0,
        "merchantOrderId": "a89206d0-7883-48dd-9316-e494f2679e72",
        "payOrderId": "01HSKATBCK7CE20N88B25870M5",
        "tokenAddress": "0x0de51eb069fd04f5ff6fb48f1dad6766ac558b33",
        "receiptAddress": "0x78f43ee9985aacd8da1c6dd099213b402aa98672",
        "amount": 1.160000,
        "state": 4,
        "accessSign": "24625267842A4074D6332A59A7BE49069C63B0392340171F1E2F1FF8C6AA9879",
        "payTxId": "0xd77cd2e8488e3b8db02dc5e3f2bdac2da99795fbcf91408b6eae68da50d752fb",
        "confirmCount": "3",
        "walletConnectEnable": true,
        "bridgeServerAddress": "https://bridge.hashnut.io",
        "eip712ChainId": "0",
        "chainId": "80001",
        "callBackUrl": "https://testnet-web3.hashnut.io/shop/payFinish?payOrderId=01HSKATBCK7CE20N88B25870M5&chain=POLYGON&amount=1160000&chainCode=polygon-erc20&sign=CAD9387C2D51389B2512C324932B1277F68B177E6C3933BC5EA686FB3A935C8C&merchantOrderId=a89206d0-7883-48dd-9316-e494f2679e72&accessSign=24625267842A4074D6332A59A7BE49069C63B0392340171F1E2F1FF8C6AA9879&obtainAmount=1150720&payTxId=0xd77cd2e8488e3b8db02dc5e3f2bdac2da99795fbcf91408b6eae68da50d752fb&receiptAddress=0x78f43ee9985aacd8da1c6dd099213b402aa98672&merchantAddress=0x6a0b7b0b95ce640b3fe3fede6ebfed4de9293019&confirmCount=3&state=4&coinCode=usdt&paySuccessTime=",
        "createTime": "0",
        "rate": 80,
        "obtainAmount": 1.150720,
        "platformFee": 0.009280
    }
}

The response parameters include:

Variable Name	Type	Description
chain	string	Chain where the payment order token is located
mchAddress	string	Merchant address for placing orders, which is the merchant address that created the receiving smart contract
chainCode	string	Chain code
coinCode	string	Currency code
createChannel	int	Channel through which the merchant created the order, 0-merchant system 1-ApiKey, as the order was created through an API key, the value is 1
accessChannel	byte	Channel through which the end user pays the order, as it is a gateway payment, the value is 1
mchOrderId	string	Merchant order number, a unique order ID generated by the merchant
platformId	string	Platform order number of hashnut, a unique order number generated by hashnut
contractAddress	string	The smart contract address of the currency, users need to fill in 'to' with the smart contract address of the currency when sending transactions
receiptAddress	string	The smart contract address that receives user funds
inputData	string	The input data of the transaction, encoded using web3j, including: hashnut receiving address and order amount
accessSign	string	Signature of (platformId+mchOrderId) using the api key
qrcodeLink	string	Gateway payment QR code image address
qrContent	string	This value is ignored
walletConnectEnable	boolean	Whether this order supports walletconnect launch
bridgeServerAddress	string	If walletConnectEnable is true, this value represents the walletconnect bridge server address

When replying to the user, the user needs to pay attention to the state of the order. If the state is greater than 0, it means that the payment has already been made, and further payment will be rejected

For a more concise and detailed usage method, please refer to Test Case Source Code In ServiceTest.java

3.1 Querying Supported Chain Information

Querying Supported Chain Information​

3.2 Query supported chain and currency information

Query supported chain and currency information​

3.3 Querying supported currency information by currency type

Querying supported currency information by currency type​

3.5 Create Order

Create Order​

Merchant concatenates the payment order URL​

3.6 Callback notification

Callback notification​

3.7 Query order

Query order information​

Querying Supported Chain Information

Query supported chain and currency information

Querying supported currency information by currency type

Create Order

Merchant concatenates the payment order URL

Callback notification

Query order information