跳到主要内容

充值和补充系统

OmniCRM 充值系统提供一个 自助服务预付费充值门户，供客户通过 Self-Care Portal <self_care_portal> 添加信用或延长服务有效期。此功能通常用于：

  • 移动数据服务 - 预付费 SIM 卡和仅数据服务
  • 热点服务 - WiFi 热点 dongles 和便携式互联网设备
  • 固定无线服务 - 预付费互联网接入

另请参见：SIM Card Provisioning <concepts_sim_provisioning> 以获取有关移动服务配置和管理 SIM 库存的信息。

概述​

充值系统允许客户通过一个简化的多步骤结账流程购买额外的服务天数，并集成了 Stripe 支付处理。

主要特点：

  • 自助服务客户门户（无需员工干预）
  • 灵活的持续时间选择（1-30 天）
  • 购买前实时使用情况显示
  • Stripe 驱动的安全支付处理
  • 如果充值失败，自动退款
  • 发票和交易生成
  • 服务激活的配置系统集成

访问充值门户​

充值门户通过一个 公共 URL 访问，客户可以在不登录 CRM 的情况下访问：

客户如何访问：

  • 当余额低时通过 SMS 发送的直接链接
  • 印刷材料上的二维码
  • 自助服务门户上的链接
  • 客户支持共享

门户会根据客户请求的 IP 地址或 IMSI 自动检测客户的服务。

充值流程​

充值流程包括 4 个步骤：

第 1 步：数据选择​

客户选择他们想要购买多少天的服务。

界面：

  • 滑块控制 - 选择 1 到 30 天
  • 实时价格计算 - 根据选择显示总费用
  • 到期日期显示 - 计算并显示服务何时到期
  • 当前使用情况显示 - 在充值前显示剩余余额/到期时间

示例显示：

定价配置：

  • 每天的价格通过环境变量 REACT_APP_TOPUP_PRICE_PER_DAY 配置
  • 默认：每天下 $10 美元
  • 货币通过 REACT_APP_CURRENCY_CODE 设置

第 2 步：账单信息​

客户提供交易的联系信息：

  • 名
  • 姓
  • 电子邮件地址

这些信息用于：

  • 发票生成
  • 支付收据电子邮件
  • 交易记录
  • 退款处理（如有需要）

第 3 步：支付​

通过 供应商托管的支付表单（Stripe Elements，PayPal SDK）进行安全支付处理。

支持的支付方式：

  • 信用卡（Visa，Mastercard，Amex）
  • 借记卡
  • 数字钱包（Apple Pay，Google Pay，PayPal） 如果支付供应商��用

安全特性：

  • PCI 合规的支付供应商集成
  • OmniCRM 中不存储卡片详细信息
  • 支持 3D Secure 身份验证
  • 加密支付传输

支付流程：

  1. 显示安全支付表单并输入卡片信息
  2. 客户输入支付详细信息
  3. 通过配置的供应商处理支付
  4. 卡片立即收费
  5. 处理支付成功/失败

注意

如果支付成功但充值配置失败（例如，网络错误，OCS 无法访问），系统会自动向客户的支付方式发起 全额退款。

第 4 步：完成​

成功屏幕：

您的服务已延长。新到期日期：2025 年 1 月 17 日

收据已发送至：<customer@example.com> 交易 ID：TXN-123456

失败屏幕：

如果充值失败，系统会显示错误并自动处理退款：

我们无法完成您的充值。您的支付已被退款。

错误：无法连接到计费系统

请重试或联系支持。

后端处理​

当客户完成支付时，系统会自动执行以下操作：

1. 支付验证

系统验证：

  • 支付意图状态为 succeeded
  • 支付金额与选择的天数匹配（days × price_per_day）
  • 支付意图未被处理过（防止重复充值）

2. 充值操作

- API 端点：POST /oam/topup_dongle
- 验证 service_uuid 和 IMSI
- 调用 OCS/CGRateS 添加余额
- 创建配置作业（play_topup_hotspot）

3. 记录创建

系统创建多个数据库记录：

  • HotspotTopup 记录 - 跟踪充值交易
    • payment_intent_id
    • service_uuid
    • imsi
    • 购买的天数
    • topup_amount
    • 状态（成功/失败/退款）
  • 交易记录 - 财务交易
    • 标题：“热点充值 - 7 天”
    • 金额：topup_amount（正数）
    • 链接到 service_id 和 customer_id
  • 发票记录 - 支付发票
    • 包含充值交易
    • 标记为已支付
    • 支付参考：Stripe payment_intent_id
  • 支付交易 - 抵消信用交易
    • 标题：“支付 [发票标题]”
    • 金额：topup_amount（负数 - 信用）
    • 将发票支付链接到客户账户

4. 配置作业

创建一个配置作业，使用 playbook play_topup_hotspot，其：

  • 接受 days 变量
  • 连接到 OCS/CGRateS API
  • 向账户添加余额
  • 更新服务到期日期

