@litepos/payment-fiuu

Fiuu CloudECR 支付网关适配器包

概述

本包实现了 Fiuu CloudECR 终端的支付集成，提供统一的支付接口供主包 @litepos/payment 调用。

核心特性

• ✅ 刷卡支付 - 支持信用卡/借记卡刷卡
• ✅ 扫码支付 - 支持商户展示二维码（Touch 'n Go, Alipay 等）
• ✅ 查询支付 - 使用 getLast 查询最后一笔交易
• ✅ 退款功能 - 使用 void 撤销交易
• ✅ 统一接口 - 符合 SDK 统一接口规范

实现设计

架构遵循

本包实现符合 docs/UPGRADE_DESIGN.md 的统一接口设计：

1. 立即返回 pending - charge() 立即返回 pending 状态，不阻塞 POS 应用
2. 后台处理 - 在后台继续等待 Fiuu CloudECR 的同步响应（最长 90 秒）
3. 轮询查询 - POS 通过 queryPayment() 轮询获取实际支付结果
4. 统一异步处理 - 虽然 Fiuu 是同步接口，但对 POS 应用表现为异步接口
5. 状态管理 - 内部维护 pending 交易状态，确保查询返回正确状态

核心函数

chargeCard(request: PaymentRequest)

• 立即返回 pending 状态（非阻塞）
• 在后台启动任务调用 Fiuu /transfer API（最长等待 90 秒）
• POS 应用可以显示等待动画，保持界面响应
• 必须配合 queryPayment() 轮询获取实际结果

chargeQrCode(request: PaymentRequest)

• 立即返回 pending 状态（非阻塞）
• 后台调用 Fiuu /transfer API 生成 QR 码
• POS 通过轮询 queryPayment() 获取 QR 码数据和支付状态

queryPayment(transactionId: string, config: unknown)

• 智能查询支付状态：
  1. 先检查是否有正在进行的后台任务
  2. 如果有且未完成，返回 pending
  3. 如果有且已完成，返回实际结果（success/failed）
  4. 如果没有，调用 Fiuu getLast API 查询终端
• 用于轮询，直到支付完成或失败

refund(transactionId: string, config: unknown)

• 调用 Fiuu /transfer API with Void
• Fiuu 退款为全额撤销（不支持部分退款）
• 立即返回退款结果

API 映射

| SDK 方法 | Fiuu API | Transaction Type | 说明 | |---------|----------|------------------|------| | chargeCard | /transfer | Sale | 刷卡支付 | | chargeQrCode | /transfer | Sale (QR) | 扫码支付 | | queryPayment | /transfer | GetLast | 查询最后一笔 | | refund | /transfer | Void | 退款/撤销 |

配置

配置格式

使用嵌套格式 - 多个支付网关配置在同一对象中：

const config = {
  fiuu: {
    posId: 'xxx',
    password: 'xxx',
    secretKey: 'xxx',
    merchantId: 'xxx',
    deviceId: 'xxx',
  }
}

配置字段

interface FiuuConfig {
  posId: string // POS 终端 ID（来自激活邮件）
  password: string // API 密码（来自激活邮件）
  secretKey: string // 签名密钥（来自 Merchant Portal）
  merchantId: string // 商户 ID（Fiuu 分配）
  deviceId: string // 设备标识符（商户自定义）
  baseUrl?: string // API 地址（默认：https://cloudecr.fiuu.com）
  apiVersion?: string // API 版本（默认：v1）
  timeout?: number // 超时时间（默认：90000ms）
}

使用示例

import { LitePosPayment, PaymentStatus } from '@litepos/payment'

const payment = new LitePosPayment()

// 嵌套配置 - 支持多个支付网关
const config = {
  fiuu: {
    posId: 'B7S3ag9yjdvgWy3Q0cKFazyY',
    password: 'Xpos123!',
    secretKey: 'LczopHy1EPfWfuHOdIQPDBnUL7exXAEj',
    merchantId: 'hirectorpteltd_Dev',
    deviceId: 'kfXdUPPnED4KyzVatT2y',
  },
  // 可以添加其他支付网关配置
  // yeahpay: { ... },
}

// 1. 发起刷卡支付（立即返回 pending）
const result = await payment.charge({
  method: 'FIUU',
  amount: 100,
  currency: 'MYR',
  orderId: 'ORDER-001',
  config,
})

console.log(result.status) // 'pending'
// POS 可以显示等待动画...

// 2. 轮询查询支付状态
const intervalId = setInterval(async () => {
  const status = await payment.queryPayment('FIUU', result.transactionId, config)

  console.log(status.status) // 'pending' -> 'success' | 'failed'

  if (status.status !== PaymentStatus.Pending) {
    clearInterval(intervalId)

    if (status.status === PaymentStatus.Success) {
      console.log('✅ 支付成功', status.transactionId)
    }
    else {
      console.log('❌ 支付失败', status.metadata?.responseText)
    }
  }
}, 2000) // 每 2 秒查询一次

开发

# 在当前包目录
pnpm build      # 构建包
pnpm dev        # 开发模式
pnpm test       # 运行测试
pnpm typecheck  # 类型检查

# 从根目录运行
pnpm test       # 测试所有包

集成测试

# 运行真实 API 集成测试（需要实际终端）
pnpm test:integration

注意: 集成测试会调用真实的 Fiuu CloudECR API，需要：

• 终端设备已开机并在线
• 终端已绑定到 POS 账户
• 准备好测试卡或支付方式

文档

• API 文档: /docs/Fiuu API/ - Fiuu CloudECR API 官方文档
• 架构设计: /docs/ARCHITECTURE.md - 整体架构说明
• 升级设计: /docs/UPGRADE_DESIGN.md - 统一接口设计文档