koi_pay_kit 0.1.1

A universal payment engine for Flutter with pluggable SDK adapters, order caching, crash recovery, polling verification, and guard mechanisms.

简体中文 | 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

• Quick Start
• Changelog

License

MIT. See LICENSE.