init

wiki/API.md

@@ -0,0 +1,194 @@
+# 前言
+开发者可通过`Epusdt`提供的`http api`将交易功能集成至任何系统
+
+# 接口统一加密方式
+### 签名算法MD5
+签名生成的通用步骤如下：            
+
+第一步，将所有非空参数值的参数按照参数名ASCII码从小到大排序（字典序），使用URL键值对的格式（即key1=value1&key2=value2…）拼接成`待加密参数`。              
+
+重要规则：   
+◆ 参数名ASCII码从小到大排序（字典序）；         
+◆ 如果参数的值为空不参与签名；        
+◆ 参数名区分大小写；
+第二步，`待加密参数`最后拼接上`api接口认证token`得到`待签名字符串`，并对`待签名字符串`进行MD5运算，再将得到的`MD5字符串`所有字符转换为`小写`，得到签名`signature`。 注意：`signature`的长度为32个字节。
+
+举例：
+
+假设传送的参数如下：      
+```
+order_id : 20220201030210321
+amount : 42
+notify_url : http://example.com/notify
+redirect_url : http://example.com/redirect
+```
+
+假设api接口认证token为：`epusdt_password_xasddawqe`(api接口认证token可以在`.env`文件设置)         
+
+第一步：对参数按照key=value的格式，并按照参数名ASCII字典序排序如下：       
+```
+amount=42&notify_url=http://example.com/notify&order_id=20220201030210321&redirect_url=http://example.com/redirect
+```
+第二步：拼接API密钥并加密：
+```
+MD5(amount=42&notify_url=http://example.com/notify&order_id=20220201030210321&redirect_url=http://example.com/redirectepusdt_password_xasddawqe)
+```
+
+最终得到最终发送的数据：    
+```
+order_id : 20220201030210321
+amount : 42
+notify_url : http://example.com/notify
+redirect_url : http://example.com/redirect
+signature : 1cd4b52df5587cfb1968b0c0c6e156cd
+```
+
+### PHP加密示例
+```php
+    function epusdtSign(array $parameter, string $signKey)
+    {
+        ksort($parameter);
+        reset($parameter); 
+        $sign = '';
+        $urls = '';
+        foreach ($parameter as $key => $val) {
+            if ($val == '') continue;
+            if ($key != 'signature') {
+                if ($sign != '') {
+                    $sign .= "&";
+                    $urls .= "&";
+                }
+                $sign .= "$key=$val"; 
+                $urls .= "$key=" . urlencode($val); 
+            }
+        }
+        $sign = md5($sign . $signKey);//密码追加进入开始MD5签名
+        return $sign;
+    }
+```
+
+# 创建交易接口
+
+## POST 创建交易
+
+POST /api/v1/order/create-transaction
+
+> Body 请求参数
+
+```json
+{
+  "order_id": "2022123321312321321",
+  "amount": 100,
+  "notify_url": "http://example.com/",
+  "redirect_url": "http://example.com/",
+  "signature": "xsadaxsaxsa"
+}
+```
+
+### 请求参数
+
+|名称|位置|类型|必选| 中文名       | 说明            |
+|---|---|---|---|-----------|---------------|
+|body|body|object| 否 ||           |
+|» order_id|body|string| 是 | 请求支付订单号   |           |
+|» amount|body|number| 是 | 支付金额(CNY) | 小数点保留后2位，最少0.01 |
+|» notify_url|body|string| 是 | 异步回调地址    |           |
+|» redirect_url|body|string| 否 | 同步跳转地址    ||
+|» signature|body|string| 是 | 签名        | 接口统一加密方式              |
+
+> 返回示例
+
+> 成功
+
+```json
+{
+  "status_code": 200,
+  "message": "success",
+  "data": {
+    "trade_id": "202203271648380592218340",
+    "order_id": "9",
+    "amount": 53,
+    "actual_amount": 7.9104,
+    "token": "TNEns8t9jbWENbStkQdVQtHMGpbsYsQjZK",
+    "expiration_time": 1648381192,
+    "payment_url": "http://example.com/pay/checkout-counter/202203271648380592218340"
+  },
+  "request_id": "b1344d70-ff19-4543-b601-37abfb3b3686"
+}
+```
+### 返回结果
+
+|状态码|状态码含义|说明|数据模型|
+|---|---|---|---|
+|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|成功|Inline|
+
+### 返回数据结构
+
+状态码 **200**
+
+| 名称                 | 类型      | 解释        | 说明                            |
+|--------------------|---------|-----------|-------------------------------|
+| » status_code      | integer | 请求状态      | 请参考下方[status_code返回状态码及含义](#status_code返回状态码及含义) |
+| » message          | string  | 消息        ||
+| » data             | object  | 返回数据      ||
+| »» trade_id        | string  | 交易号       ||
+| »» order_id        | string  | 请求支付订单号   ||
+| »» amount          | float | 请求支付金额    | CNY,保留2位小数                    |
+| »» actual_amount   | float   | 实际需要支付的金额 | USDT,保留四位小数                   |
+| »» token           | string  | 钱包地址      |                               |
+| »» expiration_time | integer | 过期时间      | 时间戳秒                          |
+| »» payment_url     | string  | 收银台地址     |                               |
+| » request_id       | string  | true      |                               |
+
+
+# 异步回调
+
+支付成功后，`Epusdt`会向目标服务器发生异步通知，告知该笔交易已经支付完成。          
+失败`Epusdt`最高最多重试5次，请注意验证消息签名。      
+目标服务器处理完成后请返回字符串`ok`即可，否则`Epusdt`会一直重试发送消息，最高5次     
+
+POST 【异步回调地址】
+
+> Body 请求参数
+
+```json
+{
+  "trade_id": "202203251648208648961728",
+  "order_id": "2022123321312321321",
+  "amount": 100,
+  "actual_amount": 15.625,
+  "token": "TNEns8t9jbWENbStkQdVQtHMGpbsYsQjZK",
+  "block_transaction_id": "123333333321232132131",
+  "signature": "xsadaxsaxsa",
+  "status": 2
+}
+```
+
+### 请求参数
+
+|名称|位置| 类型     |必选| 中文名                 | 说明              |
+|---|---|--------|---|---------------------|-----------------|
+|body|body| object | 否 ||                     |
+|» trade_id|body| string | 是 | 交易号                 |                 |
+|» order_id|body| string | 是 | 请求支付订单号             |                 |
+|» amount|body| float  | 是 | 支付金额(CNY)           | 小数点保留后2位 |
+|» actual_amount|body| float  | 是 | 实际需要支付的usdt金额(USDT) | 小数点保留后4位 |
+|» token|body| string | 是 | 钱包地址                | |
+|» block_transaction_id|body| string | 是 | 区块交易号               |  |
+|» signature|body| string | 是 | 签名                  |                 |
+|» status|body| int    | 是 | 订单状态                | 1：等待支付，2：支付成功，3：已过期        | 
+
+# status_code返回状态码及含义
+
+| 状态码 | 说明  | 
+|-----|-----|
+|400|系统错误|
+|401|签名认证错误|
+|10002|支付交易已存在，请勿重复创建|
+|10003|无可用钱包地址，无法发起支付|
+|10004|支付金额有误, 无法满足最小支付单位|
+|10005|无可用金额通道|
+|10006|汇率计算错误|
+|10007|订单区块已处理|
+|10008|订单不存在|
+|10009|无法解析参数|

wiki/BT_RUN.md

@@ -0,0 +1,119 @@
+## 前言
+本教程基于`宝塔`操作面板演示`Epusdt`如何运行，如果你未使用`宝塔`面板和有更强的服务器运维基础相信你也能根据教程的一些操作找到灵感！     
+
+## 准备工作
+- 请确保已经安装并启动了`Mysql`和`redis`、`Supervisord`服务
+- 准备一个`telgeram`机器人🤖（用于操作你的钱包和接收交易通知），申请教程参考：[https://w37fhy.cn/2364.html](https://w37fhy.cn/2364.html)
+- 准备一个收银台域名，并完成解析(例如：`upay.dujiaoka.com`)。用于支付请求发起和扫码页面
+
+## 开始使用
+### 一、新增网站
+在`宝塔`面板网站里新增一个网站，无需`php`和`ftp`纯静态即可，但是需要数据库！        
+将提前解析好的收银台域名绑定。     
+![新增网站](img/add_web.png)
+
+### 二、导入Sql
+登录管理刚刚新增数据库，导入`Epusdt`所需的sql文件。     
+![导入Sql](img/run_sql.png)
+
+### 三、配置Epusdt
+1.将编译好的`Epusdt`项目压缩包上传至刚刚新增的网站目录，随后解压。    
+![网站目录](img/web_tree.png)
+2.将`.env.example`重命名为`.env`文件，这个是配置文件   
+3.编辑`.env`文件，填入你的配置     
+```dotenv
+app_name=epusdt
+#下面配置你的域名，收银台会需要
+app_uri=https://upay.dujiaoka.com
+#是否开启debug，默认false
+app_debug=false
+#http服务监听端口
+http_listen=:8000
+
+#静态资源文件目录
+static_path=/static
+#缓存路径
+runtime_root_path=/runtime
+
+#日志配置
+log_save_path=/logs
+log_max_size=32
+log_max_age=7
+max_backups=3
+
+# mysql配置
+mysql_host=127.0.0.1
+mysql_port=3306
+mysql_user=mysql账号
+mysql_passwd=mysql密码
+mysql_database=数据库
+mysql_table_prefix=
+mysql_max_idle_conns=10
+mysql_max_open_conns=100
+mysql_max_life_time=6
+
+# redis配置
+redis_host=127.0.0.1
+redis_port=6379
+redis_passwd=
+redis_db=5
+redis_pool_size=5
+redis_max_retries=3
+redis_idle_timeout=1000
+
+# 消息队列配置
+queue_concurrency=10
+queue_level_critical=6
+queue_level_default=3
+queue_level_low=1
+
+#机器人Apitoken
+tg_bot_token=
+#telegram代理url(大陆地区服务器可使用一台国外服务器做反代tg的url)，如果运行的本来就是境外服务器，则无需填写
+tg_proxy=
+#管理员userid
+tg_manage=
+
+#api接口认证token(用于发起交易的签名认证，请勿外泄)
+api_auth_token=
+
+#订单过期时间(单位分钟)
+order_expiration_time=10
+
+#强制汇率(设置此参数后每笔交易将按照此汇率计算，例如:6.4)
+forced_usdt_rate=
+```
+4. ⚠️注意：配置文件里面不认识的不要修改，留空即可，不会改又要瞎改，除非你对项目源代码很熟悉很有信心😁
+
+### 四、配置反向代理
+由于`Epusdt`会自动开启`http`服务并监听配置端口，所以可以直接用ip访问，例如: `http://127.0.0.1:8000`。     
+这会显得非常不美观，还没有https。     
+所以我们需要借助nginx的`反向代理`来为`Epusdt`绑定一个域名        
+点击`宝塔`->`网站`->点击刚刚新增网站的`设置`->反向代理设置    
+![反向代理](img/fanxiang.png)
+
+### 五、赋予Epusdt执行权限
+`linux`服务器需要赋予`Epust`执行权限方可启动。      
+1.通过`ssh`进入服务器终端      
+2.进入`epusdt`可执行文件所在目录（目录位置可以参考宝塔面板的网站根目录）       
+3.执行命令```chmod +x epusdt```赋予权限(根据你的实际目录来，不用一比一抄我的，每个人的目录都不一样)     
+![执行权限](img/chmodx.png)
+
+
+### 六、配置supervisor
+为了保证`Epusdt`常驻后台运行，我们需要配置`supervisor`来实现进程监听        
+打开`宝塔supervisor`，添加守护进程     
+![supervisor](img/supervisor.png)
+启动命令为：epusdt所在目录+epusdt执行文件+空格+http+空格+start(例如：`/www/wwwroot/upay/epusdt-dev/epusdt http start`)       
+出现如下图则代表成功：     
+![supervisor成功](img/supervisor_success.png)
+
+### 七、测试
+以上步骤完成无误后，进入`telegram`机器人🤖，如果机器人有反馈则代表运行正常！     
+![telegram机器人](img/epusdt_bot.png)
+
+
+## 其他注意事项
+- 1.所有`.env`配置文件有了修改后都需要重启supervisor进程
+- 2.教程所示的目录均为参考，请勿1:1照抄，根据自己实际情况来
+- 3.`windows`与`linux`不同，`windows`请直接运行`epusdt.exe`即可，无需赋予执行权限