订单接口

接口概述

订单接口是茄椒支付平台的核心接口，用于处理支付订单的创建、查询、通知等操作。所有接口都采用RESTful风格设计，支持JSON格式的数据交换。

接口基础信息

请求地址

开放接口域名：https://www.qiejiao.com

请求头信息

所有API请求必须包含以下请求头：

请求头	说明	示例值
Content-Type	内容类型	application/json

通用响应格式

json

{
    "code": 200,
    "msg": "success",
    "data": {
        // 具体业务数据
    }
}

提交订单

接口说明

创建新的支付订单，返回订单支付数据，支持CNY（人民币）和USDT发起支付，以CNY发起会自动根据汇率返回需要支付的对应USDT金额, 以USDT发起支付则不参与汇率转换直接返回对应支付USDT金额, 用于生成指定数字货币的支付数据，包括收款金额(USDT)、收款地址、收款地址二维码等。商户可选择直接跳转至官方的收银台供用户支付，也可以使用数据自定义收银台。在用户支付成功后，系统将即时进行回调通知。

请求地址

POST /api/pay/create

请求参数

参数名	类型	必填	说明	示例值
pid	string	是	商户ID	10001
chain_type	int	否	支付链类型	支付方式: 1 波场 (TRC20)、2:以太坊 (ERC20)
order_no	string	是	订单号	20240101000001
amount	decimal	是	订单金额	100.00
currency	string	是	货币类型，默认CNY	币种：CNY 或 USDT
type	int	是	支付类型	1=链上转账 2=内部转账
plat	string	是	内部转账平台，选 type 为 2 时必选	LINK:链上交易, 欧易：OKX、币安：BINANCE、火币：HTX
scanpay	int	否	返回类型默认 1	1=返回订单信息 0=只返回跳转连接
notify_url	string	是	异步通知地址	https://example.com/notify
return_url	string	否	同步返回地址	https://example.com/return
param	object	否	用户自定义数据，在回调到 notifyUrl 的时候会原样返回	`{"user_id": "123"}`
signature	string	是	参考签名算法	`D9BB7783FA0AD06DBD3E0EA71E56F3B0`

请求示例

json

{
    "pid": "10001",
    "chain_type": 1,
    "order_no": "20240101000001",
    "amount": "100.00",
    "type": 1,
    "currency": "CNY",
    "scanpay": 1,
    "notify_url": "https://example.com/notify",
    "return_url": "https://example.com/return",
    "param": "{\"user_id\": \"123\"}",
    "signature": "D9BB7783FA0AD06DBD3E0EA71E56F3B0"
}

响应参数一

scanpay 为 1 时，返回订单信息

参数名	类型	说明	示例值
plat_order_no	string	平台订单ID	20240101000001
u_addr	string	平台收款钱包地址	0x1234567890abcdef1234567890abcdef12345678
u_type	string	平台收款钱包类型	1=波场 (TRC20) 2=以太坊 (ERC20)
amount	decimal	支付的USDT金额	1.000001
expire_time	int	支付过期时间戳	1704069000

响应示例一

json

{
    "code": 200,
    "msg": "success",
    "data": {
        "plat_order_no": "P20240101000001",
        "u_addr": "0x1234567890abcdef1234567890abcdef12345678",
        "u_type": "TRC20",
        "amount": "1.000001",
        "expire_time": 1704069000
    }
}

响应参数二

scanpay 为 0 时，返回订单信息

参数名	类型	说明	示例值
url	string	平台订单支付URL	https://www.qiejiao.com/index/payment/order?plat_order_no=20240101000001
plat_order_no	string	平台订单ID	20240101000001

响应示例二

json

{
    "code": 200,
    "msg": "success",
    "data": {
        "url": "",
        "plat_order_no": "20240101000001"
    }
}

订单查询

接口说明

查询订单支付状态和详细信息。

请求地址

GET /api/pay/query

请求参数

参数名	类型	必填	说明	示例值
pid	string	是	商户ID	123456789
order_no	string	是	商户订单号	20240101000001

请求示例

bash

GET /api/pay/query?pid=10001&order_no=20240101000001

响应参数

参数名	类型	说明	示例值
plat_order_no	string	平台订单ID	P20240101000001
order_no	string	商户订单号	20240101000001
amount	decimal	订单金额	100.00
status	string	订单状态	pending, paid, failed, expired
u_type	string	支付方式	1=波场 (TRC20) 2=以太坊 (ERC20)
paytime	int	支付时间戳	1704067300
createtime	int	创建时间戳	1704067200

响应示例

json

{
    "code": 200,
    "msg": "success",
    "data": {
        "plat_order_no": "P20240101000001",
        "order_no": "20240101000001",
        "amount": "1.000001",
        "status": "paid",
        "u_type": "TRC20",
        "paytime": 1704067300,
        "createtime": 1704067200,
    }
}

异步通知

通知说明

支付成功后，平台会向商户配置的notify_url发送异步通知。商户需要正确处理通知并返回响应。

通知参数

参数名	类型	说明	示例值
pid	string	商户ID	10001
plat_order_no	string	平台订单ID	P20240101000001
order_no	string	商户订单号	20240101000001
amount	decimal	支付的usdt金额	1.000001
cny_amount	decimal	cny金额	7.2
status	string	支付状态	paid
paytime	int	支付时间戳	1704067300
chain_type	string	支付链类型	1=波场 (TRC20) 2=以太坊 (ERC20)
param	string	用户自定义数据	`{"user_id": "123"}`
signature	string	通知签名参考签名算法	D9BB7783FA0AD06DBD3E0EA71E56F3B0

