Hexpay API 文档

此页面展示了 Hexpay 提供的一些运行时 API 的使用方法。

API base URL- 请联系客服获取

收银台下单支付接口

数据类型：JSON（content-type：application/json）
请求⽅式：POST
路径Path: /v1/hexpay/trade/order
验证方式：签名验证

接口说明

该接口接受商户传入的订单信息，创建用于跳转到Hexpay的支付链接。

请求参数

字段名	类型	最大长度	是否必输	说明
mchNo	String	30	是	商户号
mchOrderNo	String	64	是	商户订单号(唯一)
currency	String	10	是	订单币种，可选值：USDT、USDC、AED、AUD、AZN、BDT、BRL、CAD、CHF、CLP、COP、CRC、CZK、DKK、DOP、DZD、EGP、EUR、GBP、GEL、HKD、HUF、ILS、INR、JPY、KRW、KWD、MAD、MXN、MYR、NGN、NOK、PEN、PHP、PLN、RON、SAR、SEK、SGD、THB、TND、TRY、UAH、USD、XAF、ZAR、INR、GHS、XAF等(持续更新中)
defaultCurrency	String	10	否	使用onramp通道时，期望选择的默认法币。比如收USDT,期望默认使用INR支付，参数为：currency=USDT,defaultCurrency=INR
network	String	30	是	网络，可选值：Solana、Ethereum、Polygon、Arbitrum、Binance_smart_chain、Tron（维护中）
bizCode	Integer		否	通道编号，不确定时不要传，由接口自动适配
amount	BigDecimal	长度20，小数位6	是	订单金额
mchUserId	String	32	是	商户侧用户id
goods	Goods Type	-	是	商品说明
appId	String	64	是	应用id，商户平台创建应用分配
sign	String	512	是	签名
signType	String	10	是	签名类型，默认值RSA2
notifyUrl	String	256	否	异步通知地址（可以在商户后台进行配置）
successUrl	String	256	否	成功后跳转页面（可以在商户后台进行配置）
failUrl	String	256	否	失败跳转页面（可以在商户后台进行配置）
clientIp	String	32	否	终端用户ip（辅助判断国家/地区、语言）
autoChangeCurrency	Boolean	-	否	是否自动换汇（自动计算不同国家/地区对应币种的价格）
mchCoverFee	Boolean	-	否	是否商户承担手续费
version	String	10	是	版本号,例：v1.0

Goods Type

字段名	类型	是否必输	说明
goodsName	String	是	商品名称
goodsDetail	String	是	商品描述
goodsType	String	是	商品分类

请求示例数据

json

{
    "mchNo":"M1752564528",
    "mchOrderNo":"378758439",
    "amount":11,
    "currency":"USDC",
    "network":"Solana",
    "bizCode":0,
    "goods": {
        "goodsType": "shop",
        "goodsName": "T-shirt",
        "goodsDetail": "xxxxxxxxxxx"
    },
    "mchUserId":"1230987",
    "appId":"68760330a2cf0af37c52a073",    "sign":"VaKMVivLXtqJw6kp7PyNaI6P7qoLM9kOXms5Tll8TsX0eubZ0F+bbxGpfaTR2zpCZkVr/iygD4QyuueMt+pMOAOXZ2yayFGloyKL1mMfNHzb5PDPMhU3cKm6cb+BCHkfk5S602rCBFrQSEhVgQiwpd5ezI6NAdw4+EdPwVmzXH6pVZ9YXNSp9n1O8caS5dL0bjhWxO5EFWrxhbfFNLgWy1OXRs9e02wHZXbzukAkbuJl6UZDpPKKluy2m1BbgxYYYHlx4sunBsE8vP5vj50UHg8KK4v1K/XXzx+oIpZQ85895ZFAISLO9V7ugdlXx/+jrpzg2xnEOK9ss/oSSbdDoQ==",
    "signType":"RSA2",
    "version":"v1.0"
}

响应参数

字段名	类型	是否必须	说明
code	String	是	响应码
data	String	否	响应数据
msg	String	否	响应信息

