API Document

# Crypto payment (User Mode) API documentation

# 1. How to get API Key

   The user logs in to the cash register -> Developer Center -> API Key -> Create API key. API Key has a separate configuration page and is bound to a fixed IP address ("0.0.0.0" means no IP interception filtering, any IP can be accessed), and different API Keys can be configured to meet different needs. Please do not disclose your Access Key and Secret Key to avoid asset loss. After the Secret Key is generated, it cannot be viewed again. Please save it in time. If you forget the Secret Key, please recycle the key pair in the backstage of the merchant and apply for a new key pair.

# 1.1 How to create API KEY

• Click Developer Center-API Key

• 1 Choose whether to enable the debug mode (After debugging mode is enabled, you will have a standard prompt message and log view address for any errors)

• 2Select API Key permission

• 3Enter the whitelist address (0.0.0.0 means any IP address can be accessed)

Note: (When entering the whitelist domain name, you should pay attention to using "," to isolate multiple IPs.)

• 4 click create to generate API KEY

(After the API KEY is generated, you can copy, view, edit, and delete it in the My API KEY list below. Note that the Secret key only appears once when it is generated. Please save it properly. If you forget the Secret Key, Please recycle the key pair and apply for a new one.)

• Click Edit to close or open [Start Debugging] and modify the API Key permission and whitelist address. After the modification is complete, click Save

Note: Please wait patiently for 90 seconds for the API Key to take effect after creating or editing the API Key

# 2. How to use API Key

The current API Key is to add a parameter list in the header of the request

Parameter name Parameter description Type Required
access_key Api Key access key (eg: TPhoa7ZQ) String Yes
timestamp Millisecond-level timestamp (13 digits, such as: 1679669488472) String Yes
nonce UUID (36 bits such as: 02f7a04f-53cc-47d4-bb3f-fae69dab49ac) The five parts are 8 characters, 4 characters, 4 characters, 4 characters, and 12 characters, with "-" in the middle interval String yes
sign Parameter signature (eg: GXx2wYUD6UVr+zcmeCSFFPzcBLA=) String Yes

# 3. Technology side parameter access process

# 4. How to sign the interface

# Signature Description

   API requests are very likely to be tampered with during transmission over the internet. In order to ensure that the request has not been changed, all private interfaces except public interfaces (basic information, market data, etc.) must use your API Key is used for signature verification to verify whether parameters or parameter values have changed during transmission.

A legitimate request consists of the following parts:

  • access_key: API access key;
  • secret_key: The key used for signature encryption (only visible once when applying for an API Key in the background, please copy and save it in a safe place, and do not disclose it);
  • timestamp: The time (UTC time) when you made the request. Such as: 1632811287325 (13 digits). Including this value in a query request helps prevent third parties from intercepting your request;
  • nonce: random UUID string. Such as: 053a1b81-48a0-4bb1-96b2-60f6e509d911 (36 bits);
  • sign: The value calculated by the signature, which is used to ensure that the signature is valid and has not been tampered with;
  • All interfaces need to pass the above public parameters except secret_key in the http request header (header). The public parameters include (access_key, timestamp, nonce, sign) and other signature parameters are described in the API interface as allow.

# Signature steps

​ 1. Define a Map dictionary type object, and put the parameters in the request into it in the form of key-value

​ 2. Put access_key, timestamp, and nonce into the Map defined in the first step

​ 3. Sort the attributes in the Map in ascending order (lexicographic order) according to the ASCII code and convert the Map to a string in the form of "key1=value1&key2=value2"

​ 4. Encrypt the character string converted in the previous step with secret_key by HMAC_SHA1 and perform Base64 transcoding to obtain the value of the sign parameter. secret_key is the information in the apikey created on the cashier platform

​ 5. Add the sign value and other required parameters to the request header, and send the request to the target interface

# Signature debugging tools

  • SignUtil: User login to cash register -> Developer Center -> API Documentation -> Signature Tool The Signature tool page is displayed (The access_key in the tool, please use a valid access_key and please set the IP whitelist that allows this access_key access to 0.0.0.0, we strongly recommend the used Access_key is discarded after debugging)

# 5. Interface list

# 5.1 Test interface connectivity

request method

Get

Request URL

/ping

response data

{"version":"1.0.1","timestamp":1688116827306}

Response parameter description

Param Type Desc
version String If this parameter is returned, all interfaces in this document can be requested normally
timestamp int64 Unix timestamp