通知示例

json

{
    "pid": 10001,
    "plat_order_no": "P20240101000001",
    "order_no": "20240101000001",
    "chain_type": 1,
    "amount": "1.000001",
    "status": "paid",
    "paytime": 1704067300,
    "createtime": 1704067200,
    "param": "{\"user_id\": \"123\"}",
    "signature": "D9BB7783FA0AD06DBD3E0EA71E56F3B0"
}

响应要求

商户收到通知后，需要在3秒内返回响应：

成功响应：返回HTTP 200状态码和success字符串
失败响应：返回其他状态码或错误信息

处理流程

php

// 异步通知处理示例
public function notifyHandler()
{
    try {
        // 获取通知数据
        $data = $this->request->post();
        
        // 验证签名
        if (!$this->verifySignature($data)) {
            throw new Exception('签名验证失败');
        }
        
        // 验证订单状态
     
        
        // 返回成功响应
        echo 'success'
        exit;
    } catch (Exception $e) {
        // 记录错误日志
        Log::error('异步通知处理失败: ' . $e->getMessage());
        echo 'fail'
    }
}

手动补单

接口说明

当异步通知失败或商户系统异常时，可以使用手动补单接口重新获取订单状态。

请求地址

POST /api/pay/supplement

请求参数

补单如果能提供 交易哈希值能提高补单成功率,

参数名	类型	必填	说明	示例值
pid	string	是	商户ID	123456789
order_no	string	是	业务订单号	20240101000001
p_addr	string	是	付款钱包地址	20240101000001
hash	string	否	交易哈希值	0x3ebc59510baaa6861e98*****e
signature	string	是	签名参考签名算法	D9BB7783FA0AD06DBD3E0EA71E56F3B0

订单为 链上转账 则 hash 值为交易 hash 为哈希值， p_addr 为付款钱包地址
订单为 欧易内部 则 hash 值为欧易平台 p_addr 为 参考编号 ， hash 为订单号
订单为 币安内部 则 hash 值为币安平台 p_addr 为 交易ID， hash 为 哈希值
订单为 火币内部 则 hash 值为火币平台 p_addr 为 区块链交易ID， hash 为 哈希值

请求示例

json

{
    "pid": "123456789",
    "order_no": "20240101000001",
    "p_addr": "0x8da7822a53485ec2ba50db89375c75faeb8dff14",
    "hash": "0x3ebc59510baaa6861e980af93af101870357d14847edd621949d57aa9f450e5e",
    "signature": "D9BB7783FA0AD06DBD3E0EA71E56F3B0"
}

响应参数

与订单查询接口相同。

响应示例

json

{
    "code": 200,
    "msg": "success",
    "data": {
        "plat_order_no": "20240101000001",
        "order_no": "20240101000001",
        "amount": "100.00",
        "status": "paid",
        "u_type": "wechat",
        "paytime": 1704067300,
    },
}

收银台

USDT收银台：https://www.qiejiao.com/index/payment/cny
CNY收银台：https://www.qiejiao.com/index/payment/cny

商户可直接从创建订单返回数据中，取出 payUrl 字段，然后跳转至该地址，供用户支付。

错误代码

错误代码	错误描述	解决方案
1	成功	请求处理成功
403	权限不足	检查商户权限设置
404	资源不存在	检查请求的资源路径
409	订单已存在	使用新的订单号重新提交
422	业务逻辑错误	检查业务规则限制
429	请求频率过高	降低请求频率
500	服务器错误	联系技术支持
503	服务不可用	服务维护中，稍后重试

注意事项

订单号唯一性：商户订单号必须保证唯一性
金额精度：金额精确到分，使用字符串类型避免精度问题
时间戳：使用Unix时间戳，单位为秒
签名验证：所有请求都必须进行签名验证
异步通知：确保异步通知接口能够正确处理请求
错误重试：对于网络错误，建议使用指数退避策略重试
日志记录：记录所有接口调用日志，便于问题排查

订单接口是支付系统的核心，请严格按照文档要求进行对接。如有问题，请联系技术支持。

订单接口 ​

接口概述 ​

接口基础信息 ​

请求地址 ​

请求头信息 ​

通用响应格式 ​

提交订单 ​

接口说明 ​

请求地址 ​

请求参数 ​

请求示例 ​

响应参数一 ​

响应示例一 ​

响应参数二 ​

响应示例二 ​

订单查询 ​

接口说明 ​

请求地址 ​

请求参数 ​

请求示例 ​

响应参数 ​

响应示例 ​

异步通知 ​

通知说明 ​

通知参数 ​

通知示例 ​

响应要求 ​

处理流程 ​

手动补单 ​

接口说明 ​

请求地址 ​

请求参数 ​

请求示例 ​

响应参数 ​

响应示例 ​

收银台 ​

错误代码 ​

注意事项 ​

订单接口

接口概述

接口基础信息

请求地址

请求头信息

通用响应格式

提交订单

接口说明

请求地址

请求参数

请求示例

响应参数一

响应示例一

响应参数二

响应示例二

订单查询

接口说明

请求地址

请求参数

请求示例

响应参数

响应示例

异步通知

通知说明

通知参数

通知示例

响应要求

处理流程

手动补单

接口说明

请求地址

请求参数

请求示例

响应参数

响应示例

收银台

错误代码

注意事项