使用 Pay2S 配置银行收款
连接银行账户、创建 Pay2S webhook、保存密钥并在 ChatHub 中配置收款信息，实现钱包自动充值。
Pay2S 与 ChatHub 如何配合#
当客户走到工作流中的“通过 Pay2S 充值”步骤时，ChatHub 会生成一个以 NAP 开头的参考代码，并发送转账说明。Pay2S 监听已连接的银行账户，把进账交易推送给 ChatHub；金额为正且带有正确代码的转账会被记录，并计入客户钱包。
- 1
把收款银行账户连接到 Pay2S。
- 2
在 Pay2S 中用 ChatHub 提供的地址创建一个“进账”webhook。
- 3
复制 webhook 密钥，与收款银行信息一起保存到 ChatHub。
- 4
使用带有“通过 Pay2S 充值”步骤的工作流，然后用一笔包含准确参考代码的测试转账进行验证。
1. 准备账号和公网地址#
- 1
一个可以打开 管理 → 设置 → 支付 的 ChatHub 账号。
- 2
一个正常使用的 Pay2S 账号，以及 Pay2S 支持的银行账户。请准备好网银登录信息、账户持有人资料，以及可能需要的 OTP 接收方式。
- 3
一个可从公网访问、带 HTTPS 的正式 ChatHub 域名。正式的 webhook 不能使用 localhost 或只在本机可用的 DDEV 域名。
- 4
选定收款账户。在 ChatHub 中填写的银行、账号和持有人必须与之一致，客户才能收到准确的转账说明。
2. 在 Pay2S 中连接银行账户#
- 1
在 Pay2S 客户中心打开 Ngân hàng（银行）→ Thêm tài khoản（添加账户）。
- 2
查看各家银行支持的账户类型：个人、个体工商户或企业。在对应的银行行上点击 Kết nối（连接）。
- 3
选择该银行提供的 API 方式，填写所有要求的信息，并在接受服务条款前先阅读。
- 4
如有要求请完成 OTP 验证。返回“银行”页面，确认新账户处于可用状态后再创建 webhook。
3. 从 ChatHub 复制 webhook 地址#
- 1
在 ChatHub 中打开 管理 → 设置，选择“支付”。
- 2
在“银行转账”下展开 Pay2S。
- 3
在“Webhook 地址”处点击复制。它的格式为 https://你的-chathub-域名/api/payments/pay2s/webhook。
- 4
粘贴到 Pay2S 之前，请确认它使用的是你对外可访问的正式 HTTPS 域名。
4. 在 Pay2S 中创建进账 webhook#
- 1
回到 Pay2S，打开 Webhooks → Danh sách webhook（webhook 列表），点击 Thêm webhook（添加 webhook）。
- 2
取一个便于识别的名称，例如 ChatHub - incoming。
- 3
事件选择 Tiền vào（进账），并选择第 2 步中已连接的银行账户。
- 4
把 ChatHub 的地址粘贴到 Gọi đến URL（webhook 地址）。
- 5
可选的支付代码结构请保持为 Không giới hạn theo mã thanh toán（不按支付代码限制），这样 ChatHub 才能匹配转账备注中的 NAP 代码。本钱包充值流程不需要填写发票信息。
- 6
核对账户、事件和地址，然后点击 Thêm webhook。
5. 复制密钥并保存 ChatHub 设置#
- 1
创建 webhook 后请立即复制 Pay2S 显示的 token/密钥。Pay2S 文档说明它只在创建时显示一次。
- 2
回到 ChatHub 的 Pay2S 设置，把它粘贴到“Webhook 密钥”。
- 3
银行、账号和持有人要与 Pay2S 中收款账户完全一致。工作流会把这三项信息写进给客户的转账说明。
- 4
点击保存，等待支付设置已保存的提示。Pay2S 卡片应显示“已配置”。
6. 在钱包充值工作流中使用 Pay2S#
- 1
打开 自动化 → 工作流，选择需要提供银行转账的销售或充值工作流。
- 2
添加或检查“通过 Pay2S 充值”步骤。若提示需要先配置 Pay2S，请回到第 5 步确认密钥已保存。
- 3
确认工作流发送的银行、账号、持有人、金额和参考代码都来自 Pay2S 步骤生成的正确内容。
- 4
在检查过成功、失败和取消路径之后再启用工作流。除非确有需要，避免多个工作流同时问候或处理同一位客户。
7. 验证转账识别与钱包入账#
- 1
用一个测试联系人走一遍“通过 Pay2S 充值”步骤，记下 ChatHub 给出的金额和 NAP 代码。
- 2
向正确的账户转入完全一致的金额，并把完整的 NAP 代码写进转账备注。一次测试只做一笔交易。
- 3
在 Pay2S 的“银行交易”中确认这笔进账，然后在 Webhooks → 交易记录 中查看是否已推送到 ChatHub。
- 4
在 ChatHub 中确认工作流继续执行、客户钱包按正确金额增加，并且余额记录中标明了支付网关。
8. 常见故障排查#
- 1
Pay2S 没有识别到转账：确认银行连接仍然有效、会话/OTP 未过期，并且该笔转账已出现在“银行交易”中。
- 2
webhook 没有触发：确认它已启用、事件为“进账”、选择了正确的账户，并调用的是公网 HTTPS 地址。可在 webhook 交易记录中查看响应。
- 3
ChatHub 返回 401：说明保存的密钥与 webhook token 不一致。请重新生成或复制 Pay2S 的 token，并把新值保存到 ChatHub。
- 4
webhook 已到达但钱包没有变化：检查金额是否为正、NAP 代码是否完整且对应一笔待处理的充值，以及该代码是否已被使用过。
- 5
给客户的说明不正确：在 ChatHub 中更新银行、账号或持有人并保存。只要 webhook 没变，密钥无需改动。
- 6
当接口没有返回 HTTP 200 时，Pay2S 会重试推送。不要把重复创建 webhook 当作常规处理办法，那会让对账变得复杂。
9. 保障集成安全#
- 1
严格限制支付设置和 Pay2S 账号的访问权限。
- 2
切勿通过邮件、群聊或公开文档分享密钥。一旦怀疑泄露，请立即更换 webhook token 并同步更新 ChatHub。
- 3
关注 webhook 交易记录中的失败和超时，在做人工调整之前先把银行转账与钱包变动对上账。
- 4
更换收款账户时，请先更新 Pay2S 的连接、webhook 所选账户以及 ChatHub 中的三个银行字段，再重新启用工作流。