{"openapi":"3.0.0","info":{"title":"OpenCryptoPay Payment Gateway API","version":"1.0.0","description":"企业级非托管加密货币支付网关接口规范。原生支持 USDT (TRC-20 / BEP-20 / Polygon / ERC-20 / Arbitrum)，提供订单创建、状态查询、动态二维码、异步通知及易支付兼容网关。","contact":{"name":"OpenCryptoPay Support","url":"https://cpay.bot.cd"}},"servers":[{"url":"https://cpay.bot.cd","description":"当前网关服务器"}],"paths":{"/api/v1/order/create":{"post":{"summary":"创建支付订单 (发起支付)","description":"商户系统调用此接口创建一笔加密货币支付订单，网关将返回专属应付金额 (带防撞尾数) 及收银台地址 pay_url。","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["out_trade_no","amount"],"properties":{"out_trade_no":{"type":"string","description":"商户唯一订单号","example":"SHOP_20261102_001"},"amount":{"type":"number","description":"订单请求金额 (USDT)","example":10},"network":{"type":"string","description":"结算区块链网络，支持 TRC20, BEP20, POLYGON, ERC20, ARBITRUM","default":"TRC20","example":"TRC20"},"token":{"type":"string","description":"支付代币符号，默认为 USDT","default":"USDT","example":"USDT"},"notify_url":{"type":"string","description":"商户接收异步支付结果通知的 Webhook 地址","example":"https://your-shop.com/api/payment/notify"},"redirect_url":{"type":"string","description":"用户支付成功后前端页面自动跳转的地址","example":"https://your-shop.com/order/success"}}}}}},"responses":{"200":{"description":"订单创建成功","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"message":{"type":"string","example":"Order created successfully"},"data":{"type":"object","properties":{"trade_no":{"type":"string","description":"网关系统唯一流水号","example":"PAY1793608327859ED99B4"},"out_trade_no":{"type":"string","description":"商户原始订单号","example":"SHOP_20261102_001"},"network":{"type":"string","example":"TRC20"},"token":{"type":"string","example":"USDT"},"amount":{"type":"number","description":"原始请求金额","example":10},"actual_amount":{"type":"number","description":"实际需转账金额 (包含尾数防撞锁定)","example":10.01},"receiver_address":{"type":"string","description":"收款钱包地址","example":"TG3XXyExBkPp9nzdajDZsozEu4B5U2U2AZ"},"status":{"type":"string","example":"PENDING"},"pay_url":{"type":"string","description":"收银台跳转 URL","example":"https://cpay.bot.cd/checkout.html?trade_no=PAY1793608327859ED99B4"},"expire_at":{"type":"integer","description":"订单过期时间戳 (毫秒)","example":1793610127859},"created_at":{"type":"integer","example":1793608327859}}}}}}}},"400":{"description":"请求参数错误"},"500":{"description":"服务器内部错误"}}}},"/api/v1/order/status/{trade_no}":{"get":{"summary":"查询订单支付状态","description":"商户或前端收银台通过系统流水号查询当前订单支付状态。","parameters":[{"name":"trade_no","in":"path","required":true,"description":"系统订单流水号","schema":{"type":"string","example":"PAY1793608327859ED99B4"}}],"responses":{"200":{"description":"查询成功","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"trade_no":{"type":"string","example":"PAY1793608327859ED99B4"},"out_trade_no":{"type":"string","example":"SHOP_20261102_001"},"network":{"type":"string","example":"TRC20"},"token":{"type":"string","example":"USDT"},"actual_amount":{"type":"number","example":10.01},"status":{"type":"string","enum":["PENDING","PAID","EXPIRED","FAILED"],"example":"PAID"},"tx_id":{"type":"string","nullable":true,"description":"链上交易哈希 Hash","example":"8f3e2b9c7d4a1..."},"paid_at":{"type":"integer","nullable":true,"example":1793608400000},"expire_at":{"type":"integer","example":1793610127859}}}}}}}},"404":{"description":"订单未找到"}}}},"/api/v1/order/qrcode/{trade_no}":{"get":{"summary":"获取支付二维码","description":"获取对应订单收款地址与转账协议生成的二维码 Base64 Data URL。","parameters":[{"name":"trade_no","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"成功返回二维码","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","example":200},"data":{"type":"object","properties":{"qr_code":{"type":"string","example":"data:image/png;base64,iVBORw..."},"uri":{"type":"string","example":"tron:TG3XX...AZ?amount=10.01&token=USDT"}}}}}}}}}}},"/submit.php":{"get":{"summary":"易支付协议 - 发起支付","description":"标准易支付接口，支持独角数卡、WordPress WooCommerce、WHMCS、发卡网一键对接。","parameters":[{"name":"out_trade_no","in":"query","required":true,"schema":{"type":"string"}},{"name":"money","in":"query","required":true,"schema":{"type":"number"}},{"name":"type","in":"query","schema":{"type":"string","example":"usdt"}},{"name":"notify_url","in":"query","schema":{"type":"string"}},{"name":"return_url","in":"query","schema":{"type":"string"}}],"responses":{"302":{"description":"重定向至收银台页面"}}}}},"components":{"schemas":{"WebhookPayload":{"type":"object","description":"商户 notify_url 收到的 POST 异步通知体 (带 HMAC-SHA256 签名)","properties":{"trade_no":{"type":"string","example":"PAY1793608327859ED99B4"},"out_trade_no":{"type":"string","example":"SHOP_20261102_001"},"network":{"type":"string","example":"TRC20"},"token":{"type":"string","example":"USDT"},"amount":{"type":"string","example":"10"},"actual_amount":{"type":"string","example":"10.01"},"receiver_address":{"type":"string","example":"TG3XXyExBkPp9nzdajDZsozEu4B5U2U2AZ"},"status":{"type":"string","example":"PAID"},"tx_id":{"type":"string","example":"8f3e2b9c7d4a1..."},"paid_at":{"type":"integer","example":1793608400000},"timestamp":{"type":"integer","example":1793608400100},"sign":{"type":"string","description":"参数字典排序后的 HMAC-SHA256 签名串","example":"e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"}}}}}}