跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://waffo.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
响应码

Waffo API 响应格式： 
{
  "code": "0",
  "msg": "Success",
  "data": { ... }
}
  • code 为 "0" 表示成功
  • 失败时，code 为错误码字符串（例如 "A0003"、"E0001"）
  • 响应字段名为 msg（不是 message）

​
错误码分类

PrefixCategoryDescription
0Success—
AMerchant error参数错误、权限不足等
BUser error余额不足、支付超时等
CSystem error渠道拒绝、系统错误等
DRisk Control rejection交易被 Risk Control 拦截
EUnknown error关键：支付可能已成功
完整错误码列表请参阅 错误码速查。

​
E0001 Unknown Status 处理

这是最关键的异常场景。 当你遇到网络超时、连接中断，或服务端返回 E0001 时，支付状态未知。

​
原则

  • 不要假设失败：网络超时不代表支付没有成功
  • 不要自动关闭订单：支付可能已在 Channel 侧完成
  • 不要创建新订单：使用原始 paymentRequestId 进行查询

​
SDK 中的错误类型

LanguageUnknown status errorClient error
Node.jsWaffoUnknownStatusErrorWaffoError
JavaWaffoUnknownStatusExceptionWaffoException
Go*core.WaffoUnknownStatusError*core.WaffoError
SDK 只有两类错误。WaffoUnknownStatusError/Exception 表示支付可能已成功，而 WaffoError/Exception 表示客户端侧错误（配置、签名等）。

​
SDK 错误码

Error codeTypeDescription
S0001UnknownStatus网络错误（超时、连接失败）
E0001UnknownStatus服务端返回 unknown status
S0002Error公钥无效
S0003Error签名失败
S0004Error响应签名验签失败
S0005Error请求序列化失败
S0007Error私钥无效

​
处理流程

Network timeout / E0001 / WaffoUnknownStatusError
    │
    ▼
Query using the original paymentRequestId
    │
    ├── PAY_SUCCESS found    → Update local status to success
    ├── ORDER_CLOSE found    → Update local status to failure
    └── Still unknown        → Wait for Webhook notification

​
代码示例

import { WaffoUnknownStatusError, WaffoError } from '@waffo/waffo-node';

try {
  const response = await waffo.order().create(params);
  if (response.isSuccess()) {
    // code === "0"，处理成功
  } else {
    // API 返回错误码（如 A0003），可以安全处理为失败
  }
} catch (error) {
  if (error instanceof WaffoUnknownStatusError) {
    // 重要：支付可能已成功！先查询再决定
    const inquiry = await waffo.order().inquiry({ paymentRequestId });
    if (inquiry.isSuccess()) {
      const status = inquiry.getData().orderStatus;
      await updateOrderStatus(paymentRequestId, status);
    }
    // 如果查询也失败，等待 Webhook
  } else if (error instanceof WaffoError) {
    // 客户端错误（配置、签名），修复后可重试
    console.error('Client error:', error.errorCode, error.message);
  }
}