data数据格式

字段名	类型	说明
payOrderId	String	支付订单ID
network	String	网络
location	String	收银台前端地址
currency	String	支付货币类型
amount	BigDecimal	支付金额
orderState	Byte	订单状态，0-订单生成、1-支付中、2-支付成功、3-支付失败、4-已撤销、5-已退款、6-订单关闭或超时

json

{
    "code": 0,
    "data": {
        "amount": 11,
        "currency": "USDC",
        "location": "http://localhost:5173/pay?payOrderId=P1947225344373334017",
        "network": "Solana",
        "orderState": 0,
        "payOrderId": "P1947225344373334017"
    },
    "msg": "SUCCESS"
}

查询订单状态接口

数据类型：JSON（content-type：application/json）
请求⽅式：GET
路径Path: /v1/hexpay/trade/query
验证方式：签名验证

接口说明

该接口接受商户传入的订单号，查询订单状态。

请求参数

字段名	类型	最大长度	是否必输	说明
appId	String	64	是	应用id，商户后台创建
mchNo	String	30	是	商户号
version	String	10	是	版本：v1.0
signType	String	10	是	签名类型：当前版本仅支持RSA2
sign	String	256	是	签名
payOrderId	String	30	与mchOrderNo至少传1个	支付订单Id
mchOrderNo	String	64	与payOrderId至少传1个	商户订单号

请求示例

JSON

{
    "payOrderId":"P1947211653281546242",
    "appId":"68760330a2cf0af37c52a073",
    "mchNo":"M1752564528",
    "version":"v1.0",
    "sign":"57842768902",
    "signType":"RSA2"
}

响应参数

字段名	类型	是否必须	说明
code	String	是	响应码
data	String	否	响应数据
msg	String	否	响应信息
sign	String	是	响应签名

data

字段名	类型	是否必须	说明
payOrderId	String	是	支付订单号
mchNo	String	是	商户号
mchOrderNo	String	是	商户订单号(唯一)
mchName	String	是	商户名称
mchUserId	String	是	商户侧用户id
amount	BigDecimal	是	订单金额
refundAmount	BigDecimal	否	退款金额
state	Integer	是	状态
waitNetwork	String	否	待支付网络
waitPayCurrency	String	否	待支付金额
wayCode	String	是	支付方式
realPayAmount	BigDecimal	否	实际支付金额
realPayCurrency	String	否	实际支付币种
realNetwork	String	否	实际支付网络
goods	Goods	是	商品信息
createdAt	Date	是	订单创建时间
expiredTime	Date	是	订单失效时间
updatedAt	Date	是	更新时间
cancelTime	Date	否	取消时间
paySuccessTime	Date	否	支付成功时间

响应示例

json

{
    "code": 0,
    "data": {
        "amount": 0.001000,
        "createdAt": "2025-07-22 10:57:27",
        "goods": {
            "goodsDetail": "MacBook Pro 14-inch",
            "goodsName": "MacBook Pro 14-inch",
            "goodsType": "MacBook"
        },
        "mchName": "GlobalGoods",
        "mchNo": "M1752564528",
        "mchOrderNo": "ypSp0IpG5on6",
        "mchUserId": "illvBhVGuri7",
        "payOrderId": "P1947491150220296193",
        "paySuccessTime": "2025-07-22 11:01:30",
        "realNetwork": "Solana",
        "realPayAmount": 0.001000,
        "realPayCurrency": "USDC",
        "refundAmount": 0.000000,
        "state": 2,
        "updatedAt": "2025-07-22 10:57:27",
        "wayCode": "QrCode"
    },
    "msg": "SUCCESS",
    "sign": "54F8ADD6BD9BC8867DCB319329F587FE"
}

批量查询订单接口

数据类型：JSON（content-type：application/json）
请求⽅式：GET
路径Path: /v1/hexpay/batch/query
验证方式：签名验证

接口说明

该接口传入mchNo与appId批量查询应用下的订单信息。

请求参数

