> ## 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 收银台上实际需要填写什么：您传入的信息是否会被预填、何时会跳过支付方式选择页、卡表单的校验规则与长度、已保存卡片的表现、二维码有效期，以及哪些收银台错误会重试、哪些会直接跳转到失败页。

本页说明客户需要输入什么，以及出错时会发生什么。哪些支付方式会展示、以什么顺序展示，见「收银台支付方式展示规则」页面；页面级品牌定制见「客制化收银台」文档；重新打开的链接、处理中状态和结果页跳转见「收银台页面生命周期与收据」页面。

## 我在创建订单时已经传了客户的邮箱和姓名，为什么收银台还要客户再填？

因为复用您传入的信息是一个**账户级设置，默认关闭**，并且按字段逐个设置。在您的账户开启该设置之前，收银台把您传的值当作支付所需的数据，而不是要展示回给客户的内容。

之所以这样设计：相当一部分集成会传入占位的或合成的联系方式。在最关键的时刻把一个明显虚假的邮箱展示给买家，会损害信任，而且其中一些值在下游本来也会被拒绝。按字段逐个开启可以避免这些值直接出现在买家面前。

可以复用的字段如下，逐个单独选择：

| 字段 |
| - |
| `userInfo.userEmail` |
| `userInfo.userPhone` |
| `userInfo.userFirstName` |
| `addressInfo.postcode` |
| `addressInfo.address` |
| `addressInfo.city` |
| `addressInfo.region` |
| `addressInfo.addressCountryCode` |

另有一个互斥的 **none** 选项：要么列出字段，要么声明不复用任何字段。不能把"none"与字段列表同时使用。

请注意，first name 承载的是完整姓名——如果您只传 first name 而不传 last name，last name 会以空值存储，而不会被猜测填充。

要为您的账户修改此设置，请联系您的 Waffo 对接人，并提供希望复用的字段列表。

## 如果客户修改了我传的邮箱，你们用哪个值？

用客户的。买家在收银台页面上修改的值，会在该次支付的后续流程中替代您传入的值，包括传递给支付方式的值。这是有意设计的：买家最清楚自己的联系方式，而对于需要校验地址或发送确认的支付方式，使用过期的值会导致支付失败。

您原始的订单数据不会改变——如需知道您最初传了什么，请查看订单记录。

## 回头客每次都要重新填写所有信息吗？

不需要。存在两种独立的机制，容易混淆：

| 机制 | 谁的数据 | 由谁控制 |
| - | - | - |
| **已保存信息** | 客户在上一次购买时填写的内容 | 客户，通过表单上的"保存我的信息"选项 |
| **商户预填** | 您在订单上传入的内容 | 上文所述的您的账户设置 |

## 收银台什么时候会跳过支付方式选择页？

三条规则，按以下顺序判断：

| 情况 | 客户首先看到的 |
| - | - |
| 订单解析出**恰好一个分组，且是卡分组** | 直接显示卡表单 |
| 订单解析出**恰好一个分组、且该分组恰好只有一种支付方式**，并且该方式需要填写表单 | 直接显示该方式的表单 |
| 其他任何情况 | 选择页 |

除此之外，如果您在订单上传了 `payMethodId` 且该方式需要输入信息，收银台会直接打开该方式的表单而不是选择页。如果您传的 `payMethodId` 不需要输入信息，则其所属分组会在选择页上被预选。

未传 `payMethodId` 时，预选的是第一个有可用方式的分组中的**第一个可用**方式——不可用的方式永远不会被预选。

## 卡表单的校验规则具体是什么？

| 字段 | 规则 |
| - | - |
| 卡号 | 必填。显示长度为 **17–23 个字符**，包含输入过程中字段自动插入的空格 |
| 有效期 | 必填。恰好 **5 个字符**（`MM/YY`），且日期必须在未来 |
| CVV | 必填。长度取决于卡品牌——见下文 |
| 持卡人姓名 | 必填。最多 **100 个字符**。仅限拉丁字母 |