示例 playbook 结构：

- name: Top up hotspot service
  hosts: localhost
  tasks:
    - name: Add balance to OCS
      uri:
        url: "{{ ocs_api_url }}/add_balance"
        method: POST
        body:
          imsi: "{{ imsi }}"
          days: "{{ days }}"
          service_uuid: "{{ service_uuid }}"

低余额通知​

系统可以在客户余额低时发送自动通知：

SMS 通知：

当 OCS 事件触发时（Action_Balance_Low，Action_Balance_Out，Action_Balance_Expired）：

电子邮件通知：

在 OCS/CGRateS 行动计划中配置以发送余额警报。

通知触发器：

  • Action_Balance_Low - 余额低于阈值（例如，剩余 2 天）
  • Action_Balance_Out - 余额耗尽
  • Action_Balance_Expired - 服务到期

每个通知都包括充值门户链接，以便客户轻松访问。

故障排除​

常见问题​

“支付系统不可用”

  • 原因： Stripe 库加载失败或无效的可发布密钥
  • 修复：
    • 检查 REACT_APP_STRIPE_PUBLISHABLE_KEY 是否正确设置
    • 验证 Stripe 账户是否处于活动状态
    • 检查浏览器控制台是否有 JavaScript 错误

“充值失败。正在退款...”

  • 原因： 配置作业失败（OCS 无法访问，playbook 错误等）
  • 修复：
    • 检查配置日志：GET /crm/provision/provision_id/<id>
    • 验证 OCS/CGRateS API 是否可访问
    • 检查 playbook play_topup_hotspot.yaml 是否有错误
    • 检查 Ansible 日志

“支付意图已处理”

  • 原因： 客户尝试重用相同的支付（���如，成功后刷新）
  • 修复： 这是为了防止重复计费而设计的。客户如有需要应开始新的充值。

“支付意图金额不匹配”

  • 原因： UI 计算与后端验证不匹配
  • 修复：
    • 验证 REACT_APP_TOPUP_PRICE_PER_DAY 是否与后端期望值匹配（默认 $10）
    • 检查货币配置是否一致
    • 清除浏览器缓存并重试

监控充值​

查看充值记录：

查询 HotspotTopup 表以查看所有充值尝试：

SELECT
  hotspot_topup_id,
  service_uuid,
  days,
  topup_amount,
  status,
  payment_intent_id,
  created
FROM hotspot_topup
WHERE status = 'Failed'
ORDER BY created DESC;

检查配置状态：

GET /crm/provision/provision_id/<provision_id>

显示充值配置作业的详细状态。

Stripe 仪表板：

在您的 Stripe 仪表板中监控支付、退款和失败的交易，地址为 <https://dashboard.stripe.com>

安全考虑​

支付安全：

  • 所有卡片数据由 Stripe 处理（PCI 级别 1 合规）
  • OmniCRM 数据库中不存储敏感支付数据
  • 支付意图防止未经授权的收费
  • 客户端和服务器端的金额验证

防欺诈：

  • 重复支付意图检测防止重复计费
  • IP 地址跟踪用于使用情况关联
  • IMSI 验证确保充值到正确的服务
  • 自动退款限制财务风险

访问控制：

  • 充值门户是公共的（设计如此 - 客户需要访问）
  • 使用端点需要有效的服务识别（IP 或 IMSI）
  • 后端验证防止任意服务充值
  • 管理员可以通过 CRM 界面查看所有充值记录

最佳实践​

对于运营商：

  1. 测试退款流程 - 定期测试失败场景以确保退款有效
  2. 监控失败的充值 - 设置高失败率的警报
  3. 保持 playbook 简单 - 充值 playbook 应快速且可靠
  4. 验证 OCS 连接 - 确保 OCS API 始终可访问
  5. 审查定价 - 根据需要更新 REACT_APP_TOPUP_PRICE_PER_DAY

对于客户：

  1. 收藏充值 URL - 需要时快速访问
  2. 保存低余额通知 - SMS 包含直接链接
  3. 保持电子邮件更新 - 收据发送至档案中的电子邮件
  4. 旅行前检查到期 - 在离开覆盖区域前充值

对于开发者：

  1. 处理 Stripe webhooks - 实现 webhook 处理程序以获取支付状态更新
  2. 实现幂等性 - 在处理之前始终检查 payment_intent_id
  3. 广泛记录 - 充值失败需要详细的故障排除信息
  4. 测试错误路径 - 验证退款自动化是否正常工作
  5. 监控性能 - 配置轮询应在 &lt;5 秒内完成

相关文档​

  • payments_process - 一般支付处理
  • concepts_provisioning - 配置系统概述
  • Payment System Guide <payment_system_guide> - 支付供应商集成详细信息
  • payments_transaction - 交易管理
  • payments_invoices - 发票处理