@seaverse/payment-sdk 0.8.2 → 0.9.0

package/README.md

@@ -219,6 +219,164 @@ SDK 内置以下积分套餐：
 | Pro     | 520  | $1.99 | 专业套餐 |
 | Ultra   | 1200 | $4.99 | 旗舰套餐 |
 
+---
+
+### PaymentCheckoutModal - 完整收银台流程
+
+**适用场景**：
+- ✅ 需要完整的支付收银台体验（支付方式选择 + 订单信息展示）
+- ✅ 自动创建订单并完成支付
+- ✅ 支持三种支付方式：Link Payment、Dropin Payment、BindCard Payment
+- ✅ 适合需要更多控制和自定义的场景
+
+#### 基础用法
+
+```typescript
+import { PaymentCheckoutModal, type Product, type AutoCreateOrderConfig } from '@seaverse/payment-sdk';
+
+// 定义产品信息
+const product: Product = {
+  id: 'pkg_credit_100',
+  name: '100 Credits Package',
+  price: 9.99,
+  currency: 'USD',
+  type: 'credit_package',  // 'credit_package' | 'subscription' | 'change_subscription'
+};
+
+// 创建收银台 modal
+const modal = new PaymentCheckoutModal({
+  // 产品信息
+  product: product,
+
+  // 自动创建订单配置
+  autoCreateOrder: {
+    productId: product.id,
+    purchaseType: 1,              // 1=一次性购买, 2=订阅
+    apiHost: 'https://api.example.com',
+    accountToken: 'user-token',
+    clientId: 'your-client-id',
+    countryCode: 'SG',
+  },
+
+  // 可选配置
+  accountName: 'John Doe',        // 显示在订单信息中
+  language: 'en',                 // 'en' | 'zh-CN'
+
+  // 回调函数
+  onPaymentSuccess: (payload) => {
+    console.log('支付成功！', payload);
+    // payload 包含: orderId, transactionId, 等信息
+  },
+
+  onPaymentFailed: (error) => {
+    console.error('支付失败：', error.message);
+  },
+
+  onPaymentMethodSelect: (method) => {
+    console.log('选择支付方式：', method.name);
+  },
+
+  onLinkPaymentStart: (methodName) => {
+    console.log('Link 支付开始：', methodName);
+    // 可以在这里显示 "请在新窗口完成支付" 提示
+  },
+
+  onLoading: (loading) => {
+    console.log('加载状态：', loading);
+  },
+});
+
+// 打开收银台
+modal.open();
+```
+
+#### 三种初始化模式
+
+PaymentCheckoutModal 支持三种初始化模式（三选一）：
+
+**模式 1: autoCreateOrder（推荐）**
+```typescript
+const modal = new PaymentCheckoutModal({
+  product: { id: 'pkg_1', name: 'Product', price: 9.99, currency: 'USD', type: 'credit_package' },
+  autoCreateOrder: {
+    productId: 'pkg_1',
+    purchaseType: 1,
+    apiHost: 'https://api.example.com',
+    accountToken: 'token',
+    clientId: 'client-id',
+    countryCode: 'SG',
+  },
+  onPaymentSuccess: (payload) => { /* ... */ },
+});
+```
+
+**模式 2: payment（提前创建 OrderPayment 实例）**
+```typescript
+import { OrderPayment } from '@seaverse/payment-sdk';
+
+const payment = new OrderPayment({
+  transactionId: 'txn_123',
+  apiHost: 'https://api.example.com',
+  accountToken: 'token',
+});
+
+const modal = new PaymentCheckoutModal({
+  product: { /* ... */ },
+  payment: payment,
+  paymentMethods: [...],  // 需要手动提供支付方式列表
+  onPaymentSuccess: (payload) => { /* ... */ },
+});
+```
+
+**模式 3: transactionId（延迟初始化）**
+```typescript
+const modal = new PaymentCheckoutModal({
+  product: { /* ... */ },
+  transactionId: 'txn_123',
+  paymentMethods: [...],  // 需要手动提供支付方式列表
+  onPaymentSuccess: (payload) => { /* ... */ },
+});
+```
+
+#### 配置选项说明
+
+| 选项 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `product` | `Product` | 否 | 产品信息（id, name, price, currency, type） |
+| `autoCreateOrder` | `AutoCreateOrderConfig` | 三选一 | 自动创建订单配置（推荐） |
+| `payment` | `OrderPayment` | 三选一 | 提前创建的 OrderPayment 实例 |
+| `transactionId` | `string` | 三选一 | 订单 transaction_id（延迟初始化） |
+| `paymentMethods` | `PaymentMethod[]` | 否 | 支付方式列表（autoCreateOrder 模式会自动获取） |
+| `accountName` | `string` | 否 | 用户账号名称（显示在订单信息中） |
+| `language` | `'en' \| 'zh-CN'` | 否 | 语言设置（默认 'en'） |
+| `onPaymentSuccess` | `(payload) => void` | 否 | 支付成功回调 |
+| `onPaymentFailed` | `(error) => void` | 否 | 支付失败回调 |
+| `onPaymentMethodSelect` | `(method) => void` | 否 | 选择支付方式回调 |
+| `onLinkPaymentStart` | `(methodName) => void` | 否 | Link 支付开始回调 |
+| `onLoading` | `(loading) => void` | 否 | 加载状态回调 |
+
+#### 产品类型说明
+
+| 类型 | 值 | 说明 |
+|------|------|------|
+| 信用包 | `'credit_package'` | 一次性购买积分包 |
+| 订阅 | `'subscription'` | 新订阅购买 |
+| 变更订阅 | `'change_subscription'` | 订阅升级/降级 |
+
+#### 支付方式说明
+
+PaymentCheckoutModal 支持三种支付方式：
+
+1. **Link Payment**: 跳转到外部支付页面，自动轮询订单状态
+2. **Dropin Payment**: 嵌入式支付表单，支持信用卡、PayPal 等
+3. **BindCard Payment**: 使用已保存的卡片支付（显示卡片列表）
+
+#### 完整示例
+
+查看完整示例代码：`examples/payment-sdk-demo/src/components/new-sdk/PaymentCheckoutSection.tsx`
+
+---
+
 #### 环境配置
 
 SDK 根据 `environment` 自动配置以下参数：