简体中文 | English

koi_pay_kit

A universal, robust payment engine for Flutter. Supports any payment SDK through pluggable adapters with built-in order caching, crash recovery, polling verification, and guard mechanisms.

Why koi_pay_kit

Payment integration in Flutter is repetitive - every project rebuilds the same order caching, SDK invocation, result verification, and crash recovery logic.

koi_pay_kit solves this by providing a universal engine:

🔌 Pluggable SDK adapters — integrate any payment SDK (Alipay, WeChat Pay, Stripe, etc.)
🛡️ Pre-payment Guard — prevents duplicate payments on the same channel
💾 Crash recovery — orders cached before SDK invocation, survives app kills
🔄 Exponential backoff polling — automatic verification for "processing" states
📦 Channel isolation — independent caches per business channel
🔍 Silent reconciliation — recover() for startup self-healing
📊 Observable — optional PaymentLogger callback for monitoring
⏱️ Cache expiry — auto-purge stale orders (default 24h)

Installation

Add the package to your pubspec.yaml:

dependencies:
  koi_pay_kit: ^0.1.0

Then install dependencies:

flutter pub get

Quick Start

import 'package:koi_pay_kit/koi_pay_kit.dart';
import 'package:koi_pay_kit_alipay/koi_pay_kit_alipay.dart';

final engine = PaymentEngine(
  backend: MyOrderBackend(apiClient),
  sdks: {'alipay': AlipaySdk()},
  cache: SharedPrefsCache(prefs),
);

// Pay
final sn = await engine.pay(
  sdkId: 'alipay',
  title: '充值',
  amountInCents: 10000,  // 100.00 元
  channel: 2,
  payload: {'days': 30, 'count': 5},
);

// Step 4: your business logic
await myApi.recharge(sn: sn);
await engine.clearOrder(2);

Architecture

┌──────────────────────┐
│   Your App            │
│   ├ UI / Providers    │
│   └ OrderBackend impl │  ← You implement this
├──────────────────────┤
│   koi_pay_kit         │
│   └ PaymentEngine     │  ← Guard → Cache → Invoke → Verify → Poll
├──────────────────────┤
│   SDK Adapters        │
│   ├ koi_pay_kit_alipay│
│   ├ koi_pay_kit_wechat│  ← Future
│   └ koi_pay_kit_stripe│  ← Future
└──────────────────────┘

Interfaces

Interface	Purpose
`OrderBackend`	Server API: create orders + verify payments
`PaymentSdk`	SDK adapter: invoke native payment
`PaymentCache`	Persistence: read/write/delete cached orders

Configuration

PaymentEngine(
  // ...
  config: PaymentConfig(
    pollDelays: [2, 4, 8],        // exponential backoff (seconds)
    cacheExpireMs: 86400000,       // 24 hours
    enableGuard: true,             // prevent duplicate payments
    maxPollAttempts: 10,           // safety limit
  ),
  logger: (level, msg, [err]) => print('[$level] $msg'),
);

Recovery

Call recover() on page init to handle app kills during payment:

final recovery = await engine.recover(channel);
switch (recovery.status) {
  case RecoveryStatus.paymentConfirmed:
    await handleBusiness(recovery.cachedOrder!.sn);
    await engine.clearOrder(channel);
  case RecoveryStatus.expired:
  case RecoveryStatus.paymentFailed:
  case RecoveryStatus.noCachedOrder:
    break; // nothing to do
  case RecoveryStatus.needsManualRecovery:
    showRecoveryBanner(recovery.cachedOrder!);
}

Main Public APIs

PaymentEngine — core payment orchestrator
PaymentSdk — SDK adapter interface
OrderBackend — server API interface
PaymentCache — persistence interface
SharedPrefsCache — built-in SharedPreferences implementation
PaymentConfig — engine configuration
PaymentLogger — logging callback
PaymentOrder, OrderRequest, CachedOrder — models
SdkPayResult, VerifyResult, RecoveryResult — result models
PaymentPhase, PendingOrderException, PaymentException — flow types

Documentation

License

MIT. See LICENSE.