# 5.2 Public rate request return

request method

post

Request URL

/api/v3/wallet/rate

Request type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

{"currencyCode": "USD",
"coinCode": "USDT"}

Description of request parameters

Param Desc Require
currencyCode legal currency code USD CNY EUR GBP MXN PHP CAD TRY (String) required
coinCode Token code USDT USDC BUSD TUSD DAI (String) required

response type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

response data

{
     "code": "200",
     "success": true,
     "msg": "Success",
     "msgEn": "SUCCESS",
     "data": {
         "symbol": "USDT",
         "quote": "USD",
         "price": 0.994,
         "active": true
     }
}

Response parameter description

Param Type Desc
symbol String token type
quote String Fiat type
price float64 exchange rate
active bool is active

# 5.3 Binance rate request return

request method

post

Request URL

/api/v3/wallet/binance/rate

Request type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

"currencyCode": "USD",
"coinCode": "USDT"

Description of request parameters

Param Desc Require
currencyCode legal currency code USD CNY EUR GBP MXN PHP CAD TRY (String) required
coinCode Token code USDT USDC BUSD TUSD DAI (String) required

response type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

response data

{
     "code": "200",
     "success": true,
     "msg": "Success",
     "msgEn": "SUCCESS",
"data": {
         "symbol": "USDT",
         "quote": "USD",
         "price": 0.994,
         "active": true
}
}

Response parameter description

Param Type Desc
symbol String token type
quote String Fiat type
price float64 exchange rate
active bool is active

# 5.4 Add Create Wallet

request method

Post

Request URL

/api/v3/wallet/create

Request type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

{
    "chainType":"TRON",
    "tokenType":"USDT",
    "userFlagId":"WSXTES"
}

Description of request parameters

Param Desc Require
chainType chain type ETH TRON BSC (String) required
tokenType token type USDT USDC TUSD BUSD ETH(String) required
userFlagId User Unique Identification (String) required

response type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

response data

{
    "code": "200",
    "success": true,
    "msg": "成功",
    "msgEn": "SUCCESS",
    "data": {
        "chainType": "TRON",
        "tokenType": "USDT",
        "userFlagId": "WSXTES",
        "address": "TUZjksDTvauNfQ5rUbeeCUhu1xHKP8c9Th"
    }
}

Response parameter description

Param Type Desc
chainType String chain type
tokenType String token type
userFlagId String User Unique Identification
address String Wallet address

# 5.5 Inquiry of payment wallet address details

request method

post

Request URL

/api/v3/wallet/query/address/detail

Request type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

{
  "addressTo": "TAoW8YQhJFtoQKZxyNBB6GtRuay3BP2tQW",
  "startTime": "2024-03-31T16:00:00Z",
  "endTime": "2024-04-09T15:59:59Z"
}

Description of request parameters

Param Desc Require
addressTo Receiving address（String） required
startTime start time （String）The time zone is UTC required
endTime end time（String）The time zone is UTC required

response type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

response data

