# 地址充值通知
Source: https://developer-cn.cregis.com/api-reference/callback/address-deposit
获取地址充值信息通知
## 回调 API
回调URL由对应业务发起方传入，具体了解[生成地址](/api-reference/request-apis/address/address-generate)接口中的`callback_url`参数
该接口为`Cregis`向业务方发起回调通知请求，该回调分两种情况，根据回调内容中的`status`判断，且两种情况是互斥的，只会产生一次回调：
| 状态(status) | 描述 |
| ---------- | -------- |
| 1 | 充值交易成功回调 |
| 2 | 充值交易失败回调 |
发起回调后当接收到返回内容为`success`字符串时为回调成功，否则为回调失败，回调失败可以进行重新推送，可登录`Cregis`客户端，在项目菜单中选择对应项目，在回调记录菜单中重新推送。
> 不同类型的业务，回调内容不同，强烈建议使用不同的接口接收回调，保证业务逻辑的清晰明确。
#### 请求方式
HTTP POST
application/json
#### 请求参数
| 名称 | 类型 | 描述 |
| ------------- | -------------- | ------------------------ |
| pid | integer(int64) | 项目编号 |
| cid | integer(int64) | 系统流水号 |
| chain\_id | string | 链编号 |
| token\_id | string | 代币编号 |
| currency | string | 币种标识 |
| address | string | 地址 |
| amount | string | 金额 |
| status | string | 状态 |
| txid | string | 交易hash |
| block\_height | string | 区块高度 |
| block\_time | string | 区块时间 |
| memo | string | memo、tag等上链信息，仅Ton、Xrp支持 |
| nonce | string | 6位随机字符串 |
| timestamp | integer(int64) | 时间戳 |
| sign | string | 签名 |
###### 示例
```json theme={null}
{
"pid": 1382528827416576,
"cid": 1391751691788288,
"chain_id":"195",
"token_id":"195",
"currency": "TRX",
"amount": "1.2",
"address":"TXsmKpEuW7qWnXzJLGP9eDLvWPR2GRn1FS",
"status": "1",
"txid": "6dd05b0972075542219a3fcc116c58feaf9480f1f698cc46c4367ded83955cfd",
"block_height": "34527604",
"block_time": "1686814482000",
"nonce": "ubqso3",
"timestamp": 1687850657960,
"sign": "f5be13fdd8c6f63951ca4427359457cb"
}
```
# 订单支付通知
Source: https://developer-cn.cregis.com/api-reference/callback/payment-engine
获取订单支付信息的通知
## 回调 API
根据创建订单填写的callback\_url,当订单状态变化时会通过该回调地址通知调用方，具体了解[创建订单](/api-reference/request-apis/payment/payment-engine-create)接口中的`callback_url`参数
该接口为Cregis向业务方发起回调通知请求，只会产生一次回调：
#### 回调事件
| 回调事件名称(event\_name) | 回调事件类型(event\_type) | 描述 |
| ------------------- | ------------------- | -------- |
| order | expired | 订单超时通知 |
| order | paid | 订单支付完成通知 |
| order | paid\_partial | 订单部分支付通知 |
| order | paid\_over | 订单超额支付通知 |
| order | refunded | 订单退款通知 |
| order | paid\_remain | 订单补款通知 |
#### 请求方式
HTTP POST application/json
发起回调请求后当接收到返回内容为`success`字符串时为回调成功，否则为回调失败
#### 请求参数
| 名称 | 类型 | 描述 |
| ----------- | -------------- | ------- |
| event\_name | string | 事件名称 |
| event\_type | string | 事件类型 |
| data | JSONString | 订单信息 |
| pid | integer(int64) | 项目编号 |
| nonce | string | 6位随机字符串 |
| timestamp | integer(int64) | 时间戳 |
| sign | string | 签名 |
#### 支付订单 `data` 对象
| 名称 | 类型 | 描述 |
| ----------------- | -------------- | ------------------------------------------------------------------------------------------------------- |
| cregis\_id | string | cregis订单编号 |
| order\_id | string | 订单编号 |
| receive\_amount | string | 汇率转换后的订单金额 |
| receive\_currency | string | 汇率转换后的订单货币单位 |
| pay\_amount | string | 实际到账金额 |
| pay\_currency | string | 到账货币单位 |
| order\_amount | string | 订单交易金额 |
| order\_currency | string | 订单货币代码，即ISO 4217货币代码,例如 CNY、HKD，请参考[订单货币列表](/api-reference/request-apis/payment/payment-order-currency) |
| exchange\_rate | string | 货币汇率 |
| payment\_address | string | 充值地址 |
| created\_time | integer(int64) | 订单创建时间【13位时间戳】 |
| cancel\_time | integer(int64) | 订单取消时间【13位时间戳】 |
| transact\_time | integer(int64) | 订单支付完成时间【13位时间戳】 |
| valid\_time | integer | 订单超时时间【单位/分钟】 |
| status | string | 订单状态【new-待支付,paid-已支付，expired-订单超出有效时间，paid\_over-付款超出订单金额 paid\_partial-付款小于订单金额】 |
| remark | string | 订单备注信息 |
| tx\_id | string | 交易hash |
| payer\_id | string | 付款人id标识 |
| payer\_name | string | 付款人姓名 |
| payer\_email | string | 付款人邮箱 |
#### 超时订单 `data` 对象
| 名称 | 类型 | 描述 |
| --------------- | -------------- | --------------------------------------------- |
| cregis\_id | string | cregis订单编号 |
| order\_id | string | 商户订单编号 |
| order\_amount | string | 订单交易金额 |
| order\_currency | string | 订单货币代码，即ISO 4217货币代码,例如 CNY、HKD，参考法币信息列表接口 |
| created\_time | integer(int64) | 订单创建时间【13位时间戳】 |
| cancel\_time | integer(int64) | 订单取消时间【13位时间戳】 |
| valid\_time | integer | 订单超时时间【单位/分钟】 |
| status | string | 订单状态【new -待支付 paid-被调用方收到付款 expired-订单超出有效时间】 |
| remark | string | 订单备注信息 |
| payer\_id | string | 付款人id标识 |
| payer\_name | string | 付款人姓名 |
| payer\_email | string | 付款人邮箱 |
#### 订单退款 `data` 对象
| 名称 | 类型 | 描述 |
| ---------------------- | -------------- | ---------------------------------------------------------------------- |
| cregis\_id | string | cregis订单编号 |
| order\_id | string | 订单编号 |
| receive\_amount | string | 汇率转换后的订单金额 |
| receive\_currency | string | 汇率转换后的订单货币单位 |
| pay\_amount | string | 实际到账金额 |
| pay\_currency | string | 到账货币单位 |
| order\_amount | string | 订单交易金额 |
| order\_currency | string | 订单货币代码，即ISO 4217货币代码,例如 CNY、HKD，参考法币信息列表接口 |
| exchange\_rate | string | 货币汇率 |
| payment\_address | string | 充值地址 |
| created\_time | integer(int64) | 订单创建时间【13位时间戳】 |
| cancel\_time | integer(int64) | 订单取消时间 【13位时间戳】 |
| transact\_time | integer(int64) | 订单支付完成时间 【13位时间戳】 |
| valid\_time | integer | 订单超时时间【单位/分钟】 |
| status | string | 订单状态【new -待支付 paid-被调用方收到付款 expired-订单超出有效时间】 |
| remark | string | 订单备注信息 |
| tx\_id | string | 交易哈希 |
| payer\_id | string | 付款人id标识 |
| payer\_name | string | 付款人姓名 |
| payer\_email | string | 付款人邮箱 |
| refund\_requested | string | 订单是否发生了退款
no：无退款记录
yes：有退款记录 |
| type | string | 0: 部分退款
1: 全额退款 |
| refund\_id | long | Cregis退款订单编号 |
| refund\_address | string | 退款收款人的链上地址 |
| refund\_currency | string | 退款订单的币种填入加密货币token\_name，格式：USDT-BEP20，USDT-TRC20 |
| refund\_amount | string | 退款金额 |
| refund\_fee | | 退款所需gas fee |
| actual\_refund\_amount | | 扣减矿工费后的实际退款金额 = 退款订单金额amount-gas\_fee\_amount |
| refund\_status | string | 退款状态
0: 退款处理中
1：退款成功
2：退款失败 |
| refund\_tx\_id | string | 退款交易哈希 |
| refund\_created\_time | string | 退款订单创建时间【13位时间戳】
e.g. 1720508269092 即 2024-07-09 14:57:49 092 |
| refund\_transact\_time | string | 退款订单最后更新时间【13位时间戳】
e.g. 1720508269092 即 2024-07-09 14:57:49 092 |
#### 订单补款 `data` 对象
| 名称 | 类型 | 描述 |
| ---------------------------- | -------------- | --------------------------------------------- |
| cregis\_id | string | cregis订单编号 |
| order\_id | string | 订单编号 |
| receive\_amount | string | 汇率转换后的订单金额 |
| receive\_currency | string | 汇率转换后的订单货币单位 |
| pay\_amount | string | 实际到账金额 |
| pay\_currency | string | 到账货币单位 |
| order\_amount | string | 订单交易金额 |
| order\_currency | string | 订单货币代码，即ISO 4217货币代码,例如 CNY、HKD，参考法币信息列表接口 |
| exchange\_rate | string | 货币汇率 |
| payment\_address | string | 充值地址 |
| created\_time | integer(int64) | 订单创建时间【13位时间戳】 |
| cancel\_time | integer(int64) | 订单取消时间 【13位时间戳】 |
| transact\_time | integer(int64) | 订单支付完成时间 【13位时间戳】 |
| valid\_time | integer | 订单超时时间【单位/分钟】 |
| status | string | 订单状态【new -待支付 paid-被调用方收到付款 expired-订单超出有效时间】 |
| remark | string | 订单备注信息 |
| tx\_id | string | 交易哈希 |
| payer\_id | string | 付款人id标识 |
| payer\_name | string | 付款人姓名 |
| payer\_email | string | 付款人邮箱 |
| additional\_pay\_currency | string | 补款货币单位 |
| additional\_pay\_amount | string | 补款金额 |
| additional\_payment\_address | string | 补款地址 |
| additional\_payment\_tx\_id | string | 补款交易hash |
| additional\_payment\_tx\_id | integer(int64) | 补款订单支付完成时间 【13位时间戳】 |
###### 请求示例
```json theme={null}
{
"event_name": "order",
"event_type": "paid",
"data": {
"cregis_id": "po20240703132452000",
"order_id": "c9231e604da54469a735af3f449c880f",
"receive_amount": "12.86",
"receive_currency": "USDT",
"pay_amount": "12.86",
"pay_currency": "USDT",
"order_amount": "100",
"order_currency": "HKD",
"exchange_rate": "0.1286",
"payment_address": "0xd38c2cf366a731dcbe4a32c7ef24ff96d080ca7e",
"created_time": 1719993183015,
"cancel_time": null,
"transact_time": 1719993183325,
"valid_time": 30,
"status": "paid",
"payer_id": "p_001",
"payer_name": "",
"payer_email": "test@mail.com"
"remark":"购买商品",
"tx_id": "0x0502f2bfd96cd0f55edea3343513940f3af7fe594eae77f08d2f46ea24829b11"
}
}
```
# 钱包提币通知
Source: https://developer-cn.cregis.com/api-reference/callback/payout
获取钱包提币信息的通知
## 回调 API
回调URL由对应业务发起方传入，具体了解[提币](/api-reference/request-apis/payout/payout-create)接口中的`callback_url`参数
该接口为`Cregis`向业务发发起回调通知请求，该回调分四种情况，根据回调内容中的`status`判断，且四种情况是互斥的，只会产生一次回调：
| 状态(status) | 描述 |
| ---------- | ---- |
| 2 | 签名驳回 |
| 4 | 审批驳回 |
| 6 | 交易成功 |
| 7 | 交易失败 |
发起回调后当接收到返回内容为`success`字符串时为回调成功，否则为回调失败，回调失败可以进行重新推送，可登录`Cregis`客户端，在项目菜单中选择对应项目，在回调记录菜单中重新推送。
> 不同类型的业务，回调内容不同，强烈建议使用不同的接口接收回调，保证业务逻辑的清晰明确。
#### 请求方式
HTTP POST application/json
#### 请求参数
| 名称 | 类型 | 描述 |
| ---------------- | -------------- | ------------------------ |
| pid | integer(int64) | 项目编号 |
| cid | integer(int64) | 系统流水号 |
| chain\_id | string | 链编号 |
| token\_id | string | 代币编号 |
| currency | string | 币种标识 |
| address | string | 地址 |
| amount | string | 金额 |
| third\_party\_id | string | 调用方业务编号D |
| remark | string | 备注 |
| status | integer(int32) | 状态 |
| txid | string | 交易hash |
| block\_height | string | 区块高度 |
| block\_time | integer(int64) | 区块时间 |
| memo | string | memo、tag等上链信息，仅Ton、Xrp支持 |
| nonce | string | 6位随机字符串 |
| timestamp | integer(int64) | 时间戳 |
| sign | string | 签名 |
###### 示例
```json theme={null}
{
"pid": 1382528827416576,
"cid": 1391751691788288,
"address": "TXsmKpEuW7qWnXzJLGP9eDLvWPR2GRn1FS",
"chain_id": "195",
"token_id": "195",
"currency": "TRX",
"amount": "1.1",
"third_party_id": "1e0fb3a0a9454ad8928d26b592e8b3c7",
"remark": "payout",
"status": 0,
"txid": "6dd05b0972075542219a3fcc116c58feaf9480f1f698cc46c4367ded83955cfd",
"block_height": "34527604",
"block_time": 1686814482000,
"nonce": "ubqso3",
"timestamp": 1687850657960,
"sign": "f5be13fdd8c6f63951ca4427359457cb"
}
```
# 子地址提币通知
Source: https://developer-cn.cregis.com/api-reference/callback/withdrawal
获取子地址提币信息的通知
## 回调 API
回调URL由对应业务发起方传入，具体了解[提币](/api-reference/request-apis/withdrawal/withdrawal-create)接口中的`callback_url`参数
该接口为`Cregis`向业务发发起回调通知请求，该回调分四种情况，根据回调内容中的`status`判断，且四种情况是互斥的，只会产生一次回调：
| 状态(status) | 描述 |
| ---------- | ---- |
| 2 | 签名驳回 |
| 4 | 审批驳回 |
| 6 | 交易成功 |
| 7 | 交易失败 |
发起回调后当接收到返回内容为`success`字符串时为回调成功，否则为回调失败，回调失败可以进行重新推送，可登录`Cregis`客户端，在项目菜单中选择对应项目，在回调记录菜单中重新推送。
> 不同类型的业务，回调内容不同，强烈建议使用不同的接口接收回调，保证业务逻辑的清晰明确。
#### 请求方式
HTTP POST application/json
#### 请求参数
| 名称 | 类型 | 描述 |
| ---------------- | -------------- | ------------------------ |
| pid | integer(int64) | 项目编号 |
| cid | integer(int64) | 系统流水号 |
| chain\_id | string | 链编号 |
| token\_id | string | 代币编号 |
| currency | string | 币种标识 |
| from\_address | string | 发送方地址 |
| to\_address | string | 接收方地址 |
| amount | string | 出款金额 |
| third\_party\_id | string | 调用方业务编号D |
| remark | string | 备注,不超过256位字符 |
| status | integer(int32) | 状态 |
| txid | string | 交易hash |
| block\_height | string | 区块高度 |
| block\_time | integer(int64) | 区块时间 |
| memo | string | memo、tag等上链信息，仅Ton、Xrp支持 |
| nonce | string | 6位随机字符串 |
| timestamp | integer(int64) | 时间戳 |
| sign | string | 签名 |
###### 示例
```json theme={null}
{
"pid": 1382528827416576,
"cid": 1391751691788288,
"from_address": "rhAZ673nG6fSXovPAkw3EcrhKyWwXducoi",
"to_address": "rn5Jyu5J6PG64543KdGvS25rQBYFQo7GLc",
"chain_id": "144",
"token_id": "144",
"currency": "XRP",
"amount": "1.1",
"third_party_id": "1e0fb3a0a9454ad8928d26b592e8b3c7",
"remark": "payout",
"memo": "123",
"status": 6,
"txid": "6dd05b0972075542219a3fcc116c58feaf9480f1f698cc46c4367ded83955cfd",
"block_height": "34527604",
"block_time": 1686814482000,
"nonce": "ubqso3",
"timestamp": 1687850657960,
"sign": "f5be13fdd8c6f63951ca4427359457cb"
}
```
# 币种码
Source: https://developer-cn.cregis.com/api-reference/currency-identifiers
## 格式
`currency`支持两种格式:
* 币种名称 (`name`).
* 链编号@币种编号 (`chain_id@token_id`).
## 举例
以下表格中前两个币种的`currency`参数分别为:
* `Ethereum` 或 `60@60`
* `USDT-ERC20` 或 `60@0xdac17f958d2ee523a2206206994597c13d831ec7`
## 币种编码列表
| 币种名称 | 链编号(chain\_id) | 币种编号(token\_id) | 币种精度 |
| ----------------- | -------------- | ------------------------------------------------- | ---- |
| Bitcoin | 0 | 0 | 8 |
| Ethereum | 60 | 60 | 18 |
| USDT-ERC20 | 60 | 0xdac17f958d2ee523a2206206994597c13d831ec7 | 6 |
| USDC-ERC20 | 60 | 0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48 | 6 |
| POL-ERC20 | 60 | 0x455e53cbb86018ac2b8092fdcd39d8444affc3f6 | 18 |
| Uniswap-ERC20 | 60 | 0x1f9840a85d5af5bf1d1762f925bdaddc4201f984 | 18 |
| ChainLink-ERC20 | 60 | 0x514910771af9ca656af840dff83e8264ecf986ca | 18 |
| SHIB-ERC20 | 60 | 0x95ad61b0a150d79219dcf64e1e6cc01f0b64c4ce | 18 |
| TRON | 195 | 195 | 6 |
| USDT-TRC20 | 195 | TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t | 6 |
| USDC-TRC20 | 195 | TEkxiTehnzSmSe2XqrBj4w32RUN966rdz8 | 6 |
| BNB-BSC | 2510 | 2510 | 18 |
| USDT-BEP20 | 2510 | 0x55d398326f99059ff775485246999027b3197955 | 18 |
| USDC-BEP20 | 2510 | 0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d | 18 |
| Dogecoin | 3 | 3 | 8 |
| Litecoin | 2 | 2 | 8 |
| Bitcoin Cash | 5 | 5 | 8 |
| POL-Polygon | 62 | 62 | 18 |
| USDT-Polygon | 62 | 0xc2132d05d31c914a87c6611c10748aeb04b58e8f | 6 |
| USDC-Polygon | 62 | 0x3c499c542cef5e3811e1192ce70d8cc03d5c3359 | 6 |
| Arbitrum One | 63 | 63 | 18 |
| USDT-Arbitrum One | 63 | 0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9 | 6 |
| USDC-Arbitrum One | 63 | 0xaf88d065e77c8cc2239327c5edb3a432268e5831 | 6 |
| Optimism | 64 | 64 | 18 |
| USDT-Optimism | 64 | 0x94b008aa00579c1307b0ef2c499ad98a8ce58e58 | 6 |
| USDC-Optimism | 64 | 0x0b2c639c533813f4aa9d7837caf62653d097ff85 | 6 |
| Avalanche-C | 65 | 65 | 18 |
| USDT-Avalanche-C | 65 | 0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c7 | 6 |
| USDC-Avalanche-C | 65 | 0xb97ef9ef8734c71904d8002f8b6bc66dd9c48a6e | 6 |
| Base | 66 | 66 | 18 |
| USDT-Base | 66 | 0xfde4c96c8593536e31f229ea8f37b2ada2699bb2 | 6 |
| USDC-Base | 66 | 0x833589fcd6edb6e08f4c7c32d4f71b54bda02913 | 6 |
| opBNB | 67 | 67 | 18 |
| Solana | 1000 | 1000 | 9 |
| USDT-Solana | 1000 | Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB | 6 |
| USDC-Solana | 1000 | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v | 6 |
| TON | 2000 | 2000 | 9 |
| USDT-Jetton | 2000 | EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id\_sDs | 6 |
| Ethereum Classic | 61 | 61 | 18 |
| Filecoin | 2307 | 2307 | 18 |
| XRP-Ripple | 144 | 144 | 6 |
| SUI | 3000 | 3000 | 9 |
# 请求说明
Source: https://developer-cn.cregis.com/api-reference/request
项目接口，目前只支持http post 一种请求方式，且指定的body Content-Type为: application/json。请特别注意，所有的请求参数通过body的json格式传递，其他传递参数的方式无效。
项目接口，接口参数分为两部分：系统参数和业务参数。
* **系统参数**: 每个 API 调用都需要系统参数
* **业务参数**: 特定于各个 API 调用或端点的参数
### 系统参数
| 参数 | 类型 | 描述 | 示例 | 是否必须 |
| --------- | ------ | -------------------------------------------------------------- | -------------------------------- | ---- |
| timestamp | long | 当前请求时间戳，单位毫秒 | 1687846491667 | 是 |
| nonce | string | 6 位随机字符串 | 24abxo | 是 |
| sign | string | 请求的数字签名，防止参数被非法篡改，签名规则参考以下 [签名规则](/api-reference/signature) 章节 | eb881023045a167d3e4a7378bc212f53 | 是 |
### 业务参数
除了以上三个参数外，其他参数是业务参数，以下是一个请求示例。
## 请求示例
### 客户端
**使用 Postman 示例:**
![]()
### curl
```
curl --location --request POST 'https://xx.xx.xx/api/v1/payout' \
--header 'Content-Type: application/json' \
--data-raw '{
"pid": 1394705669275648,
"currency": "195@195",
"address": "TXsmKpEuW7qWnXzJLGP9eDLvWPR2GRn1FS",
"amount": "0.1",
"remark": "payout",
"third_party_id": "1828fc39daaf4d318777e1211c055edf",
"callback_url": "http://xxx.com/payout/callback",
"nonce": "rR7ngZ",
"timestamp": 1709708726668,
"sign": "e95ba1a7e9bcadb92d9c3405a932715d"
}'
```
# 地址资金归集
Source: https://developer-cn.cregis.com/api-reference/request-apis/address/address-balance-collect
发起项目子地址归集请求
### 接入 API
POST /api/v1/collection
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| ------------- | -------------- | ---- | ---------------------------- |
| pid | integer(int64) | 是 | 项目编号 |
| currency | string | 是 | 查询的代币标识，chain\_id\@token\_id |
| from\_address | string | 是 | 需要归集的项目地址，地址禁用状态不允许归集 |
| to\_address | string | 是 | 归集接收地址，必须是当前项目地址绑定钱包中的地址 |
| amount | string | 否 | 归集金额，不传默认归集地址所有资金 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名串 |
###### 请求示例
```json theme={null}
{
"pid": 1382528827416576,
"currency": "195@195",
"from_address": "TJ6j9CosgGRxuVwuMFsxKwuqbUFaSd1SZr",
"to_address": "TFVjBSg1dzszYSyB1dNx4cQnxaD6bHYCE1",
"amount": "1.1",
"nonce": "hwlkk6",
"timestamp": 1688004243314,
"sign": "d6eef2de79e39f434a38efb910213ba6"
}
```
### 返回
#### 返回结果
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回信息 |
| data | object | 返回数据 |
#### 返回数据 `data` 对象
| 名称 | 类型 | 描述 |
| --- | -------------- | ------------ |
| cid | integer(int64) | Cregis 系统流水号 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"cid": 1382528827416576
}
}
```
# 查询地址余额
Source: https://developer-cn.cregis.com/api-reference/request-apis/address/address-balance-query
查询项目子地址余额
### 接入 API
POST /api/v1/sub\_address\_balance
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| ---------------- | -------------- | ---- | ---------------------------- |
| pid | integer(int64) | 是 | 项目编号 |
| currency | string | 是 | 查询的代币标识，chain\_id\@token\_id |
| address | string | 否 | 查询的子地址，不传则查询项目中所有有余额的地址 |
| maximum\_balance | string | 否 | 查询地址最大余额，包含 |
| minimum\_balance | string | 否 | 查询地址最小余额，包含 |
| page\_num | integer(int32) | 否 | 分页页数，如果不填，默认为1 |
| page\_size | integer(int32) | 否 | 分页每页数量，如果不填默认为10，限制最大值为100 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名串 |
###### 请求示例
```json theme={null}
{
"pid": 1382528827416576,
"address": "",
"currency": "195@195",
"minimum_balance":"1"
"maximum_balance":"10"
"page_num": 1,
"page_size": 10,
"nonce": "hwlkk6",
"timestamp": 1688004243314,
"sign": "d6eef2de79e39f434a38efb910213ba6"
}
```
### 返回
#### 返回结果
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回信息 |
| data | object | 返回数据 |
#### 返回数据 `data` 对象
| 名称 | 类型 | 描述 |
| ---------- | -------------- | -------------------------- |
| pid | integer(int64) | 项目编号 |
| currency | string | 币种标识, chain\_id\@token\_id |
| address | string | 查询的地址 |
| total | string | 总余额（可用+处理中） |
| available | string | 可用余额 |
| processing | string | 处理中余额 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"total": 1,
"rows": [
{
"pid":1395142548643840,
"address":"TKDxZEycaxNosmH1V9x6hEacKgWF3RRZ7h",
"currency":"198@TG3XXyExBkPp9nzdajDZsozEu4BkaSJozs",
"total":"7",
"available":"7",
"processing":"0"
}
],
"pageNum": 1,
"pageSize": 10
},
}
```
# 批量创建地址
Source: https://developer-cn.cregis.com/api-reference/request-apis/address/address-batch-generate
批量创建新的收款地址
### 接入 API
POST /api/v1/batch/address/create
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| ------------- | -------------- | ---- | ------------------------------------------------------------------------------------------------ |
| pid | integer(int64) | 是 | 项目编号 |
| chain\_id | string | 是 | 链编号chain\_id |
| alias | string | 否 | 显示名称，如果填写该值，长度限制在1-40个字符 |
| callback\_url | string | 否 | 回调地址,该地址接收资金时会向对应的callback\_url发起交易回调通知,回调详情参考 [地址充值通知](/api-reference/callback/address-deposit) |
| number | string | 是 | 创建地址的数量值，在1-100之间，包含100 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名串 |
###### 请求示例
```json theme={null}
{
"pid": 1382528827416576,
"callback_url": "http://xxxx.com/deposit/callback",
"chain_id": "60",
"alias": "cc",
"number": 10,
"nonce": "ubqso3",
"timestamp": 1687850657960,
"sign": "f5be13fdd8c6f63951ca4427359457cb"
}
```
### 返回
#### 返回结果
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回信息 |
| data | Array | 返回数据 |
#### 返回数据 `data` 对象
| 名称 | 类型 | 描述 |
| ------- | ------ | -- |
| address | string | 地址 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": [
{
"address": "THnZQewzSD8XdxHaWZWcYaJuEhdGHexuSn"
},
{
"address": "TPS1VmkkEFgjJyFCiSkk8eSHJBNi69WYCR"
},
{
"address": "TUzVX6NSkgq7ZwznXdfDSp97B6mQW2e6T8"
},
{
"address": "TK8an5omq7engcFWxj528tuNkZYA6rSd5h"
},
{
"address": "TRiimhegJiHU2T7CQpg4xt3K6XU3WenRG7"
},
{
"address": "TRXamqVuW5Csh3HvoiLcA4X9Vd2xmMH1Kj"
},
{
"address": "TS6b9qG3qzTkjvbCN4uWbsmBDxXGks88YF"
},
{
"address": "TSPpPCFSqrduYye5TmVe6soJC4SD7YWVhm"
},
{
"address": "TLxRaUpZdi8BCM33AgbtEhxcxed82rwCK5"
},
{
"address": "TYvJZxYzxUevySMECpJjgE46AHnps98NYh"
}
]
}
```
# 创建地址
Source: https://developer-cn.cregis.com/api-reference/request-apis/address/address-generate
创建新的收款地址
### 接入 API
POST /api/v1/address/create
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| ------------- | -------------- | ---- | ------------------------------------------------------------------------------------------------ |
| pid | integer(int64) | 是 | 项目编号 |
| chain\_id | string | 是 | 链编号chain\_id |
| alias | string | 否 | 显示名称 |
| callback\_url | string | 否 | 回调地址,该地址接收资金时会向对应的callback\_url发起交易回调通知,回调详情参考 [地址充值通知](/api-reference/callback/address-deposit) |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名串 |
###### 请求示例
```json theme={null}
{
"pid": 1382528827416576,
"callback_url": "http://xxxx.com/deposit/callback",
"chain_id": "60",
"alias": "cc",
"nonce": "ubqso3",
"timestamp": 1687850657960,
"sign": "f5be13fdd8c6f63951ca4427359457cb"
}
```
### 返回
#### 返回结果
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回信息 |
| data | object | 返回数据 |
#### 返回数据 `data` 对象
| 名称 | 类型 | 描述 |
| ------- | ------ | -- |
| address | string | 地址 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"address": "TBotPUNNgeSJmqWkSE7JoHdAnsdMyVnUca"
}
}
```
# 更新地址信息
Source: https://developer-cn.cregis.com/api-reference/request-apis/address/address-update
更新地址相关信息
### 接入 API
POST /api/v1/address/update
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| ------------- | -------------- | ---- | ----------------------------------------------------- |
| address | string | 是 | 需要更新的项目地址 |
| callback\_url | string | 否 | 回调地址 【callback\_url、alias、status至少填写一项】 |
| alias | string | 否 | 地址显示名称 【callback\_url、alias、status至少填写一项】 |
| status | string | 否 | 地址状态【0-启用状态 1-禁用状态】【callback\_url、alias、status至少填写一项】 |
| pid | integer(int64) | 是 | 项目编号 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名 |
###### 请求示例
```json theme={null}
{
"address":"TAxmdDrQGzW37nm1xH4NXXfff2tUTaTecR",
"callback_url": "http://xxx.com/address/callback",
"alias": "地址更新操作",
"status": "1",
"pid": 1382528827416576,
"nonce": "hwlkk6",
"timestamp": 1688004243314,
"sign": "d6eef2de79e39f434a38efb910213ba6"
}
```
### 返回
#### 返回结果
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回信息 |
| data | object | 返回数据 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": null
}
```
# 校验地址是否存在
Source: https://developer-cn.cregis.com/api-reference/request-apis/address/validation-address-existence
查询地址是否为项目内部地址
### 接入API
POST /api/v1/address/inner
校验地址是否为对应项目的地址，可在订单发起后，对返回的地址信息进行校验，防止地址被篡改
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| --------- | -------------- | ---- | ------- |
| pid | integer(int64) | 是 | 项目编号 |
| address | string | 是 | 地址 |
| chain\_id | string | 是 | 链编号 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名 |
###### 请求示例
```json theme={null}
{
"pid": 1382528827416576,
"address": "TXsmKpEuW7qWnXzJLGP9eDLvWPR2GRn1FS",
"chain_id": "195",
"nonce": "tvccuh",
"timestamp": 1687849472174,
"sign": "48036043999446485fe0d20a838a00dc"
}
```
### 返回
#### 返回结果
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回说明 |
| data | object | 返回数据 |
#### 返回数据 `data` 对象
| 名称 | 类型 | 描述 |
| ------ | ------- | ------------------------------------------- |
| result | boolean | true：地址是项目内地址
false: 地址不是项目内部地址
|
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"result": false
}
}
```
# 查询项目币种
Source: https://developer-cn.cregis.com/api-reference/request-apis/global/currency-query
查询项目支持的币种信息
### 接入API
POST /api/v1/coins
查询项目支持币种信息，币种相关信息可在其他接口进行使用。
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| --------- | -------------- | ---- | ------- |
| pid | integer(int64) | 是 | 项目编号 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名 |
###### 请求示例
```
{
"pid": 1382528827416576,
"nonce": "m8jisx",
"timestamp": 1687848653294,
"sign": "cebd2bfd56766f1143dc40d078b64dac"
}
```
### 返回
#### 返回结果
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回信息 |
| data | object | 返回数据 |
##### 返回数据 `data` 对象
| 名称 | 类型 | 描述 |
| ---------- | ------ | ---------------- |
| coin\_name | string | 币种名称 |
| chain\_id | string | 链编号 |
| token\_id | string | token编号，代币即是合约地址 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"payout_coins": [
{
"coin_name": "TRON#Shasta",
"chain_id": "195",
"token_id": "195"
},
{
"coin_name": "Dogecoin",
"chain_id": "3",
"token_id": "3"
}
],
"address_coins": [
{
"coin_name": "TRON#Shasta",
"chain_id": "195",
"token_id": "195"
},
{
"coin_name": "Dogecoin",
"chain_id": "3",
"token_id": "3"
}
]
}
}
```
# 查询交易记录
Source: https://developer-cn.cregis.com/api-reference/request-apis/global/trade-query
查询商户历史交易信息
### 接入API
POST /api/v1/trade/page
查询商户的历史交易记录信息
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| ---------------- | -------------- | ---- | ------------------------------------ |
| cid | integer(int64) | 否 | cregis订单编号 |
| tx\_id | string | 否 | 交易hash |
| status | int | 否 | 交易状态【0-待确认 1-成功 2-失败】 |
| trade\_type | int | 否 | 交易类型【1-转入 2-转出】 |
| business\_type | int | 否 | 【0:普通交易 2:审核交易 3:地址收款 4:归集手续费 5:归集】 |
| blocktime\_start | integer(int64) | 否 | 区块时间-查询开始时间戳【10位】 |
| blocktime\_end | integer(int64) | 否 | 区块时间-查询结束时间戳【10位】 |
| chain\_id | string | 否 | 链编号chain\_id |
| token\_id | string | 否 | 代币编号 |
| page\_num | int | 否 | 分页页数，如果不填，默认为1 |
| page\_size | int | 否 | 分页每页数量，如果不填默认为10，如果填写了，限制最大值为100 |
| pid | integer(int64) | 是 | 项目编号 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名 |
###### 请求示例
```
{
"cid": 1410580986806272,
"tx_id": "0xa795af0324b1e3b862ae0c271bc8b3d99c7a1b72a6a0088a10c84403d0e6f27d",
"status": 1,
"trade_type": 1,
"business_type": 3,
"blocktime_start": 1721900581,
"blocktime_end":1721998633,
"chain_id": "2610",
"token_id": "0x337610d27c682e347c9cd60bd4b3b107c9d34ddd",
"page_num": 1,
"page_size": 10,
"pid": 1382528827416576,
"remark": "payout",
"nonce": "hwlkk6",
"timestamp": 1688004243314,
"sign": "d6eef2de79e39f434a38efb910213ba6"
}
```
### 返回
#### 返回结果
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回信息 |
| data | object | 返回数据 |
##### 返回数据 `data` 对象
| 名称 | 类型 | 描述 |
| ------------- | -------------- | --------------------- |
| pid | integer(int64) | 项目编号 |
| cid | integer(int64) | 系统流水号 |
| chain\_id | string | 链编号 |
| token\_id | string | 代币编号 |
| currency | string | 币种标识 |
| to\_address | string | to地址 |
| amount | string | 金额 |
| status | integer(int32) | 交易状态【0-待确认 1-成功 2-失败】 |
| txid | string | 交易hash |
| block\_height | string | 区块高度 |
| block\_time | integer(int64) | 区块时间 |
| fee | string | 交易费用 |
| from\_address | string | from地址 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"total": 1,
"rows": [
{
"pid": 1409650233999360,
"cid": 1410580986806272,
"chain_id": "2610",
"token_id": "0x337610d27c682e347c9cd60bd4b3b107c9d34ddd",
"to_address": "0x2d4124dcf3ca13acaff5579e1aa962c968df9092",
"amount": "0.1",
"status": 1,
"txid": "0xa795af0324b1e3b862ae0c271bc8b3d99c7a1b72a6a0088a10c84403d0e6f27d",
"block_height": "42393516",
"block_time": 1721900581,
"fee": "0.00258015",
"from_address": "0xbd5ba5a08849c8a2c8ef188778ec383682b0063b"
}
],
"pageNum": 1,
"pageSize": 10
}
}
```
# 创建订单
Source: https://developer-cn.cregis.com/api-reference/request-apis/payment/payment-engine-create
创建包含收银台页面支付页面的订单
### 接入API
POST /api/v2/checkout
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| -------------------------- | -------------- | ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pid | integer(int64) | 是 | Cregis中该收单项目的唯一编号 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 13位unix时间戳格式 |
| sign | string | 是 | 对该接口请求进行的数字签名以防止非法请求，请参考[签名规则](/api-reference/signature)章节。 |
| order\_id | string | 是 | 商家内部的订单编号【不超过128位字符】 |
| order\_amount | string | 是 | 付款总额（如order\_currency是法币，则以法币金额计算／如order\_currency是加密货币，则以加密货币金额计算） |
| order\_currency | string | 是 | 请参阅[订单货币列表](/api-reference/request-apis/payment/payment-order-currency)
- 如订单币种为加密货币，例子为USDT、ETH等。
- 如订单币种为法币：则填入ISO 4217 3 位字元货币代码。例子为HKD、 USD等。 |
| order\_details | JSONString | 否 | 订单商品明细包括价格、数量和商品描述。这显示在 Cregis 结帐页面的订单详情部分 |
| sub\_merchant | JSONString | 否 | 商户可使用此字段来记录内部子商户的编号 |
| payer\_id | string | 是 | 付款人编号 |
| payer\_name | string | 否 | 付款人姓名 |
| payer\_email | string | 否 | 付款人邮箱,若accept\_partial\_payment或accept\_over\_payment为false则必填 |
| tokens | ArrayString | 否 | 此字段中可限制您允许客户支付的代币。如此字段留空，则表示接受支持所有代币作为支付代币。请参阅[支付货币列表](/api-reference/request-apis/payment/payment-pay-currency)
填写参数可参考付款及结算参数页面内支付货币及支付网络的单位：例如：USDT-BEP20、USDT-TRC20等 |
| stablecoin\_realtime\_rate | string | 否 | 默认值：false
false：代表 USDT/USDC 兑 USD 使用固定1:1的汇率
true：代表 USDT/USDC兑USD 使用从CoinMarketCap上获取的实时汇率 |
| underpaid\_tolerance | float | 否 | 部分支付限额,该订单可接受的支付金额容差下限,单位为order\_currency,默认值为0。
此容差下限用于计算你允许订单可接受的最少支付金额。单位根据字段order\_currency:
- “已支付”订单状态：order\_amount - underpaid\_tolerance `<=` 实际支付金额 `<=` order\_amount + overpaid\_tolerance
- “部分付款”订单状态：实际支付金额 \< order\_amount - underpaid\_tolerance
- “超额付款”订单状态：order\_amount + overpaid\_tolerance \< 实际支付金额
例子：order\_currency 为 HKD 及 underpaid\_tolerance 为 3.50。订单状态为:
- "已支付"如订单少付款小于或等于3.50 HKD
- "部分支付"如订单少付款超过3.50 HKD |
| overpaid\_tolerance | float | 否 | 超额支付限额，该订单可接受的支付金额容差上限,单位为order\_currency,默认值为0。
此容差上限用于计算你允许订单可接受的最多支付金额。单位根据字段order\_currency:
- “已支付”订单状态：order\_amount - underpaid\_tolerance `<=` 实际支付金额 `<=` order\_amount + overpaid\_tolerance
- “部分付款”订单状态：实际支付金额 \< order\_amount - underpaid\_tolerance
- “超额付款”订单状态：order\_amount + overpaid\_tolerance \< 实际支付金额
例子：order\_currency 为 HKD 及 overpaid\_tolerance 为 3.50。订单状态为:
- "已支付"如订单多付或等于3.50 HKD
- "超额支付"如订单多付款超过3.50 HKD |
| accept\_partial\_payment | string | 否 | 默认值："true"
- "false": 如订单不接受部分支付及实际支付金额少于order\_amount时，付款人需对订单进行补款或进行退款
- "true": 如订单接受部分支付，即允许付款人不需对订单进行补款或退款 |
| accept\_over\_payment | string | 否 | 默认值："true"
- "false": 如订单不接受超额支付及实际支付金额大于order\_amount时，付款人需对订单进行差价退款
- "true": 如订单接受超额支付，即允许付款人不需对订单进行差价退款 |
| language | string | 否 | 默认值：en
用于指定收银台或邮件的默认语言，可选值为：
en - 英文
tc - 繁体中文
sc - 简体中文 |
| callback\_url | string | 否 | Cregis 会向此回调地址发送订单状态更新的通知,回调详情参考 [订单支付通知](/api-reference/callback/payment-engine) |
| remark | string | 否 | 商户可对这笔支付订单做出备注【不超过256位字符】 |
| valid\_time | integer | 是 | 单位：分钟（可填写：10 到 1440 的整数）
订单的有效时间。如超过有效时间，将不可以再支付。 |
| success\_url | string | 是 | 付款成功后，点击“返回商店”按钮，付款人将被重定向到此 URL。请确保 URL 中包含“http\://”或“https\://” |
| cancel\_url | string | 是 | 如果付款人不付款或点击“取消”按钮，则定向至此 url。请确保 url 中包含“http\://”或“https\://”。 |
**order\_details object**
| 名称 | 类型 | 是否必须 | 描述 |
| -------------- | --------------- | ---- | --- |
| shopping\_cost | decimal | 否 | 运费 |
| tax\_cost | decimal | 否 | 消费税 |
| items | JSONArrayString | 否 | 税项 |
**items object**
| 名称 | 类型 | 是否必须 | 描述 |
| --------------- | -------------- | ---- | ----------------------------------------------------------------------- |
| item\_id | string | 否 | 商品唯一ID |
| item\_name | string | 否 | 商品名称 |
| item\_price | decimal | 否 | 商品价格 |
| price\_currency | string | 否 | 请参阅[订单货币列表](/api-reference/request-apis/payment/payment-order-currency) |
| item\_quantity | integer(int64) | 否 | 商品数量 |
**sub\_merchant object**
| 名称 | 类型 | 是否必须 | 描述 |
| ------------------- | ------ | ---- | ------- |
| sub\_merchant\_id | string | 否 | 子商户唯一编号 |
| sub\_merchant\_name | string | 否 | 商户名称 |
###### 请求示例
```json theme={null}
{
"timestamp": 1734327655,
"nonce": "dositl",
"sign": "f5be13fdd8c6f63951ca4427359457cb",
"order_id": "merchant_order_id_12334567",
"order_amount": "5",
"order_currency": "USD",
"callback_url": "https://callback.com",
"remark": "VIP order",
"payer_id": "payer001",
"payer_name": "payer",
"payer_email": "payer@gmail.com",
"valid_time": 60,
"pid": 1419287201923072,
"cancel_url": "https://cancel.merchant.com",
"success_url": "https://success.merchant.com",
"tokens": "[\"USDT-TRC20\",\"USDT-BEP20\"]",
"order_details": "{\"items\": [{\"item_id\": \"10001\", \"item_name\": \"Product1\",\"item_price\": 123.00,\"item_quantity\": 1,\"price_currency\": \"USD\"},{\"item_id\": \"10002\", \"item_name\": \"Product2\",\"item_price\": 100.00,\"item_quantity\": 2,\"price_currency\": \"USD\"}],\"shopping_cost\": 10.88,\"tax_cost\": 10.00}"
"sub_merchant": "{\"sub_merchant_id\": \"submerchant10001\",\"sub_merchant_name\": \"Merchant1\"}"
}
```
### 返回
#### 返回数据
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回信息 |
| data | Object | 返回数据 |
#### `data` 对象
| 名称 | 类型 | 描述 |
| ------------------- | -------------- | ---------------------------------------------------------------------------- |
| cregis\_id | string | Cregis唯⼀识标 |
| checkout\_url | string | 收银台链接 |
| merchant\_name | string | 收银台展示的商户名称 |
| merchant\_logo\_url | string | 收银台展示的商户logo |
| order\_amount | string | 订单⾦额 |
| order\_currency | string | 订单货币代码 |
| created\_time | integer(int64) | 订单创建时间以13位unix时间戳格式
e.g. 1720508269092 , i.e. 2024-07-09 14:57:49 092 |
| expire\_time | integer(int64) | 订单失效时间以13位unix时间戳格式
e.g. 1720508269092 , i.e. 2024-07-09 14:57:49 092 |
| payment\_info | ArrayObject | 订单相关讯息 |
#### `payment_info` 对象
| 名称 | 类型 | 描述 |
| ----------------- | ------- | ---------------------------- |
| payment\_address | string | 充值地址 |
| token\_symbol | string | 可用于支付的加密货币。可參考订单建立中的tokens参数 |
| blockchain | string | 货币⽹络 |
| token\_name | string | 货币名称 |
| logo\_url | string | 货币logo地址 |
| token\_decimals | integer | 货币精度 |
| receive\_amount | string | 汇率转换后的订单⾦额 |
| receive\_currency | string | 汇率转换后订单货币代码 |
| exchange\_rate | string | 货币汇率 |
| asset\_logo | string | 资产标识logo |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"cregis_id": "po1420761885130752",
"checkout_url": "http://192.168.2.60:9099?cid=b2fb433c953a43bd9bdfc3f611567887",
"merchant_name": null,
"merchant_logo_url": null,
"order_amount": "5",
"order_currency": "HKD",
"created_time": 1734328473070,
"expire_time": 1734332073070,
"payment_info": [
{
"payment_address": "TX8GZJfLYPtmzRgd3FoiXuCHbptiQ37NSM",
"token_symbol": "USDT",
"blockchain": "TRON",
"token_name": "USDT-TRC20",
"logo_url": "https://static.cregis.io/pic/coin/USDT-Tron-TRC20@8x.png",
"token_decimals": 6,
"receive_amount": "0.642951",
"receive_currency": "USDT",
"exchange_rate": "0.1285902181",
"asset_logo": "https://static.cregis.io/pic/coin/tether%20usd-usdt-with-currency@8x.png"
},
{
"payment_address": "0xf9d70ab23195cfc9c0c14b384a1fd3a3f12cd4f8",
"token_symbol": "USDT",
"blockchain": "BNB-BSC",
"token_name": "USDT-BEP20",
"logo_url": "https://static.cregis.io/pic/coin/USDT-BNB%20Chain-BEP20@8x.png",
"token_decimals": 18,
"receive_amount": "0.642951",
"receive_currency": "USDT",
"exchange_rate": "0.1285902181",
"asset_logo": "https://static.cregis.io/pic/coin/tether%20usd-usdt-with-currency@8x.png"
},
]
}
}
```
# 查询订单信息
Source: https://developer-cn.cregis.com/api-reference/request-apis/payment/payment-engine-query
查询订单详情
### 接入API
POST /api/v2/order/info
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| ---------- | -------------- | ---- | ---------- |
| pid | integer(int64) | 是 | 项目编号 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名 |
| cregis\_id | string | 是 | cregis订单编号 |
###### 请求示例
```json theme={null}
{
"cregis_id": "po20240703132452000",
"pid": 1382528827416576,
"nonce": "hwlkk6",
"timestamp": 1688004243314,
"sign": "d6eef2de79e39f434a38efb910213ba6"
}
```
### 返回
#### 返回数据
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回信息 |
| data | object | 返回数据 |
#### 返回数据 `data` 对象
| 名称 | 类型 | 描述 |
| ------------------ | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| cregis\_id | string | cregis订单编号 |
| order\_id | string | 调用方订单编号 |
| order\_amount | string | 订单金额 |
| order\_currency | string | 订单币种 |
| created\_time | integer(int64) | 订单创建时间以13位unix时间戳格式
e.g. 1750407942433 , i.e. 2024-07-09 14:57:49 092 |
| cancel\_time | integer(int64) | 订单取消时间以13位unix时间戳格式
e.g. 1750407942433 , i.e. 2024-07-09 14:57:49 092 |
| transact\_time | integer(int64) | 订单完成时间以13位unix时间戳格式
e.g. 1750407942433 , i.e. 2024-07-09 14:57:49 092 |
| valid\_time | integer(int64) | 单位：分钟（可填写：10 到 60 的整数）
订单的有效时间。如超过有效时间，将不可以再支付。 |
| status | string | 订单支付状态
new - 订单初始状态
paid - 订单已成功支付
expired - 订单超出有效时间
paid\_over - 付款超出订单金额
paid\_partial - 付款小于订单金额 |
| refund\_requested | string | 订单是否发生了退款
no：无退款申请记录
yes：有退款申请记录 |
| refund\_data | object | 退款订单相关讯息 |
| payer\_id | string | 付款人信息 |
| payer\_name | string | 付款人名称 |
| payer\_email | string | 付款人邮箱 |
| remark | string | 订单备注信息 |
| payment\_detail | ArrayObject | 付款记录 |
| payment\_info | ArrayObject | 请求付款信息 |
| order\_details | Object | 商品信息 |
| settlement\_status | string | 结算状态
- unsettled：尚未结算
- settling：正在结算
- settled：结算已完成 |
| settlement\_type | string | 结算类型
- system：自动结算
- manual：手动结算 |
| sub\_merchant | Object | 子商户信息 |
**order\_details object**
| 名称 | 类型 | 描述 |
| -------------- | ----------- | ---------- |
| shopping\_cost | decimal | 订单的运费 |
| tax\_cost | decimal | 订单的税费 |
| items | ArrayObject | 订单内购买商品的详情 |
**items object**
| 名称 | 类型 | 描述 |
| --------------- | -------------- | ------ |
| item\_id | string | 商品唯一ID |
| item\_name | string | 商品名称 |
| item\_price | decimal | 商品价格 |
| price\_currency | string | 商品币种 |
| item\_quantity | integer(int64) | 商品数量 |
**sub\_merchant object**
| 名称 | 类型 | 描述 |
| ------------------- | ------ | ------- |
| sub\_merchant\_id | string | 子商户唯一编号 |
| sub\_merchant\_name | string | 子商户名称 |
**payment\_detail object**
| 名称 | 类型 | 描述 |
| ----------------- | ------ | ---------- |
| payment\_address | string | 充值地址 |
| from\_address | string | 支付方地址 |
| receive\_amount | string | 汇率转换后的订单金额 |
| receive\_currency | string | 汇率转换后的订单币种 |
| pay\_amount | string | 实际到账金额 |
| pay\_currency | string | 到账币种 |
| exchange\_rate | string | 汇率 |
| tx\_id | string | 交易hash |
| blockchain | string | 货币网络 |
| token\_name | string | 货币名称 |
**payment\_info object**
| 名称 | 类型 | 描述 |
| ----------------- | ------- | -------------------- |
| payment\_address | string | 充值地址 |
| token\_symbol | string | 币种。可参考订单建立中的tokens参数 |
| blockchain | string | 货币网络 |
| token\_name | string | 货币名称 |
| logo\_url | string | 货币logo地址 |
| token\_decimals | integer | 货币精度 |
| receive\_amount | string | 汇率转换后的该收订单金额 |
| receive\_currency | string | 汇率转换后订单货币代码 |
| exchange\_rate | string | 货币汇率 |
| asset\_logo | string | 币种标识logo |
**refund\_data object**
| 名称 | 类型 | 描述 |
| ---------------------- | -------------- | ------------------------------------------------------------------------------- |
| refund\_id | integer(int64) | Cregis退款订单编号 |
| cregis\_id | string | Cregis支付订单唯一编号 |
| reference\_id | string | 商家内部的原订单编号 |
| recipient\_id | string | 商家内部的客户编号 |
| recipient\_name | string | 退款收款人姓名 |
| recipient\_email | string | 退款收款人邮箱 |
| recipient\_address | string | 退款收款人的链上地址 |
| token | string | 退款订单的币种填入加密货币token\_name，格式：USDT-BEP20，USDT-TRC20 |
| network | string | 退款订单的网络 blockchain |
| refund\_amount | string | 退款金额 |
| refund\_fee | string | 退款所需gas fee |
| actual\_refund\_amount | string | 扣减矿工费后的实际退款金额 |
| type | integer | 退款类型
1：代表 部分退款
2：代表 全额退款 |
| refund\_status | integer | 退款状态
0: 代表 退款处理中
1：代表 退款成功
2：代表 退款失败 |
| refund\_tx\_id | string | 退款交易哈希 |
| refund\_created\_time | string | 退款订单创建时间以13位unix时间戳格式
e.g. 1720508269092 ,i.e. 2024-07-09 14:57:49 092 |
| refund\_transact\_time | string | 退款订单最后更新时间以13位unix时间戳格式
e.g. 1720508269092 ,i.e. 2024-07-09 14:57:49 092 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"cregis_id": "po1420761885130752",
"order_id": "merchant_order_id_123",
"order_amount": "5",
"order_currency": "HKD",
"created_time": 1734328473070,
"cancel_time": null,
"transact_time": 1734328473872,
"valid_time": 60,
"status": "paid",
"payer_id": "payer001",
"payer_name": "payer",
"payer_email": "12345678@email.com",
"remark": "收银台备注",
"payment_detail": [
{
"payment_address": "TUX9zGoPFVXd6RC7pg18nfVLATeN9vgBeX",
"from_address": "THMxY6QeMYqACWs8fiL4VGBz2ZJRp4mDhT",
"receive_amount": "10.00",
"receive_currency": "USDT",
"pay_amount": "10",
"pay_currency": "USDT",
"exchange_rate": "1",
"tx_id": "d51bc829da5ad05c14f8f0a6ae16708129e485346ad91b8d5f2d33e490b91815",
"blockchain": "TRON",
"token_name": "USDT-TRC20"
}
],
"payment_info": [
{
"payment_address": "0xf9d70ab23195cfc9c0c14b384a1fd3a3f12cd4f8",
"token_symbol": "USDT",
"blockchain": "BNB-BSC",
"token_name": "USDT-BEP20",
"logo_url": "https://static.cregis.io/pic/coin/USDT-BNB%20Chain-BEP20@8x.png",
"token_decimals": 18,
"receive_amount": "0.642951",
"receive_currency": "USDT",
"exchange_rate": "0.1285902181",
"asset_logo": "https://static.cregis.io/pic/coin/tether%20usd-usdt-with-currency@8x.png"
},
{
"payment_address": "TX8GZJfLYPtmzRgd3FoiXuCHbptiQ37NSM",
"token_symbol": "USDT",
"blockchain": "TRON",
"token_name": "USDT-TRC20",
"logo_url": "https://static.cregis.io/pic/coin/USDT-Tron-TRC20@8x.png",
"token_decimals": 6,
"receive_amount": "0.642951",
"receive_currency": "USDT",
"exchange_rate": "0.1285902181",
"asset_logo": "https://static.cregis.io/pic/coin/tether%20usd-usdt-with-currency@8x.png"
}
],
"order_details": {
"items": [
{
"item_id": "1",
"item_name": "Product1",
"item_price": 123,
"price_currency": "HKD",
"item_quantity": 1
},
{
"item_id": "1",
"item_name": "Product2",
"item_price": 124,
"price_currency": "HKD",
"item_quantity": 1
}
],
"shopping_cost": 10.88,
"tax_cost": 100
},
"settlement_status": "unsettled",
"settlement_type": "",
"sub_merchant": {
"sub_merchant_id": "123",
"sub_merchant_name": "kg"
}
}
}
```
# 订单货币列表
Source: https://developer-cn.cregis.com/api-reference/request-apis/payment/payment-order-currency
系统支持的订单货币order_currency列表
### 说明
创建订单时可以根据需要选择法定货币或者加密货币代码（order\_currency参数）, 如付款人选择的付款币种与订单币种不同, 系统将使用 CoinMarketCap 提供的汇率进行实时换算
#### 法定货币
| 代码 | 名称 | 精度 |
| --- | ------- | -- |
| HKD | 港币 | 2 |
| USD | 美元 | 2 |
| TWD | 台币 | 2 |
| AED | 阿联酋迪拉姆 | 2 |
| SGD | 新加坡元 | 2 |
| PHP | 菲律宾比索 | 2 |
| CNY | 人民币 | 2 |
| GBP | 英镑 | 2 |
| EUR | 欧元 | 2 |
| MYR | 马来西亚林吉特 | 2 |
| BRL | 巴西货币 | 2 |
| AUD | 澳元 | 2 |
| BGN | 保加利亚列弗 | 2 |
| DKK | 丹麦克朗 | 2 |
| CAD | 加拿大元 | 2 |
| SEK | 瑞典克朗 | 2 |
| CHF | 瑞士法郎 | 2 |
| INR | 印度卢比 | 2 |
#### 加密货币
| 代码 | 名称 | 精度 |
| ---- | ---- | -- |
| USDT | USDT | 2 |
| USDC | USDC | 2 |
| BTC | BTC | 5 |
| SOL | SOL | 4 |
| ETH | ETH | 4 |
| TRX | TRX | 2 |
| BNB | BNB | 4 |
# 支付货币列表
Source: https://developer-cn.cregis.com/api-reference/request-apis/payment/payment-pay-currency
系统支持的支付货币列表
### 说明
创建订单时可以根据需要选择支付指定加密货币名称（tokens参数）, 如付款人选择的付款加密货币币种与订单币种不同, 系统将使用 CoinMarketCap 提供的汇率进行实时换算。如tokens不传，将默认支持所有可支持的加密货币币种进行支付
#### 加密货币
| 加密货币名称 | 货币标识 | 网络 |
| ----------------- | ---- | ------------ |
| USDT-TRC20 | USDT | TRON |
| USDT-ERC20 | USDT | Ethereum |
| USDT-BEP20 | USDT | BSC |
| USDT-Polygon | USDT | Polygon |
| USDT-Avalanche-C | USDT | Avalanche-C |
| USDT-Arbitrum One | USDT | Arbitrum One |
| USDT-Solana | USDT | Solana |
| USDC-Base | USDC | Base |
| USDC-ERC20 | USDC | Ethereum |
| USDC-Solana | USDC | Solana |
| USDC-BEP20 | USDC | BSC |
| USDC-Polygon | USDC | Polygon |
| USDC-Avalanche-C | USDC | Avalanche-C |
| USDC-Arbitrum One | USDC | Arbitrum One |
| USDC-Optimism | USDC | Optimism |
| Bitcoin | BTC | Bitcoin |
| Solana | SOL | Solana |
| Ethereum | ETH | Ethereum |
| Base | ETH | Base |
| Arbitrum One | ETH | Arbitrum One |
| Optimism | ETH | Optimism |
| TRON | TRX | TRON |
| BNB-BSC | BNB | BSC |
# 发起钱包提币
Source: https://developer-cn.cregis.com/api-reference/request-apis/payout/payout-create
发起提币请求，从钱包地址出款
### 接入 API
POST /api/v1/payout
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| ---------------- | -------------- | ---- | ------------------------------------------------------------------------------------ |
| pid | integer(int64) | 是 | 项目编号 |
| currency | string | 是 | 币种标识 |
| address | string | 是 | 提币地址 |
| amount | string | 是 | 金额 |
| callback\_url | string | 否 | 回调地址,该提币信息被处理时会向对应的callback\_url发起回调通知,回调详情参考 [提币通知](/api-reference/callback/payout) |
| third\_party\_id | string | 是 | 调用方业务编号 |
| remark | string | 否 | 备注 |
| memo | string | 否 | memo、tag等上链信息，仅Ton、Xrp支持 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名 |
###### 请求示例
```json theme={null}
{
"pid": 1382528827416576,
"currency": "195@195",
"address": "TXsmKpEuW7qWnXzJLGP9eDLvWPR2GRn1FS",
"amount": "1.1",
"remark": "payout",
"third_party_id": "c9231e604da54469a735af3f449c880f",
"callback_url": "http://xxx.com/payout/callback",
"nonce": "hwlkk6",
"timestamp": 1688004243314,
"sign": "d6eef2de79e39f434a38efb910213ba6"
}
```
### 返回
#### 返回结果
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回信息 |
| data | object | 返回数据 |
#### 返回数据 `data` 对象
| 名称 | 类型 | 描述 |
| --- | -------------- | ----- |
| cid | integer(int64) | 系统流水号 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"cid": 1382688606330880
}
}
```
# 发起钱包提币（v2）
Source: https://developer-cn.cregis.com/api-reference/request-apis/payout/payout-create-v2
发起提币请求，从钱包地址出款，支持从指定钱包指定地址出款
### 接入 API
POST /api/v2/payout
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| ---------------- | -------------- | ---- | --------------------------------------------------------------------------------------------------------------------------- |
| pid | integer(int64) | 是 | 创建的WaaS项目ID |
| wallet\_id | integer(int64) | 否 | 指定出款钱包ID，不传则默认使用该项目设置的默认出款钱包的默认付款地址进行出款，请参考[创建项目](https://support.cregis.com/cregis-wallet-guide/zh-cn/api/manual/creation) |
| currency | string | 是 | 币种标识 |
| from\_address | string | 否 | 发送方地址，不传则默认使用该项目设置的默认出款钱包的默认付款地址进行出款，请参考[创建项目](https://support.cregis.com/cregis-wallet-guide/zh-cn/api/manual/creation) |
| to\_address | string | 是 | 接收方地址，在进行提币前建议先对接收方地址进行校验 |
| amount | string | 是 | 提币金额 |
| callback\_url | string | 否 | 回调地址,该提币信息被处理时会向对应的callback\_url发起回调通知,回调详情参考 [提币通知](/api-reference/callback/payout) |
| third\_party\_id | string | 是 | 调用方业务编号，由您自己的业务系统生成 |
| remark | string | 否 | 转账的描述。不超过256位字符 |
| memo | string | 否 | memo、tag等上链信息，仅Ton、Xrp支持 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名 |
###### 请求示例
```json theme={null}
{
"pid": 1382528827416576,
"wallet_id": 11434198045401088,
"currency": "144@144",
"from_address": "rhAZ673nG6fSXovPAkw3EcrhKyWwXducoi",
"to_address": "rn5Jyu5J6PG64543KdGvS25rQBYFQo7GLc",
"amount": "1.1",
"remark": "payout",
"memo": "123",
"third_party_id": "c9231e604da54469a735af3f449c880f",
"callback_url": "http://xxx.com/payout/callback",
"nonce": "hwlkk6",
"timestamp": 1688004243314,
"sign": "d6eef2de79e39f434a38efb910213ba6"
}
```
### 返回
#### 返回结果
| 名称 | 类型 | 描述 |
| ---- | ------ | ------------------------------------------------------------------------------------ |
| code | string | 返回状态码，成功码只有一个"code": "00000"，其他所有返回码都是表示执行出现异常，请参考[返回码](/api-reference/return-codes) |
| msg | string | 返回信息 |
| data | object | 返回数据 |
#### 返回数据 `data` 对象
| 名称 | 类型 | 描述 |
| --- | -------------- | ----- |
| cid | integer(int64) | 系统流水号 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"cid": 1382688606330880
}
}
```
# 查询钱包提币信息
Source: https://developer-cn.cregis.com/api-reference/request-apis/payout/payout-query
查询钱包提币订单信息
### 接入API
POST /api/v1/payout/query
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| --------- | -------------- | ---- | ------- |
| pid | integer(int64) | 是 | 项目编号 |
| cid | integer(int64) | 是 | 订单编号 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名 |
###### 请求示例
```json theme={null}
{
"pid": 1382528827416576,
"cid": 1382626461605888,
"nonce": "sw7kv5",
"timestamp": 1687853722065,
"sign": "af825ddb839e6796d62977caf18d3394"
}
```
### 返回
#### 返回数据
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回信息 |
| data | object | 返回数据 |
#### Response `data` Object
| 名称 | 类型 | 描述 |
| ---------------- | -------------- | ------------------------ |
| pid | integer(int64) | 项目编号 |
| chain\_id | string | 链编号 |
| token\_id | string | 代币编号 |
| currency | string | 币种标识 |
| from\_address | string | 发送方地址 |
| address | string | 接收方地址 |
| amount | string | 金额 |
| status | integer(int32) | 状态 |
| third\_party\_id | string | 调用方业务编号 |
| remark | string | 备注 |
| memo | string | memo、tag等上链信息，仅Ton、Xrp支持 |
| txid | string | 交易hash |
| block\_height | string | 区块高度 |
| block\_time | integer(int64) | 区块时间 |
#### Response `status` 类型
| 状态(status) | 描述 |
| ---------- | ---- |
| 0 | 待审批 |
| 3 | 审批取消 |
| 4 | 审批驳回 |
| 5 | 待签名 |
| 1 | 签名通过 |
| 2 | 签名驳回 |
| 6 | 交易成功 |
| 7 | 交易失败 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"pid": 1382528827416576,
"from_address": "TRsYEaEd1UbNsoXDza3jyJTnwavk6iWBdk",
"address": "TXsmKpEuW7qWnXzJLGP9eDLvWPR2GRn1FS",
"chain_id": "195",
"token_id": "195",
"currency": "TRX",
"amount": "1.1",
"third_party_id": "1e0fb3a0a9454ad8928d26b592e8b3c7",
"remark": "payout",
"status": 0,
"txid": "6dd05b0972075542219a3fcc116c58feaf9480f1f698cc46c4367ded83955cfd",
"block_height": "34527604",
"block_time": 1686814482000
}
}
```
# 校验地址合法性
Source: https://developer-cn.cregis.com/api-reference/request-apis/payout/validation-address-legality
检查提币地址是否为合法地址
### 接入API
POST /api/v1/address/legal
检验地址格式合法性，可在发起提币前进行校验，检测到账地址合法再执行提币操作
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| --------- | -------------- | ---- | ------- |
| pid | integer(int64) | 是 | 项目编号 |
| address | string | 是 | 地址 |
| chain\_id | string | 是 | 链编号 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名 |
###### 请求示例
```json theme={null}
{
"pid": 1382528827416576,
"address": "TXsmKpEuW7qWnXzJLGP9eDLvWPR2GRn1FS",
"chain_id": "195",
"nonce": "m8jisx",
"timestamp": 1687848653294,
"sign": "cebd2bfd56766f1143dc40d078b64dac"
}
```
### 返回
#### 返回结果
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回信息 |
| data | object | 返回数据 |
#### 返回数据 `data` 对象
| 名称 | 类型 | 描述 |
| ------ | ------- | --------------------------- |
| result | boolean | true: 合法地址
false: 非法地址 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"result": true
}
}
```
# 发起子地址提币
Source: https://developer-cn.cregis.com/api-reference/request-apis/withdrawal/withdrawal-create
发起提币请求，从WaaS项目子地址出款
### 接入 API
POST /api/v1/sub\_address\_withdrawal
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| ---------------- | -------------- | ---- | ---------------------------------------------------------------------------------------- |
| pid | integer(int64) | 是 | 项目编号 |
| currency | string | 是 | 币种标识 |
| from\_address | string | 否 | 发送方地址，该地址必须是对应WaaS项目中的地址 |
| to\_address | string | 是 | 接收方地址，在进行提币前建议先对接收方地址进行校验 |
| amount | string | 是 | 出款金额 |
| callback\_url | string | 否 | 回调地址,该出款信息被处理时会向对应的callback\_url发起回调通知,回调详情参考 [提币通知](/api-reference/callback/withdrawal) |
| third\_party\_id | string | 是 | 调用方业务编号 |
| remark | string | 否 | 备注。不超过256位字符 |
| memo | string | 否 | memo、tag等上链信息，仅Ton、Xrp支持 |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳 |
| sign | string | 是 | 签名 |
###### 请求示例
```json theme={null}
{
"pid": 1382528827416576,
"currency": "144@144",
"from_address": "rhAZ673nG6fSXovPAkw3EcrhKyWwXducoi",
"to_address": "rn5Jyu5J6PG64543KdGvS25rQBYFQo7GLc",
"amount": "1.1",
"remark": "payout",
"memo": "123",
"third_party_id": "c9231e604da54469a735af3f449c880f",
"callback_url": "http://xxx.com/payout/callback",
"nonce": "hwlkk6",
"timestamp": 1688004243314,
"sign": "d6eef2de79e39f434a38efb910213ba6"
}
```
### 返回
#### 返回结果
| 名称 | 类型 | 描述 |
| ---- | ------ | ------------------------------------------------------------------------------------ |
| code | string | 返回状态码，成功码只有一个"code": "00000"，其他所有返回码都是表示执行出现异常，请参考[返回码](/api-reference/return-codes) |
| msg | string | 返回信息 |
| data | object | 返回数据 |
#### 返回数据 `data` 对象
| 名称 | 类型 | 描述 |
| --- | -------------- | ----- |
| cid | integer(int64) | 系统流水号 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"cid": 1382688606330880
}
}
```
# 查询子地址提币信息
Source: https://developer-cn.cregis.com/api-reference/request-apis/withdrawal/withdrawal-query
查询子地址提币订单信息
### 接入API
POST /api/v1/sub\_address\_withdrawal/info
### 请求
#### 请求参数
| 名称 | 类型 | 是否必须 | 描述 |
| --------- | -------------- | ---- | ------------------------ |
| pid | integer(int64) | 是 | 项目编号 |
| cid | integer(int64) | 是 | 系统流水号，子地址出款请求响应data中的cid |
| nonce | string | 是 | 6位随机字符串 |
| timestamp | integer(int64) | 是 | 时间戳，单位毫秒 |
| sign | string | 是 | 签名 |
###### 请求示例
```json theme={null}
{
"pid": 1382528827416576,
"cid": 1382626461605888,
"nonce": "sw7kv5",
"timestamp": 1687853722065,
"sign": "af825ddb839e6796d62977caf18d3394"
}
```
### 返回
#### 返回数据
| 名称 | 类型 | 描述 |
| ---- | ------ | ---- |
| code | string | 返回码 |
| msg | string | 返回信息 |
| data | object | 返回数据 |
#### 返回数据 `data` 对象
| 名称 | 类型 | 描述 |
| ---------------- | -------------- | ------------------------ |
| pid | integer(int64) | 项目编号 |
| chain\_id | string | 链编号 |
| token\_id | string | 代币编号 |
| currency | string | 币种标识 |
| from\_address | string | 发送方地址 |
| to\_address | string | 接收方地址 |
| amount | string | 金额 |
| status | integer(int32) | 状态 |
| third\_party\_id | string | 调用方业务编号 |
| remark | string | 备注 |
| memo | string | memo、tag等上链信息，仅Ton、Xrp支持 |
| txid | string | 交易hash |
| block\_height | string | 区块高度 |
| block\_time | integer(int64) | 区块时间 |
#### 返回数据 `status` 类型
| 状态(status) | 描述 |
| ---------- | ---- |
| 0 | 待审批 |
| 4 | 审批驳回 |
| 5 | 待签名 |
| 1 | 签名通过 |
| 2 | 签名驳回 |
| 6 | 交易成功 |
| 7 | 交易失败 |
###### 返回示例
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"pid": 1382528827416576,
"from_address": "rqkVSVbsatX3mXAc64g9wTihrmoLwpiuB",
"to_address": "rn5Jyu5J6PG64543KdGvS25rQBYFQo7GLc",
"chain_id": "144",
"token_id": "144",
"currency": "XRP",
"amount": "1.1",
"third_party_id": "1e0fb3a0a9454ad8928d26b592e8b3c7",
"remark": "payout",
"memo": "123",
"status": 0,
"txid": "6dd05b0972075542219a3fcc116c58feaf9480f1f698cc46c4367ded83955cfd",
"block_height": "34527604",
"block_time": 1686814482000
}
}
```
# 响应说明
Source: https://developer-cn.cregis.com/api-reference/response
```json theme={null}
{
"code": "00000",
"msg": "ok",
"data": {
"cid": 1382813146816512
}
}
```
| 参数 | 类型 | 描述 | 示例 |
| ---- | ------ | ----------------------------------------------------------------------------------- | ----- |
| code | string | 响应状态码，code为00000表示响应成功，其他状态码表示响应失败。 具体系统错误码可以参考[系统错误码](/api-reference/return-codes) | 00000 |
| msg | string | 错误消息 | 签名错误 |
| data | object | 业务数据，为 Json 对象，如果请求错误，该字段为空。 | |
# 返回码
Source: https://developer-cn.cregis.com/api-reference/return-codes
## 成功码
| 返回码 | 描述 |
| ----- | ------------------------------ |
| 00000 | 成功码只有一个，其他所有返回码都是表示执行出现异常，是错误码 |
## 失败码
| 返回码 | 返回内容 | 描述 |
| ----- | ----------------------------------------------------------------------------------- | ------------------- |
| Axxxx | Param Error | 参数错误 |
| B0001 | Signature Error | 签名错误 |
| T0062 | Please expand the number of API addresses or upgrade the subscription version first | 请先扩容API地址数量或者升级订阅版本 |
| E0001 | The IP is not added to the whitelist list | 白名单列表未添加该ip值 |
| E0002 | Address alias must be a combination of 40 characters or less | 备注必须是40位字符以内组合 |
| E0003 | Item does not exist or item status is anomalous | 项目不存在或项目状态异常 |
| E0004 | Unsupported interface type | 不支持的接口类型 |
| E0005 | Unsupported coin | 不支持的币种 |
| E0006 | The withdrawal amount must be greater than 0 | 提币金额需大于0 |
| E0007 | Incorrect accuracy of the withdrawal amount | 提币金额精度错误 |
| E0008 | Address is invalid | 地址不合法 |
| E0009 | Duplicate business number | 三方业务编号重复 |
| E0010 | Wallet does not exist | 钱包不存在 |
| E0014 | Transfer out of business unqueried to order information | 转出业务未查询到订单信息 |
| E0015 | Item order does not exist | 项目订单不存在 |
| E0016 | Amount error | 金额错误 |
| E0018 | Order number must be unique | 订单编号不允许重复 |
| E0019 | Order number exceeds 128 characters | 订单编号长度超过128位字符 |
| E0020 | Unsupported currency | 不支持的法币 |
| E0021 | Order remark exceeds 256 characters | 订单备注长度超过256位字符 |
| E0022 | Order amount must be greater than 0 | 订单金额需大于0 |
| E0023 | Order amount precision error | 订单金额精度错误 |
| E0024 | Order does not exist | 订单不存在 |
| E0025 | Incorrect payer information | 付款人信息有误 |
| E0026 | Please input in minutes. Minimum is 10 minutes,maximum 60 minutes | 订单超时时间至少十分钟 |
| E0027 | Number of addresses set incorrectly | 批量生成地址数量超出限制 |
| E0028 | Unsupported address status value | 不支持的地址状态值 |
| E0029 | At least one modification required | 至少一个修改项 |
| E0030 | Address update failed | 地址更新失败 |
| E0031 | Failed to create the checkout counter | 创建收银台失败 |
| E0032 | Memo content only supports numeric characters and must be less than 4294967295 | 无效的tag |
| E0033 | Please expand the number of API addresses or upgrade the subscription version first | 超出地址使用数量 |
| E0034 | The number of available withdrawals is insufficient | 超出提币次数 |
# 签名规则
Source: https://developer-cn.cregis.com/api-reference/signature
## 签名算法
1. 请求参数中除去sign和空值参数外，其他参数**按字典序排序**.
字典序定义：在英文字典中，排列单词的顺序是先按照第一个字母以升序排列（即 a、b、c……z 的顺序）；如果第一个字母一样，那么比较第二个、第三个乃至后面的字母。如果比到最后两个单词不一样长（比如，sigh 和 sight），那么把短者排在前。
2. 排序完成后，按照"key1value1key2value2..."进行拼接
3. 将项目的API Key拼接到第 2 步中得到的字符串最前面
4. 将第 3 步中获取的字符串使用散列算法取md5并转为小写即为sign，将sign添加到请求参数中
## 签名示例
**步骤 1** 假设项目 `API Key` 为:
```
f502a9ac9ca54327986f29c03b271491
```
**除 sign 外请求参数** 为:
```json theme={null}
{
"pid": 1382528827416576,
"currency": "195@195",
"address": "TXsmKpEuW7qWnXzJLGP9eDLvWPR2GRn1FS",
"amount": "1.1",
"remark": "payout",
"third_party_id": "c9231e604da54469a735af3f449c880f",
"callback_url": "http://192.168.2.29:9099/callback",
"nonce": "hwlkk6",
"timestamp": 1688004243314
}
```
**步骤 2** （非空参数key按字典序排序）得到的字符串为：
```
addressTXsmKpEuW7qWnXzJLGP9eDLvWPR2GRn1FSamount1.1callback_urlhttp://192.168.2.29:9099/callbackcurrency195@195noncehwlkk6pid1382528827416576remarkpayoutthird_party_idc9231e604da54469a735af3f449c880ftimestamp1688004243314
```
**步骤 3** （拼接项目key）的到字符串为
```
f502a9ac9ca54327986f29c03b271491addressTXsmKpEuW7qWnXzJLGP9eDLvWPR2GRn1FSamount1.1callback_urlhttp://192.168.2.29:9099/callbackcurrency195@195noncehwlkk6pid1382528827416576remarkpayoutthird_party_idc9231e604da54469a735af3f449c880ftimestamp1688004243314
```
**步骤 4** （取md5）得到的 sign 为：
```
c9bae061ae3f5f8d3bfde817f6966c36
```
**最后** 发送的请求参数为（增加了sign）:
```json theme={null}
{
"pid": 1382528827416576,
"currency": "195@195",
"address": "TXsmKpEuW7qWnXzJLGP9eDLvWPR2GRn1FS",
"amount": "1.1",
"remark": "payout",
"third_party_id": "c9231e604da54469a735af3f449c880f",
"callback_url": "http://192.168.2.29:9099/callback",
"nonce": "hwlkk6",
"timestamp": 1688004243314,
"sign": "d6eef2de79e39f434a38efb910213ba6"
}
```
# API Key
Source: https://developer-cn.cregis.com/faqs/APIKey
关于API Key相关的常见问题
## API Key如何进行管理和使用?
API Key作为接口交互中用于验签的重要信息，需妥善使用，不要透露给其他人，从客户端获取到API Key后交与相关人员进行使用，如发现API Key泄漏请及时联系客服进行更换处理
# 地址管理
Source: https://developer-cn.cregis.com/faqs/Address
关于地址相关的常见问题
## 如何保障用户充值地址的正确性？
为防止给用户展示的充值地址有误，可以在给用户展示充值地址前，调用[校验地址是否为项目](/api-reference/request-apis/validation-address-existence)接口，如果校验地址为对应项目地址，即可为用户展示对应的地址
## 提币接口调用失败如何处理？
常见提币失败有以下几种场景：
1、提供的提币地址格式与对应链不匹配，可在发起提币申请前，调用[校验地址是否为合法地址](/api-reference/request-apis/validation-address-legality)接口
2、提币金额的小数点位数太长，建议查看对应币种的精度即为最大可支持的小数点位数
3、调用方业务编号重复，third\_party\_id作为与业务方进行交易的字段，`Cregis`不支持接收重复的业务数据
注意：提币金额不会因为`Cregis`钱包资产余额的不足而导致提币失败。
# 回调
Source: https://developer-cn.cregis.com/faqs/Callback
关于Cregis回调相关的常见问题
## 如何保证回调数据的安全性？
请务必校验回调中sign字段的正确性，同时可联系客服获取回调发起方的服务器IP，接收回调方可设置只接收指定IP发起的回调
## 回调失败如何处理？
`Cregis`认为回调成功的唯一标志是发起回调请求收到`success`字符串，请在接收到回调信息并正确处理业务后返回。回调失败，可登陆`Cregis`客户端，在对应项目中找到失败回调记录进行查看失败原因并操作重新推送
# 币种管理
Source: https://developer-cn.cregis.com/faqs/Coin
关于币种相关的常见问题
## 如何获取币种码?
`Cregis`可通过两种方式获取支持的币种信息：
1、参考文档[币种码](/api-reference/currency-identifiers)，该文档会定时更新，但并不能保证实时性
2、通过查询[支持币种接口](/api-reference/request-apis/currency-query)，该接口会实时返回项目所支持的所有币种数据
# 交易管理
Source: https://developer-cn.cregis.com/faqs/Transaction
关于交易相关的常见问题
## 如何确定交易是否为需要的交易?
`Cregis`中确定币种唯一性的信息为chain\_id+token\_id，可对这两个属性来判断唯一币种
# 服务集成
Source: https://developer-cn.cregis.com/integration
建议Cregis APIs服务集成工作分成三个独立阶段，包括技术验证阶段、产品环境集成阶段和运营阶段。
![]()
1. 技术验证阶段：在该阶段，客户可快速了解API主要功能，根据自身业务需要，再了解感兴趣的API流程的具体描述性，并借助API调试工具，进行快速测试验证。
2. 产品环境集成阶段：经过技术验证，客户将会有足够的信心开始产品集成，从而部署实际产品服务。当然，产品阶段，客户首先要开通正式服务，并通过Cregis 终端应用设置正式产品环境，并配置其接口环境参数。
3. 运营阶段：服务进入运营阶段，如果需调整服务，可重复上述流程；
注：本文内容重点描述第一阶段，借助本文档和API调试工具，开发者无需开通业务即可进行技术对接和验证
# 快速开始
Source: https://developer-cn.cregis.com/quickstart
快速了解如何使用 Cregis 开发者 API
## 下载 Cregis PC 客户端
访问下载链接 [https://www.cregis.com/download](https://www.cregis.com/download)
选择您的操作系统以下载对应的Cregis安装包，安装包大小约为：
* **Mac**: 148M
* **Windows**: 105M
![Cregis Desktop App]()
## 注册账号、登录
详情参考 [帐号注册及登录](https://support.cregis.com/cregis-wallet-guide/zh-cn/xin-shou-ru-men/zhang-hao-zhu-ce-ji-deng-lu)
1. 注册 Cregis 账户
2. 绑定 Google 验证
3. 登录 Cregis 账户
## 生成 API Key
1. 打开 Cregis App
2. 在"钱包"中，创建名为 "my-wallet" 的钱包
![frontpage wallet]()
![cregis wallet]()
3. 创建项目
\-- [*创建项目API*](https://support.cregis.com/cregis-wallet-guide/zh-cn/api/manual/creation)
\-- [*创建支付引擎API*](https://support.cregis.com/cregis-wallet-guide/zh-cn/payment_engine/creation)
请妥善保管您的 **API Key**，**网关服务器域名**，**项目编号**，不要与他人分享。
## 测试 API Key
1. [选择您所需要的SDK](/sdk-tool/sdk): Jave, Go, PHP, C#
2. 准备SDK所需的3个关键信息
API Key, 网关服务器域名, 项目编号
3. [Java测试用例](https://github.com/0xcregis/cregis-java-sdk/blob/master/cregis-sdk-core/src/test/java/com/cregis/core/HutoolClientTest.java)
了解HTTP Request构造细节，请参阅 [请求说明](/api-reference/request)
# SDK支持
Source: https://developer-cn.cregis.com/sdk-tool/sdk
支持多语言版本的SDK可供使用
`Cregis` API提供主流语言的开发者SDK。请点击以下链接下载并使用最新版本的SDK：
## Java
[https://github.com/0xcregis/cregis-java-sdk](https://github.com/0xcregis/cregis-java-sdk)
## Go
[https://github.com/0xcregis/cregis-go-sdk](https://github.com/0xcregis/cregis-go-sdk)
## Php
[https://github.com/0xcregis/cregis-sdk-php](https://github.com/0xcregis/cregis-sdk-php)
## C\#
[https://github.com/0xcregis/cregis-sdk-csharp](https://github.com/0xcregis/cregis-sdk-csharp)
# 调试工具
Source: https://developer-cn.cregis.com/sdk-tool/tool
API调试工具
`Cregis` API为开发者提供了在线调试工具。 请点击以下链接下载该工具的最新版本：
## macOS
开发中...
## winOS
开发中...
# 功能和应用场景
Source: https://developer-cn.cregis.com/usecases
支持种类丰富的加密数字资产的用户充值、订单收款、企业提款（付款）和配套的查询与通知等服务。
![]()
客户可根据自身业务模式，灵活接入并组合相应服务，以下以交易所和电商为例
#### 交易所
交易所需要解决大量个人客户日常充值和提币需求，需要稳定和高效的服务接口，Cregis APIs提供的充值和提币接口，可以满足上述需求，用于构建交易所和客户间双向资金渠道，具体如下图所示：
![]()
#### 电商
电商运营日常中，面向客户需要处理大量的订单销售收款，面对不同供应商需处理采购付款，Cregis APIs提供订单收款和付款功能接口，可满足上述需求，用于构建电商与上下游间的资金渠道，具体如下图所示：
![]()
# 用户充值
Source: https://developer-cn.cregis.com/user-recharge
## 使用方案
针对每个用户，推荐分配唯一专属充值地址，则该用户所有的充值操作，都会围绕该地址进行，好处是：
1. 对于每种资产类型，会为每个用户分配一个充值账
2. 充值账户会反复使用，便利用户经常性入金
3. 用户与充值帐户唯一对应关系，也确保个人账务明确性
![User Recharge Scenario]()
## 使用流程
如上所述，会给用户分配唯一对应的充值地址，一般发生在接纳新客户时，如发生用户注册，具体流程如下：
![User Recharge Process]()
1. 用户注册
* 用户通过业务系统发起新用户注册
* 用户注册成功后，业务系统会发起请求为用户生成专属充值帐户
2. [确定是否支持目标币种](/api-reference/request-apis/currency-query)
* 若不支持，则无法生成账户
3. 生成专属充值帐户
* 业务系统调用 [生成地址](api-reference/request-apis/address-generate) 请求，为该用户分配专属充值帐户
* 对于每种资产类型，会为每个用户分配一个充值账户
* 充值账户会反复使用，便利用户经常性入金
* 用户与充值帐户唯一对应关系，也确保个人账务明确性
4. 监听用户入金
* 通过被动 [监听](api-reference/callback/address-deposit) 方式监听充值入金
* 用户需指定通知回调地址
5. 用户充值
* 用户可选择通过任何第三方钱包，向专属充值账户打款入金
6. 入金通知
* 用户充值后，通知回调地址会接收到充值通知
# 提币付款
Source: https://developer-cn.cregis.com/withdrawal-payment
## 使用方案
企业转账或提币，要求从Cregis企业钱包中操作，因为企业钱包对资金有严格管理，可确保资金使用流程可靠安全，具体措施包括：
1. 严格放款流程审批
2. 基于MPC技术保证的多方签名出金
![withdrawal or payment scenario]()
## 使用流程
如上所述，企业出金围绕企业钱包进行，有着严格的流程，具体流程如下：
![Withdrawal or Payment Process]()
1. [确定是否支持目标币种](/api-reference/request-apis/currency-query)
* 如果不支持，则无法生成提币订单
2. 验证目标地址有效性
* 确定目标地址在目标链上[是否为有效地址](/api-reference/request-apis/validation-address-legality)
3. 发起提币/支付
* 发起[提币申请](/api-reference/request-apis/payout-create) 提交给企业钱包
4. 提币查询/监听
* 用户发起提现后，通知回调地址会收到提现状态通知。
* 用户通过 [查询订单](/api-reference/request-apis/payout-query) 获取订单信息