API 文档 (v1.0.0) OpenAPI (Swagger)

加密货币支付 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 上。

基础 URL https://visualpay.net/

回调跳转

如果在“创建交易”时提供了可选的 callback_url,支付页面会在付款进入最终状态后把付款人的浏览器重定向到您的 URL。所有结果共用同一个 URL,成功与失败通过 status 查询参数区分。

附加到您 URL 上的查询参数

网关会把下表中的参数附加到您的回调 URL 上,您的应用无需再次调用 API 就能识别订单及其最终结果。

参数 说明
order_id 创建交易时提供的订单 ID(如有)。
status 最终付款状态:confirmed、expired 或 cancelled(与“查询交易”API 的取值相同)。
tracking_code 用于核验的 VisualPay 交易 UUID。

跳转示例

url
https://example.com/order?order_id=100001&status=confirmed&tracking_code=550e8400-e29b-41d4-a716-446655440000
重要: 回调跳转只用于改善浏览器端体验。在履行订单之前,您的后端仍然必须通过 Webhook 或“查询交易”接口确认付款。如果没有提供 callback_url,付款人会留在 VisualPay 的支付页面上。

跳转时机:付款确认后会先显示 3 秒成功提示再跳转;付款过期或取消时立即跳转。

身份验证

调用 VisualPay 商户 API 时,每个请求都需要使用商户 API 密钥进行身份验证。请在 VisualPay 面板中创建商户,并从商户设置中复制 API 密钥。

安全提示: 请妥善保管您的 API 密钥。密钥只在生成时显示,不应出现在客户端代码中。

每个请求都需要商户 API 密钥。

所有 API 请求都需要在 x-api-key HTTP 请求头中携带您的商户 API 密钥。

http
x-api-key: YOUR_MERCHANT_API_KEY
GET /api/v1/merchant/currencies/list

获取支持的币种

返回当前已认证商户启用的币种和网络。

请求示例

bash
curl --location 'https://visualpay.net/api/v1/merchant/currencies/list' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

响应示例

json
{
    "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"
}
GET /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。

请求示例

bash
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'

响应示例

json
{
    "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"
}
POST /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 或“查询交易”接口核验付款状态,不要只依赖跳转。

请求示例

bash
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"}'

响应示例

json
{
    "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"
}
GET /api/v1/merchant/transaction/status

查询交易

按 tracking_code 查询。只返回属于当前已认证商户的交易。

请求参数

字段 必填 类型 说明
tracking_code 是 string 创建交易时网关返回的跟踪码

请求示例

bash
curl --location 'https://visualpay.net/api/v1/merchant/transaction/status?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

响应示例

json
{
    "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"
}
GET /api/v1/merchant/transaction/recheck

重新核验交易

对当前已认证商户名下已过期或已取消的交易重新核验链上付款。按 tracking_code 查询。

请求参数

字段 必填 类型 说明
tracking_code 是 string 创建交易时网关返回的跟踪码

请求示例

bash
curl --location 'https://visualpay.net/api/v1/merchant/transaction/recheck?tracking_code=AbC12XyZ' \
--header 'x-api-key: YOUR_MERCHANT_API_KEY'

响应示例

json
{
    "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."
}
POST /api/v1/merchant/transaction/cancel

取消交易

只有状态为 pending 的交易可以取消。

请求参数

字段 必填 类型 说明
tracking_code 是 string 要取消的待付款交易的网关跟踪码。

请求示例

bash
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"}'

响应示例

json
{
    "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."
}
GET /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。

请求示例

bash
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'

响应示例

json
{
    "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

交易已取消。

最佳实践: 付款人返回您的网站后,请先调用“查询交易”接口确认最终付款状态,再履行订单。