{"openapi":"3.1.0","info":{"title":"BuffPayment Merchant API","version":"0.1.0","description":"商户通过统一 API 创建和查询 CEX 支付订单。首期渠道为 Binance Pay，结算资产仅支持 USDT。"},"servers":[{"url":"https://api.buffpayment.com","description":"当前运行环境"}],"tags":[{"name":"Payments","description":"支付订单"}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"x-api-key"},"ApiSecret":{"type":"apiKey","in":"header","name":"x-api-secret"}},"schemas":{"CreatePaymentRequest":{"type":"object","additionalProperties":false,"required":["merchantOrderNo","amount","currency","description"],"properties":{"merchantOrderNo":{"type":"string","pattern":"^[A-Za-z0-9]{1,32}$","example":"ORDER202608170001","description":"商户侧唯一订单号；重复提交会返回原订单。"},"amount":{"type":"number","exclusiveMinimum":0,"maximum":1000000,"example":25.17},"currency":{"type":"string","const":"USDT"},"description":{"type":"string","minLength":1,"maxLength":256,"example":"Example order"},"terminalType":{"type":"string","enum":["APP","WEB","WAP","MINI_PROGRAM","OTHERS"],"default":"WEB"}}},"Payment":{"type":"object","properties":{"id":{"type":"string","example":"cm_example_payment_id"},"merchantOrderNo":{"type":"string","example":"ORDER202608170001"},"provider":{"type":"string","enum":["BINANCE_PAY"]},"amount":{"type":"string","example":"25.17000000"},"currency":{"type":"string","example":"USDT"},"status":{"type":"string","enum":["CREATED","PENDING","PAID","EXPIRED","FAILED","CLOSED","REFUNDED"]},"checkoutUrl":{"type":["string","null"],"format":"uri","description":"跳转至渠道收银台的地址。"},"providerExpiresAt":{"type":["string","null"],"format":"date-time"},"paidAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}},"security":[{"ApiKey":[],"ApiSecret":[]}],"paths":{"/api/v1/payments":{"post":{"tags":["Payments"],"summary":"创建支付订单","description":"按 merchantOrderNo 幂等创建 USDT 支付。真实模式调用 Binance Pay；本地 PAYMENT_MODE=mock 时生成模拟待支付订单。","operationId":"createPayment","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentRequest"}}}},"responses":{"200":{"description":"幂等命中，返回已有订单","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"201":{"description":"创建成功","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"400":{"description":"参数无效","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"API 凭证无效或商户不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"支付渠道创建失败","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/payments/{id}":{"get":{"tags":["Payments"],"summary":"查询支付订单","operationId":"getPayment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"BuffPayment 支付订单 ID。"}],"responses":{"200":{"description":"订单详情","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"401":{"description":"API 凭证无效或商户不可用","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"订单不存在或不属于当前商户","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}