#Class: WantuPayClient

顽兔支付客户端。无全局状态，可创建多个实例。 方法名、参数名、返回字段与 Python 版 wantu_pay.py 及 HTTP 报文一字不差（都是 snake_case），不做键名转换。

#Constructors

#Constructor

new WantuPayClient(options): WantuPayClient

#Parameters

#options

WantuPayClientOptions

#Returns

WantuPayClient

#Properties

#api_secret

readonly api_secret: string

---

#base_url

readonly base_url: string

---

#merchant_id

readonly merchant_id: string

---

#timeout

readonly timeout: number

单次请求超时（秒）。

---

#webhook_secret

readonly webhook_secret: string | undefined

#Methods

#close_order()

close_order(params): Promise<OrderResult>

关闭未支付的单（out_trade_no 与 order_id 二选一）。

用户取消、改金额换单时调用：网关同步到渠道关单，旧二维码/支付链接随即失效，不用等超时。 已关闭的单幂等返回；已支付的单抛 WantuPayApiError（code=40902），按已支付处理（入账或退款）。

#Parameters

#params

OrderRef

#Returns

Promise<OrderResult>

---

#create_order()

create_order(params): Promise<CreateOrderResult>

创建支付单。同单号同参数幂等。

channel 选支付渠道：不传或 'alipay'＝支付宝（pay_url 是支付页地址，qrcode 模式嵌 iframe、 redirect 模式整页跳转）；'chinaums'＝银商，形态由 pay_mode 决定：'qrcode'＝聚合码（pay_url 是 二维码内容，前端渲染成码图、不能 iframe）；'redirect'＝公众号支付（微信/支付宝/云闪付 App 内 打开的 H5 页面把用户 302 到 pay_url，商户无需自有公众号）。

#Parameters

#params

CreateOrderParams

#Returns

Promise<CreateOrderResult>

---

#create_refund()

create_refund(params): Promise<RefundResult>

申请退款。out_refund_no 是幂等键，网络失败后用同一单号重试是安全的。

#Parameters

#params

CreateRefundParams

#Returns

Promise<RefundResult>

---

#query_order()

query_order(params): Promise<OrderResult>

查询支付单（out_trade_no 与 order_id 二选一）。回调之外的兜底手段。

#Parameters

#params

OrderRef

#Returns

Promise<OrderResult>

---

#query_refund()

query_refund(params): Promise<RefundResult>

查询退款。status 为 processing / succeeded / failed；failed 时多一个 fail_reason： rejected（商户后台拒绝）/ expired（超 14 天未审批自动拒绝）/ channel（支付渠道明确失败）。 refund.failed webhook 的 data 同样带 fail_reason。

#Parameters

#params

QueryRefundParams

#Returns

Promise<RefundResult>

---

#verify_webhook()

verify_webhook(headers, raw_body, tolerance_sec?): WantuWebhookEvent

验签并解析 webhook 事件。

raw_body 必须是请求体原文，字符串或 Buffer 都行（Express 用 express.raw() 后的 req.body 直接传）， 任何 JSON 解析要放在验签之后。验签失败抛 WantuWebhookVerifyError，此时不要处理业务， 返回非 2xx 状态即可，网关会自动重试。

返回的就是网关报文：event_type 为 'order.paid'、'refund.succeeded'、'refund.failed' 或测试事件 'webhook.ping'，业务数据在 event.data（字段与接口文档一致）。 入账前务必：核对 data.amount 与本地订单一致 + 以 out_trade_no 幂等。

#Parameters

#headers

HeadersLike

#raw_body

string | Uint8Array<ArrayBufferLike>

#tolerance_sec?

number = DEFAULT_TOLERANCE_SEC

#Returns

WantuWebhookEvent