字段名	类型	最大长度	是否必输	说明
appId	String	64	是	应用id，商户后台创建
mchNo	String	30	是	商户号
version	String	10	是	版本：v1.0
signType	String	10	是	签名类型：当前版本仅支持RSA2
sign	String	256	是	签名
bizCode	Integer		否	通道编号，不确定时不要传，由接口自动适配
createdStart	Date		否	日期格式字符串（yyyy-MM-dd HH:mm:ss），时间范围查询--开始时间，查询范围：大于等于此时间
createdEnd	Date		否	日期格式字符串（yyyy-MM-dd HH:mm:ss），时间范围查询--结束时间，查询范围：小于等于此时间
settleState	Byte		否	结算状态：0-待结算, 1-结算中, 2-结算成功, 3-结算失败, 4-待人工结算
state	Byte		否	订单状态: 0-订单生成, 1-支付中, 2-支付成功, 3-支付失败, 4-已撤销, 5-已退款, 6-订单关闭
current	Integer		否	当前页码，默认为1
size	Integer		否	每页大小，默认为10

请求示例

JSON

{
    "appId": "68c1382798a210e71dedddae",
    "mchNo": "M1757493187",
    "version": "v1.0",
    "signType": "RSA2",
    "state":2,
    "settleState":2,
    "bizCode":1,
    "createdStart":"2025-09-10 00:00:00",
    "createdEnd":"2025-09-10 23:59:59",
    "sign": "g+NAXi68wJ8J9hnKbBEzf6gbF+acYSyn8eMQrQDE6ndzcma9dBVYIRTBaNaeE/aFDAdMB4ARbXpLit8QIaH7vn3ZF6iKqu7tGpax817C9Yz+c9zvLtbt6rvTpwuBCKVfQJNJ+JbWCjXqwfRMJBmDfnUCujdeLnXf2l7QW6azi0Q3CC18UKyRtHGiRZ8kdwP+s3YX7JXCD+N35aFUdf7vwP19nEhXpyjMrZKColFbarQdrPZ1MsrROcnAKPqfMgV0gQ39GizIUi0fSdBR3xD7YtG+pcmJ6iCUzNbpkpMyTYBg5J4sp2MT+ejhUXSp+hYellp20Lt22TE1yCUajAlJkQ=="
}

响应参数

data

字段名	类型	说明
payOrderId	String	支付订单号
appId	String	应用id
mchOrderNo	String	商户订单号(唯一)
createdAt	Date	订单创建时间
state	Integer	状态
mchUserId	String	商户侧用户id
bizCode	Integer	通道编号，不确定时不要传，由接口自动适配
wayCode	String	支付方式
network	String	网络
currency	String	订单币种
amount	BigDecimal	订单金额
realPayAmount	BigDecimal	实际支付金额
realPayCurrency	String	实际支付币种
successTime	Date	成功时间
settleCurrency	String	结算货币
settleAmount	BigDecimal	结算金额
mchFeeAmount	BigDecimal	商户手续费
mchSettleIncome	BigDecimal	商户实际结算收入
settleState	Byte	订单结算状态（0-待结算, 1-结算中, 2-结算成功, 3-结算失败)

json