一旦卡号能识别出品牌，CVV 长度就按品牌确定：

| 品牌 | CVV 长度 |
| - | - |
| American Express | 恰好 4 位 |
| Visa | 恰好 3 位 |
| Mastercard | 恰好 3 位 |
| 品牌尚未识别，或其他 | 接受 3–4 位 |

因此，卡号未输完时被接受的 CVV，在品牌识别出来后可能变为无效。这是预期行为。

## 好几个字段都填错了，为什么我只看到一条错误提示？

每个字段**最多显示一条提示**——即它未通过的第一条规则，顺序为 必填 → 格式 → 过短 → 过长。提示在字段被交互过之后才会出现；点击支付按钮会把所有字段标记为已交互，因此提交时每个未通过的字段都会显示各自的一条提示。

有一种情况表现不同。**"This card is currently not supported"** 是在输入卡号的过程中实时校验的，所以可能在离开该字段之前就出现。但它仍然是卡号字段上的一条提示，这意味着卡号本身的长度或格式问题会先被报出——修正卡号之后，剩下的才是不支持该卡的提示。

该提示表示卡本身超出支持范围（其卡种、品牌或发卡地区不被接受），而不是表单格式有误。您可能在同一字段上看到的相关错误码：

| 错误码 | 含义 |
| - | - |
| `008001B027` | 当前不支持该卡 |
| `008001B028` | 不支持该卡的卡种 |
| `008001B029` | 不接受该卡的发卡地区 |
| `008001B030` | 不支持该卡的品牌 |
| `008001B125` | 持卡人姓名只能包含英文字母 |

## 已保存卡片的客户会看到什么？

如果您在订单上传了 `userPaymentAccessToken`，收银台会直接进入一个简短的完成步骤：卡片以掩码形式显示，客户**唯一**需要输入的字段是 **CVV**。卡号查询步骤会被完全跳过，因此该页面不会有逐字符输入的卡校验。

如果您**没有**指定支付方式，选择页会列出该客户在您账户下已关联的卡片，以及添加新卡的选项。每个客户在每个商户下可以有一张默认卡，收银台会预选它。您也可以通过 API 限制在某笔订单上提供哪些已保存的卡。

已移除或已过期的 token 会被拒绝，而不是被静默忽略——错误码 `008001B113` 表示该卡已被移除。

## 客户可以选择保存卡片供下次使用吗？

表单上会提供保存选项，是否显示取决于支付方式和您的账户：

| 支付方式类型 | 保存选项在以下情况出现 |
| - | - |
| 信用卡 / 借记卡 | 您的账户已为该方式开启保存卡片 |
| 其他所有方式 | 您的账户已开启保存客户输入的信息 |

您也可以从订单侧驱动：`paymentInfo.bindForFutureUse`（`0` = 否，`1` = 是）要求在该次支付中绑定支付方式以供将来使用。不会有任何静默保存——客户会在表单上看到该选项。

已保存的卡片之后在哪里出现、以及之后如何对其扣款，见 tokenization 文档。

## 我在订单上传了固定的卡号前缀，表单会有变化吗？

会。当订单固定了卡号的前几位数字时，收银台会把这些数字作为不可编辑的前缀渲染在输入框前面，卡号字段可接受的长度会恰好减少已显示的位数。客户只需输入剩余部分，总的可接受长度不变。

## Sandbox 收银台有测试卡吗？

有。在 Sandbox 环境中，卡表单在字段上方显示快速填充的卡片标签；点击一个即可填入卡号、有效期、CVV 和姓名。它们只在 Sandbox 环境渲染——没有任何代码路径会在生产环境中显示它们，因此上线前无需关闭任何东西。

## 客户可以先保存二维码，之后再付款吗？

不可以，这一点值得写进您自己的客服话术里。

