跳转到主要内容

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.

​
集成

如果你希望快速上线，推荐收银台集成（Checkout），无需处理敏感卡信息，集成工作量最小。
DIRECT_PAYMENT 是早期产品，目前基本不再使用。新商户直接接入 ONE_TIME_PAYMENT 即可。两者在系统对接层面没有差别，差异体现在业务关系上：
  • ONE_TIME_PAYMENT：Waffo 作为 PSP，提供完整收单服务（信息流 + 资金结算）
  • DIRECT_PAYMENT：Waffo 作为 ISV/PG，仅提供系统对接能力（不碰资金）
避免浮点精度问题。例如 0.1 + 0.2 = 0.30000000000000004，在金融场景中这是不可接受的。
  • 同币种下单：大部分币种精度需符合 ISO 4217（2 位小数），但 IDR、COP、KES、TWD 不允许有小数
  • 跨币种下单：所有币种金额精度符合 ISO 4217 即可，无例外
使用 cloudflared 或 ngrok 等隧道工具将本地端口暴露为公网 URL。

​
传参

  • 不传：用户到 Waffo 收银台选择支付方式
  • 卡类支付：建议 payMethodType="CREDITCARD,DEBITCARD"，不传 payMethodName。Waffo 根据用户输入的卡 BIN 自动确定卡组，一次创单同时支持 Visa/Mastercard、信用卡/借记卡
  • VA（虚拟账户）：建议 payMethodType="VA"，不传 payMethodName，用户到收银台选择银行
  • 指定具体支付方式：同时传 payMethodType 和 payMethodName，具体值可在 Portal 的 Payin 页面查询
详细传参规则见 收银台集成 - 自定义选项。
可以。如果没有收集用户邮箱，有两种处理方式：
  1. 使用固定格式上送，如 userId@examples.com（用实际 userId 替换）
  2. 联系 Waffo，由 Waffo 代为覆写为 userId@examples.com 格式（需获得商户授权）
上线后建议传入真实用户邮箱。避免使用 test 等字符或同一邮箱被多人使用，否则可能触发风控。
可以传。该字段控制用户在收银台提交订单的时间窗口（必须为 UTC+0 时区）。一旦订单提交到支付渠道后，过期时间由支付方式自身控制。极少数支付方式支持商户传入渠道侧过期时间，具体可登录 Portal 到 Payin 页面查看。
  • 同币种：商户定价币种与用户所在国家币种一致（如 IDR 定价 → 印尼用户用 IDR 支付）
  • 跨币种：商户定价币种与用户支付币种不同（如 USD 定价 → 印尼用户用 IDR 的 DANA 支付）
跨币种下单需要额外传 payMethodCountry（当 payMethodType 或 payMethodName 任一未指定时）。userCurrency 可以不传。
当希望收银台只展示指定国家的支付方式时传入。不传则展示商户合约下所有国家的可用支付方式。
  • 全球卡（CREDITCARD/DEBITCARD）：不要传，全球卡不属于任何国家
详细传参规则见 收银台集成 - 自定义选项。

​
支付

根据 orderAction.actionType 判断：
  • actionType = "WEB" → 取 webUrl
  • actionType = "DEEPLINK" → 取 deeplinkUrl
一般只会有 webUrl。如果传参 userTerminal=APP，部分需要外部授权的钱包类支付方式会返回 deeplink。
沙盒环境因使用模拟器，deeplink 无法唤起真实钱包 App，此效果需要在生产环境验证。
需要将用户引导到外部授权页面。URL 取自 orderAction，根据 actionType 取 webUrl 或 deeplinkUrl。
这个异常是因为调渠道出现网络超时，不确定创单是否成功。
  • 创单时：如果能确定用户在异常情况下不可能支付成功（如需要返回收银链接的支付方式），可以弃单
  • 退款时：必须使用相同的 refundRequestId 进行重试，不能弃单
参见 错误处理。
  1. 检查 notifyUrl 是否 HTTPS 且公网可达
  2. 检查回调端口是否为 80 或 443（Waffo 生产环境只支持标准端口）
  3. 检查响应 body 是否为 {"message": "success"}，Content-Type 是否为 application/json
  4. 检查响应是否包含 X-SIGNATURE Header
  5. 主动调用查询接口获取最新状态
  6. 如果持续收不到，联系 Waffo 技术支持
强烈建议接入。使用场景：
  • 用户跳转到成功/失败页时主动查询，给用户最顺畅的体验
  • 对历史订单做订单回溯
  • Webhook 验签不通过时，通过查询接口兜底获取结果
不指定 payMethodType / payMethodName 时，收银台会展示所有可用的支付方式，用户自行选择。

​
签名 & 安全

  1. 私钥格式不正确：必须是 PKCS#8 格式
  2. 签名内容不正确：需要对 HTTP body 全部做加签，不能只签部分字段
2048 位 RSA 密钥对，使用 SHA256WithRSA（RSASSA-PKCS1-v1_5 + SHA-256）签名算法。
不建议。沙盒和生产应使用不同的 API Key 和 RSA 密钥对。

​
App 集成

  • 确认 App 和 WebView 是否允许打开外部 App 或外部浏览器页面
  • 确认 App 和 WebView 是否支持下载、复制、长按保存等能力，QR、OTC、银行转账等支付方式可能依赖这些能力
  • 确认原生 App 和 WebView 之间传递 URL 时完整保留 query 参数
  • 使用 WebView 加载时，userTerminal 应传 APP
  • 详细限制参见 支付方式集成注意事项
不推荐。建议直接使用 Waffo 收银台内置的 GP/AP 能力，无需商户自行集成。
对比项使用 Waffo 收银台商户自行集成
开通 GP/AP 开发者账号不需要需要
域名注册验证需要需要
管理加密证书/密钥Waffo 负责商户自行管理
服务端处理/解密 TokenWaffo 负责商户自行处理
PCI DSS 合规不需要可能需要
收银台 UIWaffo 提供商户自行开发
集成复杂度低高
如有特殊需求必须自行集成，请联系 Waffo 技术支持获取详细接入指南。
会唤起 PayMe App。如果用户没有安装，会提示下载。