{
    "code": 0,
    "msg": "SUCCESS",
    "data": {
        "records": [
            {
                "payOrderId": "P1956719923828715522",
                "appId": "689d7bd965ac3acb9b2f0cb7",
                "mchOrderNo": "VO6LDUwMFaSS",
                "createdAt": "2025-08-16 14:09:18",
                "state": 2,
                "mchUserId": "dxrM7dglqQPb",
                "bizCode": 2,
                "wayCode": "-",
                "network": "Solana",
                "currency": "USDC",
                "amount": "12",
                "realPayCurrency": "USDT",
                "realPayAmount": "12",
                "realNetwork": "binance_smart_chain",
                "txHash": "0xd609c2deac9c87df133f8fa2256b2deb019c62daa7151bcdf626055925013432",
                "successTime": "2025-08-16 14:25:02",
                "settleCurrency": "USDC",
                "settleAmount": "12",
                "mchFeeAmount": "0.02",
                "mchSettleIncome": "11.98",
                "settleState": 2
            },
            {
                "payOrderId": "P1955910592950509570",
                "appId": "689d7bd965ac3acb9b2f0cb7",
                "mchOrderNo": "A1EmjBwIBMjC",
                "createdAt": "2025-08-14 08:33:19",
                "state": 2,
                "mchUserId": "eqvmUlm4WeCm",
                "bizCode": 0,
                "wayCode": "QR_CODE",
                "network": "Solana",
                "currency": "USDC",
                "amount": "0.2",
                "realPayCurrency": "USDC",
                "realPayAmount": "0.2",
                "realNetwork": "arbitrum",
                "txHash": "0xc6269fd87101aec2bb95b16f24b17cf64fa7599cc1f06d18c3ee6ffd0ef46d3a",
                "successTime": "2025-08-14 08:34:37",
                "settleCurrency": "USDC",
                "settleAmount": "0.2",
                "mchFeeAmount": "0.01",
                "mchSettleIncome": "0.19",
                "settleState": 2
            },
            {
                "payOrderId": "P1955876137510723586",
                "appId": "689d7bd965ac3acb9b2f0cb7",
                "mchOrderNo": "bh16wcQku0B2",
                "createdAt": "2025-08-14 06:16:24",
                "state": 2,
                "mchUserId": "TucYS0DW1ORa",
                "bizCode": 0,
                "wayCode": "QR_CODE",
                "network": "Arbitrum",
                "currency": "USDC",
                "amount": "0.1",
                "realPayCurrency": "USDC",
                "realPayAmount": "0.1",
                "realNetwork": "arbitrum",
                "txHash": "0x5df6a442c3f974064028c9b67739250d00b080cd7f29444147155c9153bac9d3",
                "successTime": "2025-08-14 06:16:56",
                "settleCurrency": "USDC",
                "settleAmount": "0.1",
                "mchFeeAmount": "0.01",
                "mchSettleIncome": "0.09",
                "settleState": 2
            }
        ],
        "total": 3,
        "size": 10,
        "current": 1,
        "pages": 1
    }
}

订单状态回调

登录商户管理后台 → 进入 应用管理 → 选择对应 App → 配置成功跳转url、失败跳转url、接收订单回调状态url

点击查看密钥生成步骤

回调信息

字段名	类型	说明
payOrderId	String	支付订单号
amount	BigDecimal	订单金额
mchOrderNo	String	商户订单号 (唯一)
sign	String	签名
mchName	String	商户名称
realNetwork	String	实际网络
wayCode	String	支付方式
successUrl	String	支付成功回调地址
failUrl	String	支付失败回调地址
reqTime	String	时间戳
realPayCurrency	String	实际支付币种
createdAt	Date	订单创建时间
appId	String	应用 id
successTime	Date	成功时间
mchUserId	String	商户侧用户 id
currency	String	订单币种
realPayAmount	BigDecimal	实际支付金额
state	Integer	状态
mchNo	String	商户号
refundAmount	BigDecimal	退款金额
updatedAt	Date	订单更新时间
settleCurrency	String	结算货币
settleAmount	BigDecimal	结算金额（法币支付时为对应稳定币金额）

Content-Type: application/x-www-form-urlencoded

Body参考：

json