{
    "code": "200",
    "success": true,
    "msg": "成功",
    "msgEn": "SUCCESS",
    "data": [
        {
            "orderId": "OCRYPPAID202311031003401699005820300DEV001OO0000000400001022",
            "cashierId": "",
            "orderType": 1,
            "orderResourceType": 1,
            "userId": "1719629264270237698",
            "orderStatus": 4,
            "orderTime": 1699005820000,
            "channelOrderId": "",
            "externalOrderId": "",
            "orderAmount": "12",
            "orderActualAmount": "12",
            "orderEntryAmount": "11",
            "orderFee": "1",
            "orderPayTime": 1699005820000,
            "orderCompleteTime": 1699005820000,
            "currencyType": "USD",
            "tokenType": "USDT",
            "chainType": "TRON",
            "exchangeRate": "0.991",
            "addressFrom": "TBoG3wMvQhFUYQdcrHF6M3s7TKNHvCdW4w",
            "addressTo": "TAoW8YQhJFtoQKZxyNBB6GtRuay3BP2tQW",
            "tradeHash": "ff085ab75fc8edcb2a12142531f3c6442888cde94dce44bc1da41b361bb2e0e3",
            "orderTypeCode": "Pay",
            "orderResourceTypeCode": "Crypto",
            "orderStatusCode": "Completed"
        },
        {
            "orderId": "OCRYPPAID202311031003041699005784949DEV001OO0000000400001021",
            "cashierId": "",
            "orderType": 1,
            "orderResourceType": 1,
            "userId": "1719629264270237698",
            "orderStatus": 4,
            "orderTime": 1699005785000,
            "channelOrderId": "",
            "externalOrderId": "",
            "orderAmount": "11",
            "orderActualAmount": "11",
            "orderEntryAmount": "10",
            "orderFee": "1",
            "orderPayTime": 1699005785000,
            "orderCompleteTime": 1699005785000,
            "currencyType": "USD",
            "tokenType": "USDT",
            "chainType": "TRON",
            "exchangeRate": "0.991",
            "addressFrom": "TBoG3wMvQhFUYQdcrHF6M3s7TKNHvCdW4w",
            "addressTo": "TAoW8YQhJFtoQKZxyNBB6GtRuay3BP2tQW",
            "tradeHash": "928f51cd2d4123682c7f4c12aff68615f150563386065f84c62b311f64b58482",
            "orderTypeCode": "Pay",
            "orderResourceTypeCode": "Crypto",
            "orderStatusCode": "Completed"
        },
        {
            "orderId": "OCRYPPAID202311010903371698829417650DEV001OO0000000400000935",
            "cashierId": "",
            "orderType": 1,
            "orderResourceType": 1,
            "userId": "1719629264270237698",
            "orderStatus": 4,
            "orderTime": 1698829418000,
            "channelOrderId": "",
            "externalOrderId": "",
            "orderAmount": "31",
            "orderActualAmount": "31",
            "orderEntryAmount": "29.76",
            "orderFee": "1.24",
            "orderPayTime": 1698829418000,
            "orderCompleteTime": 1698829418000,
            "currencyType": "USD",
            "tokenType": "USDT",
            "chainType": "TRON",
            "exchangeRate": "0.991",
            "addressFrom": "TBoG3wMvQhFUYQdcrHF6M3s7TKNHvCdW4w",
            "addressTo": "TAoW8YQhJFtoQKZxyNBB6GtRuay3BP2tQW",
            "tradeHash": "616b29d8d572dd8920d7d061e3ed462e54b12e368deae56c06051a03be2e5f24",
            "orderTypeCode": "Pay",
            "orderResourceTypeCode": "Crypto",
            "orderStatusCode": "Completed"
        }
    ]
}

Response parameter description

Param Type Desc
orderId String order ID
cashierId String Cashier ID
orderType int64 Order Type 1 - Collection
orderResourceType int64 Business type 1 to which the order belongs - encryption order
userId String order originator
orderStatus int64 Order Status 1-Pending payment
2- Confirming on the chain
4- Completed
8- The payment amount does not match
16- Received overtime
32- Unpaid
orderTime int64 Order initiation time
channelOrderId String Order associated channel order id
externalOrderId String Merchant order ID
orderAmount String order amount
orderActualAmount String The actual payment or deducted amount of the order
orderFee String Order handling fee
currencyType String Fiat currency type
tokenType String token type
chainType String main chain type
exchangeRate String Exchange rate at the time of order generation
addressTo String Receiving address
tradeHash String chain hash
orderTypeCode String order type code
orderResourceTypeCode String Description of the business type to which the order belongs
orderStatusCode String Order Status Description

# 5.6 Query the balance of the payment wallet address

request method

post

Request URL

/api/v3/wallet/query/address

Request type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

{
    "address":"TYpFF2AjK82tcXEiJCwR2FPWsPPyaSiGQB"
}

Description of request parameters

Param Desc Require
address address (String) required

response type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

response data

{
    "code": "200",
    "success": true,
    "msg": "成功",
    "msgEn": "SUCCESS",
    "data": {
        "walletAddress": "TYpFF2AjK82tcXEiJCwR2FPWsPPyaSiGQB",
        "merchant": "[email protected]",
        "userFlagId": "WSXTES2",
        "chainName": "TRON",
        "amount": 20.4912,
        "tokenList": [
            {
                "tokenName": "USDT",
                "tokenAmount": 40
            },
            {
                "tokenName": "TUSD",
                "tokenAmount": 0
            },
            {
                "tokenName": "USDC",
                "tokenAmount": 0
            }
        ]
    }
}

Response parameter description

Param Type Desc
walletAddress String Wallet address
merchant String Merchant
userFlagId String User Unique Identification
chainName String Chain Name
amount float64 Local Currency Amount
tokenName String Token Name
tokenAmount float64 Token amount

