goodsInfo、addressInfo 和若干 userInfo
字段标记为可选,其底层对象也确实只有长度限制——没有
必填约束。然而,一个通过了 schema 校验的请求仍可能返回
A0003 Parameter validation failed 并指出其中某个字段。下文使用的 payMethodType 取值
列在数据参考中。
为什么标记为可选的字段会因缺失被拒绝?
因为”必填”不是 API 的属性——它是实际使用的支付 方式加上你所处场景的属性。一个集成发送卡支付,不需要goodsInfo 里的任何内容;另一个发送分期付款,需要完整的逐项商品清单。单一的
schema 无法同时标记两者。由此产生两个后果:
- 字段要求不是仅由支付方式决定的稳定函数。 同一种 方式可能根据支付的处理方式要求不同的字段,而且这个集合可能在你这边没有任何改动的情况下发生变化,所以在 集成中硬编码的按方式列表会悄无声息地过时。
- 没有预检发现端点。
/api/v1/paymethodconfig/inquiry返回可用性、维护窗口、金额范围、币种和退款政策—— 它不返回字段要求。
那么正确的做法是什么?
提交、读取列表、重新发送。不要预判。- 带上你已持有的所有信息发送请求。
- 如果缺少必填字段,调用会以
A0003失败。专门针对A0003, 响应的msg会在括号中附带字段级详情;在/api/v1/order/refund上,缺失的路径还会以missingFields列表返回。 - 精确填入这些路径并重新发送。
userInfo.userFirstName、addressInfo.postcode、
goodsInfo.goodsUniquePrice——因此可以直接映射到你的请求体。
如果你使用托管收银台,通常永远不会遇到这个问题。 当所选方式
需要你未提供的字段时,Waffo 会把订单路由到收银台,由收银台
为买家渲染这些输入项。上述循环在没有
收银台可回退的场景下最为重要:商户发起的交易(merchantInitiatedMode)和
直接结算的代理支付。
缺失字段列表中可能出现哪些字段路径?
大致上各类支付方式会要求什么?
仅供参考——有助于评估你的数据收集工作量,不是契约。以 返回的列表为准。同一种方式类型的要求还会因市场而异,这也是 静态列表站不住脚的另一个原因。其中哪些实际上是无条件必填的?
不要在本来就是必填的字段上花精力。在/api/v1/order/create 上,
userInfo.userId、userInfo.userTerminal 和 orderDescription 对每个
请求都是必填的。userInfo.userEmail 实际上也是必填的:如果没有收集到真实地址,
请发送 userId@examples.com 形式的唯一兜底值——绝不要用共享或占位
值,那可能触发风控。在 goodsInfo 内,契约要求要么传
goodsUrl 要么传 appName(不能都传)用于合规和风控审核;创建调用
本身不会因它们缺失而拒绝——只有支付方式的条件规则
会通过上述缺失字段列表来拒绝。
由场景而非支付方式驱动的要求
由你如何集成触发,并在任何支付方式特定规则运行之前检查:退款使用同一份列表吗?
不是。退款有自己的检查,可能要求支付从不需要的身份和付款信息, 因为资金往往通过转账退回,而不是在原支付上做冲正 ——这也是退款请求接受userInfo(包括
userBankInfo)、addressInfo 和 extendInfo 的原因。同样的提交-读取循环。
字段已经传了但仍被拒绝,为什么?
格式规则适用于你发送的每个字段,无论它是否被要求:
长度限制是另一回事,在收单规范中按字段列出,
同样会产生指明字段的
A0003。
按响应要求的内容原样重新发送后仍然被阻塞? 联系支持,附上
paymentRequestId 和完整的
A0003 消息。