* 二维码**仅对该次支付尝试有效**。它不是可复用的收款地址，不能用于之后的其他订单。
* 订单一旦过期或成功，重新打开收银台链接将完全不再显示二维码——链接会根据订单的真实状态解析到失败页或成功页。
* **保存二维码图片**按钮**仅在移动端**提供。桌面端不会渲染该按钮，因为桌面端保存的截图正是导致客户尝试支付已过期二维码的那种产物。

## 收银台页面显示了错误但一直在转圈，是卡住了吗？

不是——这是可重试路径。到达收银台的每个错误都带有一个可重试标志，页面对两类错误的表现不同：

| 错误类型 | 客户看到的 |
| - | - |
| **不可重试**——拒绝、限额、校验、链接过期 | 结果已是最终的：页面跳转到**失败页**并显示原因 |
| **可重试**——超时、系统错误、并发操作冲突 | 页面停留在**处理中视图**，显示原因，Waffo 在后台持续重试。重试产生结果后，页面会自行推进 |

在可重试路径上客户永远不需要重新提交，您也不应在其上再构建客户端重试。请以您收到的支付通知或订单查询作为最终状态的权威来源——而不是页面在某一时刻显示的内容。

## 我应该认识哪些收银台错误码？

完整列表很长，且大多由发卡行决定。以下是集成测试中常见、且原因在您或客户一侧的错误码：

| 错误码 | 提示文案 | 通常表示 |
| - | - | - |
| `008000S006` | Timeout. Please try again later | 临时性问题；可重试 |
| `008001B003` | Payment link expired. Please create another payment | 收银台链接的有效期已过 |
| `008001B007` | You have submitted, please refresh the page | 同一步骤的重复提交 |
| `008001B011` | Please input the correct phone number | 手机号格式被拒绝 |
| `008001B025` | Sorry your payment order has expired | 订单本身（而不只是链接）已过期 |
| `008001B049` | Order has expired, please place a new order | 同上，来自支付步骤 |
| `008001B058` | OTP has expired. Please request a new one | 一次性验证码已超时 |
| `008001B059` | OTP verification failed. Please try again | 一次性验证码错误 |
| `008001B092` | No payment methods are available for this region | 您的协议下没有任何支付方式匹配解析出的国家 |
| `008001B099` | The transaction currency is not supported | 解析出的支付方式未启用该币种 |
| `008001B101` | Invalid postcode | 邮编未通过该支付方式的格式检查 |
| `008001B116` | Receipt link expired | 收据链接已超过有效期；见收据文档 |
| `008001B124` | Today's verification attempts have reached the limit | 已达每日验证次数上限；客户需次日重试 |

`008001B03x`–`008001B09x` 范围内的错误码几乎都是发卡行或钱包的决定，原样转发。它们会按原样展示给客户；用同一支付工具重试无法把它们变成成功。

## 有些支付会要求客户填写邮箱或邮箱验证码，为什么？

某些支付方式在接受支付之前要求已验证的邮箱地址，因此收银台会收集邮箱，并在需要时通过发送到该地址的一次性验证码进行验证。这是所路由到的支付方式的要求，不是 Waffo 按商户额外添加的。

您可以预期：

* 如果您传了可用的 `userInfo.userEmail`，它可以预填该字段。对某些支付方式，该地址在该次支付中是固定的，客户无法替换——此时在同一步骤传入不同的地址会被拒绝。
* 一次性验证码有效期很短。验证成功后会在该订单上记住一段有限的时间，因此客户在完成支付过程中无需重复验证。
* 此步骤的邮箱地址上限为 50 个字符。
* 客户在一次收银台会话中选择了支付方式后，该选择在该会话内固定不变。

***

看到一条无法复现的校验提示？
[联系客服](mailto:support@waffo.com)，并提供订单 ID、显示的确切错误码，以及客户使用的是移动端还是桌面端。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.