# 5.7 Querying the Payment Wallet Address and Callback Order Status

request method

post

Request URL

/api/v3/wallet/query/notifystatus

Request type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

{
  "address": "TKWHPtoVuSvPC6tnVhQc8QVt4hcLiYLarg",
  "startTime": "2024-03-31T16:00:00Z",
  "endTime": "2024-04-09T15:59:59Z",
  "state":1,
  "page":1,
  "size":10  
}

Description of request parameters

Param Desc Require
addressTo Receiving address（String） required
startTime start time （String）The time zone is UTC required
endTime end time（String）The time zone is UTC required
state Callback status oneof=0 1（Int64）0 is a success, 1 is a failure required
page page（Int64） omitempty
size size（Int64） omitempty

response type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

response data

{
    "code": "200",
    "success": true,
    "msg": "成功",
    "msgEn": "SUCCESS",
    "data": [
        {
            "orderId": "OCRYPPAID202311060927381699262858736DEV001OO0000000400001140",
            "cashierId": "",
            "orderType": 1,
            "orderResourceType": 1,
            "userId": "1719629264270237698",
            "orderStatus": 4,
            "orderTime": 1699262859000,
            "channelOrderId": "",
            "externalOrderId": "",
            "orderAmount": "250",
            "orderActualAmount": "250",
            "orderPayTime": 1699262859000,
            "currencyType": "USD",
            "tokenType": "USDT",
            "chainType": "TRON",
            "exchangeRate": "0.991",
            "addressFrom": "TNsGPpkaaMZX9GgUrk6FiGdAf94z9co2PA",
            "addressTo": "TKWHPtoVuSvPC6tnVhQc8QVt4hcLiYLarg",
            "tradeHash": "18d7c6e333b4d889b9029d3838d76390c8ed82256467a84be19b9a4a954a357e",
            "errorMsg": "帳戶餘額不足",
            "orderTypeCode": "Pay",
            "orderResourceTypeCode": "Crypto",
            "orderStatusCode": "Completed"
        },
        {
            "orderId": "OCRYPPAID202311060914331699262073877DEV001OO0000000400001137",
            "cashierId": "",
            "orderType": 1,
            "orderResourceType": 1,
            "userId": "1719629264270237698",
            "orderStatus": 4,
            "orderTime": 1699262074000,
            "channelOrderId": "",
            "externalOrderId": "",
            "orderAmount": "250",
            "orderActualAmount": "250",
            "orderFee": "225",
            "orderPayTime": 1699262074000,
            "currencyType": "USD",
            "tokenType": "USDT",
            "chainType": "TRON",
            "exchangeRate": "0.991",
            "addressFrom": "TNsGPpkaaMZX9GgUrk6FiGdAf94z9co2PA",
            "addressTo": "TKWHPtoVuSvPC6tnVhQc8QVt4hcLiYLarg",
            "tradeHash": "8df54a0a6183976683ae579222bf84a4363c94158e833eafe1ea2e5be740c97b",
            "orderTypeCode": "Pay",
            "orderResourceTypeCode": "Crypto",
            "orderStatusCode": "Completed"
        }
    ]
}

Response parameter description

Param Type Desc
orderId String order ID
cashierId String Cashier ID
orderType int64 Order Type 1 - Collection
orderResourceType int64 Business type 1 to which the order belongs - encryption order
userId String order originator
orderStatus int64 Order Status 1-Pending payment
2- Confirming on the chain
4- Completed
8- The payment amount does not match
16- Received overtime
32- Unpaid
orderTime int64 Order initiation time
channelOrderId String Order associated channel order id
externalOrderId String Merchant order ID
orderAmount String order amount
orderActualAmount String The actual payment or deducted amount of the order
orderFee String Order handling fee
currencyType String Fiat currency type
tokenType String token type
chainType String main chain type
exchangeRate String Exchange rate at the time of order generation
addressTo String Receiving address
tradeHash String chain hash
orderTypeCode String order type code
orderResourceTypeCode String Description of the business type to which the order belongs
orderStatusCode String Order Status Description

# 5.8 Add new transfer order

request method

post

Request URL

/api/v3/wallet/transfer

Request type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