{
    "payOrderId": "P1958816503884955649",
    "amount": 0.01,
    "mchOrderNo": "482d0876d40d44dfa20c6e6859946a2b",
    "sign": "qHkU9ATWhxKq5W1BoOE9y298zUX9bqY8DoLBZaXZ/trKcCvqU6i/F4HZxYpHZbpWj04wJo9v/n1K25s01sg63Me55qA0wl71R0q0/xSbc2/vuTWQC3k3xhieKg9Qr7SxxS63eizItHnkXTyvjxYcyb5msSEjBr8NBZ83bejJ5LdJ+3t/F3lrQ33oFRvRl8p/aKeuNVI3xJ9nVkxNkl46wXZvZ4wAmb96qh7cVf5dmpf6P9dHVfp2mu9QTJH9lIMg/14PUp2FBNbn9YZIENuhpA4ODIL+HmtPzaHDetZzY7zCDGO1KT6bOpysHuiXmzHI6fOvWB1MXwF1mR4sX6MBrg==",
    "mchName": "M1755226149",
    "realNetwork": "arbitrum",
    "wayCode": "QR_CODE",
    "payWay": "USDC(Arbitrum)",
    "successUrl": "http://gs.shequnplatform.com:38669/order/success",
    "failUrl": "http://gs.shequnplatform.com:38669/order/failure",
    "reqTime": "1755854933053",
    "realPayCurrency": "USDC",
    "createdAt": "2025-08-22 09:00:22",
    "appId": "689ea02565ac52e60665ea8a",
    "successTime": "1755853505000",
    "mchUserId": "1ed646e0dc6e444ea3b98751c2ab9deb",
    "currency": "USDC",
    "realPayAmount": 0.010000,
    "state": 2,
    "mchNo": "M1755226149",
    "refundAmount": "0.000000",
    "updatedAt": "2025-08-22 09:26:25",
    "settleAmount":0.01,
    "settleCurrency":"USDC"
}

查询余额

数据类型：JSON（content-type：application/json）
请求⽅式：POST
路径Path: /v1/hexpay/balance/query
验证方式：签名验证

接口说明

该接口根据商户号、币种、appId查询余额信息

请求参数

字段名	类型	最大长度	是否必输	说明
appId	String	64	是	应用id，传该商户下的任意一个均可
mchNo	String	30	是	商户号
version	String	10	是	版本：v1.0
signType	String	10	是	签名类型：当前版本仅支持RSA2
sign	String	512	是	签名
currency	String	10	否	币种，可选值：USDT、USDC

请求示例

JSON

{
    "mchNo": "M1752564528",
    "currency": "USDC",
    "appId":"68887ae1e4b04fb9fe9e03f2",
    "signType":"RSA2",
    "version":"1.0",
    "sign":"Qu1AVxR1YxDBisaRLITSdC3Dh7pZT+eoRxUxJMd8BOmkoMlN2Zx5MTXWnIaeE/AyXuGcQGT35kgQLhrHecJ2YhzyFS5e89Sfqlm+sNQNxNl9Ad01CrD34DK+jjArM0r69oquAO/alcyuJmkJZWmYtZyPP2xuBWWyzwune6WicYr05GPeswvl/5I0po7XZXBjvPKq/ilCpVWdWf6PZGUVUIQpzLXxmCSt9xAKzm92lNTPC0duXF+hq6dh/Ebjg5YG5IazFVIRGPhuuxAVZMA9aJFc7SnMliwmRYqeugME0IRfKN29nNtVxDKiaobST6DXxQEXhXYBwTfnZGXvALp03w=="
}

响应参数

类型	字段名	说明
String	currency	币种
String	availableBalance	可用余额
String	frozenBalance	冻结余额
String	coinFullName	币种全称

响应示例

json

{
    "code": 0,
    "data": [
        {
            "availableBalance": 65.08666658,
            "coinFullName": "USD Coin",
            "currency": "USDC",
            "frozenBalance": 4.48858868
        }
    ],
    "msg": "SUCCESS"
}

Hexpay API 文档 ​

收银台下单支付接口 ​

接口说明 ​

请求参数 ​

响应参数 ​

查询订单状态接口 ​

接口说明 ​

请求参数 ​

响应参数 ​

批量查询订单接口 ​

接口说明 ​

请求参数 ​

响应参数 ​

订单状态回调 ​

回调信息 ​

查询余额 ​

接口说明 ​

请求参数 ​

响应参数 ​

Hexpay API 文档

收银台下单支付接口

接口说明

请求参数

响应参数

查询订单状态接口

接口说明

请求参数

响应参数

批量查询订单接口

接口说明

请求参数

响应参数

订单状态回调

回调信息

查询余额

接口说明

请求参数

响应参数