加密货币支付 API 文档
这是 VisualPay 加密货币支付网关的完整 REST API 参考。您可以用它创建交易,在任何支持的网络上接受 USDT、USDC、ETH、BNB 和 TON 付款,监控链上状态并接收 Webhook。所有操作都在您自己的后端完成,中间不经过托管收银台。
下面的每个接口都使用同一个商户 API 密钥进行身份验证,返回 JSON,可以从任何语言或框架调用。无需安装 SDK,也没有需要维护的插件。
快速开始
通过 VisualPay 接入加密货币支付网关只需要一次 POST 请求。您提交以美元计价的订单金额,以及希望收款的币种和网络,API 会返回收款地址、精确的 USDT(或其他币种)金额,以及一个可以与订单关联保存的跟踪码。
接入 VisualPay 后,您的业务就可以轻松接受加密货币付款。处理一笔付款时,先创建新交易,再把用户重定向到响应中返回的支付页面。区块链监控由 VisualPay 负责,您可以轮询状态,也可以在商户面板中对账。
创建交易时可以选择传入 callback_url,在付款完成或失败后把付款人带回您的网站。VisualPay 会把 order_id(如果提供)、status 和 tracking_code 作为查询参数附加到这个 URL 上。
https://visualpay.net/
回调跳转
如果在“创建交易”时提供了可选的 callback_url,支付页面会在付款进入最终状态后把付款人的浏览器重定向到您的 URL。所有结果共用同一个 URL,成功与失败通过 status 查询参数区分。
附加到您 URL 上的查询参数
网关会把下表中的参数附加到您的回调 URL 上,您的应用无需再次调用 API 就能识别订单及其最终结果。
| 参数 | 说明 |
|---|---|
order_id |
创建交易时提供的订单 ID(如有)。 |
status |
最终付款状态:confirmed、expired 或 cancelled(与“查询交易”API 的取值相同)。 |
tracking_code |
用于核验的 VisualPay 交易 UUID。 |
跳转示例
https://example.com/order?order_id=100001&status=confirmed&tracking_code=550e8400-e29b-41d4-a716-446655440000
callback_url,付款人会留在 VisualPay 的支付页面上。
跳转时机:付款确认后会先显示 3 秒成功提示再跳转;付款过期或取消时立即跳转。
身份验证
调用 VisualPay 商户 API 时,每个请求都需要使用商户 API 密钥进行身份验证。请在 VisualPay 面板中创建商户,并从商户设置中复制 API 密钥。
每个请求都需要商户 API 密钥。
所有 API 请求都需要在 x-api-key HTTP 请求头中携带您的商户 API 密钥。
x-api-key: YOUR_MERCHANT_API_KEY
/api/v1/merchant/currencies/list
获取支持的币种
返回当前已认证商户启用的币种和网络。
请求示例
curl --location 'https://visualpay.net/api/v1/merchant/currencies/list' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'
响应示例
{
"status": 200,
"data": [
{
"currency_name": "Tether",
"currency_symbol": "USDT",
"currency_type": "stable",
"price_in_usdt": 1,
"icon": "",
"supported_networks": [
{
"network_name": "TRON (TRC20)",
"network_symbol": "TRX",
"network_code": "trc20",
"network_fee": 1,
"minimum_pay_usd": 5,
"maximum_pay_usd": 10000,
"max_ttl": 30,
"icon": ""
}
]
}
],
"message": "success"
}
/api/v1/merchant/transaction/list
获取交易列表
分页返回商户交易。可选筛选条件:status 枚举值、日期范围(最长 30 天)。
请求参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
limit |
否 | integer | 每页条数(1–50) |
page |
否 | integer | 页码 |
from_date |
否 | string (date) | 开始日期(Y-m-d)。必须与 to_date 一起提供。最长范围 30 天。 |
to_date |
否 | string (date) | 结束日期(Y-m-d)。必须与 from_date 一起提供。最长范围 30 天。 |
status |
否 | enum | 可选。支持的取值:pending、confirmed、expired、cancelled。 |
请求示例
curl --location 'https://visualpay.net/api/v1/merchant/transaction/list?limit=50&page=1&from_date=2026-07-01&to_date=2026-07-20&status=pending' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'
响应示例
{
"status": 200,
"data": {
"items": [
{
"order_id": 1001,
"status": "pending",
"tracking_code": "AbC12XyZ",
"payment_url": "https://pay.visualpay.net/AbC12XyZ",
"currency_code": "usdt_trc20",
"currency_name": "Tether",
"network_code": "trc20",
"network_name": "TRON (TRC20)",
"pay_amount": "10.00000000",
"amount_usd": "10.00000000",
"platform_share": "0.20000000",
"merchant_share": "9.80000000",
"payment_fee_percent": 1,
"payment_tolerance_percent": 1,
"paid_amount": "",
"is_canceled_by_user": false,
"tx_id": "",
"tx_explorer_url": "",
"email": "",
"comment": "",
"paid_at": 0,
"created_at": 0,
"expired_at": 0
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 120,
"last_page": 3
}
},
"message": "success"
}
/api/v1/merchant/transaction/create
创建交易
创建一笔新的加密货币付款。
amount_usd:以 USD/USDT 计的应付金额。提交的值必须大于等于 minimum_pay_usd,且小于等于 maximum_pay_usd。
ttl:监控该交易的存活时间,单位为分钟。填写的值不能大于 max_ttl。
order_id:可选。如果提交该参数,必须是 6 位数字。
email:可选。
comment:可选。
callback_url:可选。您网站上可公开访问的 HTTPS URL。提供后,支付页面会在交易进入终态(confirmed、expired 或 cancelled)后把付款人重定向回来,并附加 order_id(如果提供)、status 和 tracking_code 查询参数。
示例:
https://example.com/order?order_id=100001&status=confirmed&tracking_code=550e8400-e29b-41d4-a716-446655440000
请求参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
currency_symbol |
是 | string | 您的商户已启用的币种代码(例如 USDT、ETH)。 |
network_code |
是 | string | 所选币种的网络代码(例如 TRC20、ERC20、BEP20)。 |
amount_usd |
是 | number | 以 USD/USDT 计的金额 |
ttl |
是 | integer | 监控该交易的存活时间,单位为分钟。不能超过该币种的 max_ttl。 |
order_id |
否 | integer | 可选。如果提供,必须是 6 位数字。 |
email |
否 | string (email) | 可选,付款人邮箱。 |
comment |
否 | string | 可选,付款人备注。 |
callback_url |
否 | string (uri) | 可选。付款人在支付页面完成付款或付款失败后,VisualPay 会把其浏览器重定向到这个 HTTPS URL,并附加查询参数 order_id(创建时如有提供)、status 和 tracking_code。所有结果请使用同一个 URL,通过 status 参数区分。务必在服务端通过 Webhook 或“查询交易”接口核验付款状态,不要只依赖跳转。 |
请求示例
curl --location 'https://visualpay.net/api/v1/merchant/transaction/create?currency_symbol=value&network_code=value&amount_usd=value&ttl=value&order_id=value&email=value&comment=value&callback_url=value' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"currency_symbol":"USDT","network_code":"trc20","amount_usd":25.5,"ttl":15,"order_id":100001,"email":"payer@example.com","comment":"Invoice #1001","callback_url":"https://example.com/order"}'
响应示例
{
"status": 200,
"data": {
"payment_url": "http://127.0.0.1:6131/payment/AbC12XyZ",
"tracking_code": "AbC12XyZ",
"status": "pending",
"order_id": 1001,
"currency_name": "Tether",
"currency_symbol": "USDT",
"network": "tron",
"network_code": "trc20",
"network_name": "TRON (TRC20)",
"amount_usd": "25.50000000",
"pay_amount": "25.50000000",
"platform_share": "0.51000000",
"merchant_share": "24.99000000",
"payment_fee_percent": 1,
"payment_tolerance_percent": 1,
"wallet_address": "TXyz...",
"qr_code": "",
"expired_at": 0
},
"message": "success"
}
/api/v1/merchant/transaction/status
查询交易
按 tracking_code 查询。只返回属于当前已认证商户的交易。
请求参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
tracking_code |
是 | string | 创建交易时网关返回的跟踪码 |
请求示例
curl --location 'https://visualpay.net/api/v1/merchant/transaction/status?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'
响应示例
{
"status": 200,
"data": {
"order_id": 1001,
"status": "pending",
"tracking_code": "AbC12XyZ",
"payment_url": "https://pay.visualpay.net/AbC12XyZ",
"currency_code": "usdt_trc20",
"currency_name": "Tether",
"network_code": "trc20",
"network_name": "TRON (TRC20)",
"pay_amount": "10.00000000",
"amount_usd": "10.00000000",
"platform_share": "0.20000000",
"merchant_share": "9.80000000",
"payment_fee_percent": 1,
"payment_tolerance_percent": 1,
"paid_amount": "",
"is_canceled_by_user": false,
"tx_id": "",
"tx_explorer_url": "",
"email": "",
"comment": "",
"paid_at": 0,
"created_at": 0,
"expired_at": 0
},
"message": "success"
}
/api/v1/merchant/transaction/recheck
重新核验交易
对当前已认证商户名下已过期或已取消的交易重新核验链上付款。按 tracking_code 查询。
请求参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
tracking_code |
是 | string | 创建交易时网关返回的跟踪码 |
请求示例
curl --location 'https://visualpay.net/api/v1/merchant/transaction/recheck?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'
响应示例
{
"status": 200,
"data": {
"order_id": 1001,
"status": "pending",
"tracking_code": "AbC12XyZ",
"payment_url": "https://pay.visualpay.net/AbC12XyZ",
"currency_code": "usdt_trc20",
"currency_name": "Tether",
"network_code": "trc20",
"network_name": "TRON (TRC20)",
"pay_amount": "10.00000000",
"amount_usd": "10.00000000",
"platform_share": "0.20000000",
"merchant_share": "9.80000000",
"payment_fee_percent": 1,
"payment_tolerance_percent": 1,
"paid_amount": "",
"is_canceled_by_user": false,
"tx_id": "",
"tx_explorer_url": "",
"email": "",
"comment": "",
"paid_at": 0,
"created_at": 0,
"expired_at": 0
},
"message": "Transaction confirmed successfully."
}
/api/v1/merchant/transaction/cancel
取消交易
只有状态为 pending 的交易可以取消。
请求参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
tracking_code |
是 | string | 要取消的待付款交易的网关跟踪码。 |
请求示例
curl --location 'https://visualpay.net/api/v1/merchant/transaction/cancel?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY' \
--header 'Content-Type: application/json' \
--data '{"tracking_code":"AbC12XyZ"}'
响应示例
{
"status": 200,
"data": {
"order_id": 1001,
"status": "pending",
"tracking_code": "AbC12XyZ",
"payment_url": "https://pay.visualpay.net/AbC12XyZ",
"currency_code": "usdt_trc20",
"currency_name": "Tether",
"network_code": "trc20",
"network_name": "TRON (TRC20)",
"pay_amount": "10.00000000",
"amount_usd": "10.00000000",
"platform_share": "0.20000000",
"merchant_share": "9.80000000",
"payment_fee_percent": 1,
"payment_tolerance_percent": 1,
"paid_amount": "",
"is_canceled_by_user": false,
"tx_id": "",
"tx_explorer_url": "",
"email": "",
"comment": "",
"paid_at": 0,
"created_at": 0,
"expired_at": 0
},
"message": "Transaction cancelled successfully."
}
/api/v1/merchant/withdrawals/list
获取提现列表
分页返回提现记录。可选筛选条件:status 枚举值、日期范围(最长 30 天)。
请求参数
| 字段 | 必填 | 类型 | 说明 |
|---|---|---|---|
limit |
否 | integer | 每页条数(1–50) |
page |
否 | integer | 页码 |
from_date |
否 | string (date) | 开始日期(Y-m-d)。必须与 to_date 一起提供。最长范围 30 天。 |
to_date |
否 | string (date) | 结束日期(Y-m-d)。必须与 from_date 一起提供。最长范围 30 天。 |
status |
否 | enum | 可选。支持的取值:pending、processing、confirmed。 |
请求示例
curl --location 'https://visualpay.net/api/v1/merchant/withdrawals/list?limit=50&page=1&from_date=2026-07-01&to_date=2026-07-20&status=pending' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'
响应示例
{
"status": 200,
"data": {
"items": [
{
"tracking_code": "49e9f567-8c2a-4b1d-9f3e-2a1b0c9d8e7f",
"currency_name": "Tether",
"network_name": "TRON (TRC20)",
"destination_address": "TXyz...",
"amount_usd": "$98.50",
"status": "Processing",
"tx_id": "",
"tx_explorer_url": "",
"created_at": 0
}
],
"pagination": {
"page": 1,
"limit": 50,
"total": 120,
"last_page": 3
}
},
"message": "success"
}
交易状态
交易状态表示一笔付款当前所处的阶段。可能的取值包括:
pending
等待链上付款。
confirmed
付款已成功完成。
expired
付款窗口已过,付款未完成。
cancelled
交易已取消。