{
	"externalOrderId": "622257420681202921",
	"addressTo": "0xa8666442fA7583F783a169CC9F5449ec660295E8",
	"chainType": "ETH",
	"tokenType": "USDT",
    "currencyType":"USD",
	"cryptoAmount": "1",
	"notifyUrl": "http://192.168.1.135:30002/url",
	"remark": "http://192.168.1.135:30002/url"
}

Description of request parameters

Param Desc Require
externalOrderId Merchant order ID Max=64 (String) required
addressTo Receiving address Max=64 (String) required
chainType Cryptocurrency main chain type ETH TRON BSC (String) required
tokenType Order encrypted token type USDT USDC TUSD BUSD (String) required
cryptoAmount Encrypted amount, no more than 6 digits after the decimal point (String) Select based on actual service conditions optional
currencyType Order currencyType oneof=USD BRL CNY（String）Select based on actual service conditions optional
currencyAmount Order currencyAmount ，The decimal point cannot be greater than 2 places（String） Select based on actual service conditions optional
notifyUrl callback URL (String, url) optional
remark Remarks (String) optional

response type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

response data

{
    "code": "200",
    "success": true,
    "msg" : "Success" ,
    "msgEn": "SUCCESS",
    "data": {
        "orderId": "OCRYPDRAW202307310902401690794160841DOCKER020000000200001109",
        "orderStatus": "Accepted",
        "addressTo": "0xa8666442fA7583F783a169CC9F5449ec660295E8",
        "chainType": "ETH",
        "tokenType": "USDT",
        "tokenAmount": 1,
        "externalOrderId": "622257420681202921"
    }
}

Response parameter description

Param Type Desc
orderId String order ID
orderStatus String Order Status
addressTo String Receiving address
chainType String Encrypted main chain type
tokenType String Crypto Token Type
tokenAmount float64 Ghostwriting amount
externalOrderId String Merchant order ID

# 5.9 Query transfer orders

request method

post

Request URL

/api/v3/wallet/query/transfer

Request type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

{
    "externalOrderId": "622257420681202921",
    "orderId": "OCRYPDRAW202307310902401690794160841DOCKER020000000200001109"
}

Description of request parameters

Param Desc Require
externalOrderId Merchant order number max=64 (String) required
orderId system order number (String) required

response type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

response data

{
    "code": "200",
    "success": true,
    "msg" : "Success" ,
    "msgEn": "SUCCESS",
    "data": [{
        "orderId": "OCRYPDRAW202307310902401690794160841DOCKER020000000200001109",
        "cashierId": "",
        "orderType": 2,
        "orderResourceType": 1,
        "userId": "1663371399710216194",
        "orderStatus": 1,
        "orderTime": 1690794160000,
        "channelOrderId": "",
        "externalOrderId": "622257420681202921",
        "orderAmount": "1",
        "orderActualAmount": "1.01",
        "orderFee": "0.01",
        "currencyType": "USD",
        "tokenType": "USDT",
        "chainType": "ETH",
        "exchangeRate": "0.983",
        "addressTo": "0xa8666442fA7583F783a169CC9F5449ec660295E8",
        "tradeHash" : "0xe9d043c9cbdb96ed7a71c5a0923baabe9e23316b3f1b0a01975bcd6d69b41fa3" ,
        "orderTypeCode": "Transfer",
        "orderResourceTypeCode": "Crypto",
        "orderStatusCode": "Accepted"
    }]
}

Response parameter description

Param Type Desc
orderId String order ID
cashierId String Cashier ID
orderType int64 Order Type 2 - Pay on behalf
orderResourceType int64 Business type 1 to which the order belongs - encryption order
userId String order originator
orderStatus int64 Order Status 1- Accepted
2- Completed
4- Payment failed
8- Pending approval
16- Payment rejected
orderTime int64 Order initiation time
channelOrderId String Order associated channel order id
externalOrderId String Merchant order ID
orderAmount String order amount
orderActualAmount String The actual payment or deducted amount of the order
orderFee String Order handling fee
currencyType String Fiat currency type
tokenType String token type
chainType String main chain type
exchangeRate String Exchange rate at the time of order generation
addressTo String Receiving address
tradeHash String chain hash
orderTypeCode String order type code
orderResourceTypeCode String Description of the business type to which the order belongs
orderStatusCode String Order Status Description

# 5.10 Query balance

request method

GET

Request URL

/api/v3/wallet/query/balance

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign computed signature kAXyh+eerqrefyaF8dyFB0M4FVo=

response data

{
	"code": "200",
	"success": true,
	"msg": "成功",
	"msgEn": "SUCCESS",
	"data": [{
		"accountStatusId": 4,
		"accountBalance": "346.525",
		"accountFreezeAmount": "0",
		"accountWaitSettledAmount": "0",
		"chainType": "ETH",
		"tokenType": "USDT",
		"AccountStatus": "InAndOut"
	}, {
		"accountStatusId": 4,
		"accountBalance": "479.938888",
		"accountFreezeAmount": "0",
		"accountWaitSettledAmount": "0",
		"chainType": "TRON",
		"tokenType": "USDT",
		"AccountStatus": "InAndOut"
	}, {
		"accountStatusId": 4,
		"accountBalance": "0",
		"accountFreezeAmount": "0",
		"accountWaitSettledAmount": "0",
		"chainType": "BSC",
		"tokenType": "USDT",
		"AccountStatus": "InAndOut"
	}, {
		"accountStatusId": 4,
		"accountBalance": "0",
		"accountFreezeAmount": "0",
		"accountWaitSettledAmount": "0",
		"chainType": "ETH",
		"tokenType": "BUSD",
		"AccountStatus": "InAndOut"
	}, {
		"accountStatusId": 4,
		"accountBalance": "0",
		"accountFreezeAmount": "0",
		"accountWaitSettledAmount": "0",
		"chainType": "BSC",
		"tokenType": "BUSD",
		"AccountStatus": "InAndOut"
	}, {
		"accountStatusId": 4,
		"accountBalance": "0",
		"accountFreezeAmount": "0",
		"accountWaitSettledAmount": "0",
		"chainType": "ETH",
		"tokenType": "TUSD",
		"AccountStatus": "InAndOut"
	}, {
		"accountStatusId": 4,
		"accountBalance": "0",
		"accountFreezeAmount": "0",
		"accountWaitSettledAmount": "0",
		"chainType": "TRON",
		"tokenType": "TUSD",
		"AccountStatus": "InAndOut"
	}, {
		"accountStatusId": 4,
		"accountBalance": "0",
		"accountFreezeAmount": "0",
		"accountWaitSettledAmount": "0",
		"chainType": "BSC",
		"tokenType": "TUSD",
		"AccountStatus": "InAndOut"
	}, {
		"accountStatusId": 4,
		"accountBalance": "0",
		"accountFreezeAmount": "0",
		"accountWaitSettledAmount": "0",
		"chainType": "ETH",
		"tokenType": "USDC",
		"AccountStatus": "InAndOut"
	}, {
		"accountStatusId": 4,
		"accountBalance": "0",
		"accountFreezeAmount": "0",
		"accountWaitSettledAmount": "0",
		"chainType": "TRON",
		"tokenType": "USDC",
		"AccountStatus": "InAndOut"
	}, {
		"accountStatusId": 4,
		"accountBalance": "0",
		"accountFreezeAmount": "0",
		"accountWaitSettledAmount": "0",
		"chainType": "BSC",
		"tokenType": "USDC",
		"AccountStatus": "InAndOut"
	}]
}

Response parameter description

Param Type Desc
accountStatusId int64 账户状态id
accountBalance String 账户可用余额
accountFreezeAmount String 账户冻结金额
accountWaitSettledAmount String 账户待划转金额
chainType String 主链类型
tokenType String 代币类型
AccountStatus String 账户状态

# 5.11 Query orders through hash

request method

post

Request URL

/api/v3/wallet/query/ordertoHash

Request type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

request header

Param Desc Sample
access_key Acquisition from merchant background pFqV75X3
timestamp Unix timestamp 13 digits milliseconds 1679724896223
nonce UUID V4 794c26b0-d33c-4394-b2bb-c485eca16d9e
sign Calculated signature kAXyh+eerqrefyaF8dyFB0M4FVo=

request parameters

{
    "tradeHash": "5e1fdbb146c02bf0042dae6e9e15c3fc556bddf93e63ab64f1b5b9a3c456813f",
    "startTime": "2024-03-31T16:00:00Z",
    "endTime": "2024-04-09T15:59:59Z"
}

Description of request parameters

Param Desc Require
addressTo Receiving address（String） required
startTime start time （String）The time zone is UTC required
endTime end time（String）The time zone is UTC required

response type

Header: { 'Content-Type': 'application/json;charset=utf-8'}

response data

{
    "code":"200",
    "success":true,
    "msg":"成功",
    "msgEn":"SUCCESS",
    "data":[
            {
            "orderId":"OCRYPPAID202404080144071712540647531DEV001OO0000000400014827",
            "cashierId":"OCRYPPAID202404080144071712540647455DEV001OO0000000200014826",
            "orderType":1,
            "orderResourceType":1,
            "userId":"1707285840326127617",
            "orderStatus":4,
            "orderTime":1712540648000,
            "channelOrderId":"",
            "externalOrderId":"69511350",
            "orderAmount":"20",
            "orderActualAmount":"20",
            "orderEntryAmount":"6.9982",
            "orderFee":"13.0018",
            "orderPayTime":1712540727000,
            "orderCompleteTime":1712540727000,
            "currencyType":"USD",
            "tokenType":"USDT",
            "chainType":"TRON",
            "exchangeRate":"0.995",
            "addressFrom":"TNsGPpkaaMZX9GgUrk6FiGdAf94z9co2PA",
            "addressTo":"TGa3cWX6FzsJKKV9JYhFG5Q4NM2FwKuAWA",
            "tradeHash":"5e1fdbb146c02bf0042dae6e9e15c3fc556bddf93e63ab64f1b5b9a3c456813f",
            "orderTypeCode":"Pay",
            "orderResourceTypeCode":"Crypto",
            "orderStatusCode":"Completed"
            }
		]
}

Response parameter description

Param Type Desc
orderId String order ID
cashierId String Cashier ID
orderType int64 Order Type 1 - Collection
orderResourceType int64 Business type 1 to which the order belongs - encryption order
userId String order originator
orderStatus int64 Order Status 1-Pending payment
2- Confirming on the chain
4- Completed
8- The payment amount does not match
16- Received overtime
32- Unpaid
orderTime int64 Order initiation time
channelOrderId String Order associated channel order id
externalOrderId String Merchant order ID
orderAmount String order amount
orderActualAmount String The actual payment or deducted amount of the order
orderFee String Order handling fee
currencyType String Fiat currency type
tokenType String token type
chainType String main chain type
exchangeRate String Exchange rate at the time of order generation
addressTo String Receiving address
tradeHash String chain hash
orderTypeCode String order type code
orderResourceTypeCode String Description of the business type to which the order belongs
orderStatusCode String Order Status Description

# 6. callback information

# 6.1 How to call back interface check

# Signature verification instructions

​ API requests are likely to be tampered with during transmission over the internet. To ensure that callbacks have not been changed, you can set callback parameter signature authentication. The setting method is: log in to the cashier -> developer center -> callback address -> add.

# Signature verification steps

The overall process is roughly the same as the signature, except that the data used to verify the signature is different. The signature is to construct the data by itself, and the signature is to obtain the data (header, json)

  1. Take out the sign value in the header;

  2. Define a Map dictionary type object, put the json parameters in the request in the form of key-value

  3. Take out the access_key, timestamp, and nonce in the header and put them into the Map defined in the previous step

  4. Sort the keys in the Map according to the ASCII code from small to large (lexicographic order) and convert the Map into a string in the form of "key1=value1&key2=value2";

  5. Use the secret_key to encrypt the character string converted in the previous step with HMAC_SHA1 and perform Base64 transcoding to obtain the signed value and the sign extracted from the header in the first step for string verification. If they match, the signature verification will pass, otherwise, the signature verification will fail. The secret_key here needs to match the access_key when placing an order.

# 6.2 payment callback

callback data

{
    "currencyType": "USD",
    "orderActualAmount": "1",
    "orderId": "OCRYPPAID202307310902391690794159441DOCKER020000000400001108",
    "tradeHash": "0x806d5b3da29c8426a644e2ded85b865b37504dcdec4cfb9db13af5e962815528",
    "orderFee": "1",
    "orderStatus": "Completed",
    "chainType": "ETH",
    "externalOrderId": "402297358314559082",
    "addressTo": "0xe072c63c1e04f8c6f36133f6629f66778147d5d8",
    "orderAmount": "1",
    "orderTime": 1690794159000,
    "exchangeRate": "0.983",
    "orderStatusCode": 4,
    "orderPayTime" : 1690794247000 ,
    "addressFrom": "0x0cbfd17ae9e1d6d881b2cade71277f48abf64d24",
    "tokenType": "USDT"
}

Callback parameter description

Param Type Desc
currencyType String Fiat currency type
orderActualAmount String The actual payment amount of the order
orderId String order ID
tradeHash String chain hash
orderFee String Order handling fee
orderStatus String Order status code description
chainType String main chain type
externalOrderId String Merchant order ID
addressTo String Receiving address
orderAmount String order amount
orderTime int64 Order creation time
exchangeRate String Exchange rate at the time of order generation
orderStatusCode int64 Order status code
1- Pending payment: After the order is successfully created, it waits for the user to make payment, which is not the final status of the order and does not need to be processed;
2- On chain confirmation: The user has clicked the mark on the checkout page and completed the process. However, on chain confirmation is still required to confirm whether the payment has been received, which is not the final status of the order and does not require further processing;
4- Completed: The system will automatically call back a notification. After receiving the notification, you need to increase the balance/credit for your users according to the actual business;
8- Payment amount mismatch: The system will issue a normal callback notification, and the customer needs to increase their balance/credit based on the actual payment amount after receiving the notification;
16- Overdue collection: The system will not make a callback, and customers need to manually increase their balance/credit according to the amount;
32- Unpaid: If the payment has not been made within 2 hours and the address has been released, making another payment will generate a new overdue payment order, and the original order status will remain unchanged;
orderPayTime int64 order payment time
addressFrom String payment address
tokenType String token type

At any time, the merchant can log in to the backstage of the merchant to manually trigger the callback (it is not recommended to initiate a manual callback if the order is not final), and the relevant information such as the order status in the callback information is the actual status (manualPlease pay attention to the order status when calling back. If the status of the manual callback order is not final, the platform will still initiate a notification when the order becomes final. Please pay attention to redundant processing at the business level)

# 6.3 Transfer callback

callback data

{
    "orderAmount": "1",
    "orderTime": 1690794160000,
    "orderId": "OCRYPDRAW202307310902401690794160841DOCKER020000000200001109",
    "orderStatusCode": 2,
    "tradeHash" : "0xe9d043c9cbdb96ed7a71c5a0923baabe9e23316b3f1b0a01975bcd6d69b41fa3" ,
    "orderFee": "0.01",
    "orderStatus": "Completed",
    "orderPayTime" : 1690794182000 ,
    "chainType": "ETH",
    "externalOrderId": "622257420681202921",
    "tokenType": "USDT",
    "addressTo": "0xa8666442fA7583F783a169CC9F5449ec660295E8"
}

Callback parameter description

Param Type Desc
orderAmount String order amount
orderTime int64 Order creation time
orderId String order ID
orderStatusCode int64 Order status code 1- Accepted
2- Completed
4- Payment failed
8- Pending approval
16- Rejected payment
tradeHash String chain hash
orderFee String Order handling fee
orderStatus String Order Status Description
orderPayTime int64 Order payment time
chainType String main chain type
externalOrderId int64 Merchant order ID
tokenType int64 token type
tokenType String token type
addressTo String Receiving address

At any time, the merchant can log in to the backstage of the merchant to manually trigger the callback (it is not recommended to initiate a manual callback if the order is not final), and the relevant information such as the order status in the callback information is the actual status (manualPlease pay attention to the order status when calling back. If the status of the manual callback order is not final, the platform will still initiate a notification when the order becomes final. Please pay attention to redundant processing at the business level)

# 6.4 Callback response

Remarks: All callbacks include signature information. It is recommended that merchants do a callback signature verification. After receiving the callback information, the merchant will determine the final status of the order. Please respond to the following information from the gateway (content-type: application/json) if there is no normal response The server will send a total of 2 notifications within 30 minutes at intervals of three minutes

{"code":200,"success":true}

# 6.5 Callback notification URL

*** Log in to the backstage of the merchant to configure the unified callback address (manually specify the callback URL address in the order, which has a higher priority than the uniformly configured callback address. For example, if the notifyUrl parameter is specified in the order, it will be used regardless of whether there is a unified configuration of the callback notification address. notifyUrl address in the order)***

Note that the http response status_code has the highest priority, as long as the response status_code=200 is received, the response data will be ignored

# 7. Public response code

filed Type Default value and comment
code String Success "200" For others, please refer to failure code
success Bool success true, failure false, and code to keep the meaning of synchronization
msg String The textual description returned by the first-level code
data Object Reference interface list chapter

# 8. Failure code

Code Desc
200 Normal
300 Parameter exception
301 IP Unauthorized
307 Signature error
500 System Error