LPE (Learmond Pay Element) SDK

A reusable Flutter SDK that provides a unified UI and helpers for collecting payments via stripe Elements, Apple Pay, Google Pay and the Source Pay button.

This README documents the SDK's major features and how to integrate and inegrate the package.

Major features

Composite payment widget: LearmondPayButtons (Card / Bank / Apple Pay / Google Pay)
Individual buttons: LearmondCardButton, LearmondUSBankButton, LearmondEUBankButton, LearmondApplePayButton, LearmondGooglePayButton, LearmondSourcePayButton.
Programmatic pay sheet: LearmondPaySheet.show(...)
Native device pay bridge: LearmondNativePay.showNativePay(...)
Merchant args helpers: buildMerchantArgs, buildMerchantArgsFromAmount
Lightweight merchant-args editor: Learmond.instance.presentMerchantArgs(...) (used by the example/test app)

Installation

Add the package to your pubspec.yaml (use local path for development):

flutter pub add lpe_sdk

Install dependencies:

flutter pub get

Note: The plugin uses native functionality for Apple/Google Pay; follow platform-specific setup steps for iOS and Android when integrating into a real app.

Initialization

Optionally set global defaults with LpeConfig before runApp(...):

void main() {
  LpeConfig.init(
    appleMerchantId: 'merchant.com.example',
    googleGatewayMerchantId: 'yourGatewayMerchantId',
    defaultMerchantName: 'My Shop',
    defaultMerchantInfo: 'Order',
  );
  runApp(const MyApp());
}

Usage

Use LearmondPayButtons to show a compact set of payment options; it handles wiring to Stripe and native pay flows for you.

LearmondPayButtons(
  publishableKey: 'pk_test_...',
  clientSecret: 'pi_..._secret_...',
  merchantId: 'merchant.com.example',
  merchantName: 'My Shop',
  merchantInfo: 'Order 1234',
  summaryItems: [
    SummaryLineItem(label: 'Subtotal', amountCents: 1000),
    SummaryLineItem(label: 'Tax', amountCents: 80),
  ],
  amount: '10.80',
  onResult: (res) {
    // handle result
  },
)

Individual Buttons

Use per-button widgets for custom layout and styling.

Programmatic: Payment sheet

Show the full Stripe-based sheet (webview) programmatically:

final result = await LearmondPaySheet.show(
  context: context,
  publishableKey: 'pk_test...',
  clientSecret: 'pi_..._secret_...',
  amount: '10.00',
  merchantArgs: buildMerchantArgs(...),
);

Programmatic: Native pay

Call the native bridge to present Apple/Google Pay directly and receive a token/result:

final res = await LearmondNativePay.showNativePay({
  'method': 'google_pay',
  'amountCents': 1000,
  'currency': 'USD',
  'gatewayMerchantId': 'yourGatewayMerchantId',
});

Web Support (Google Pay & Apple Pay)

This SDK now includes a web implementation for native-like payments:

Google Pay: prefers the Google Pay JS SDK when available (window.google.payments.api.PaymentsClient) and falls back to the standard PaymentRequest API using the Google Pay method identifier (https://google.com/pay). This enables a native Google Pay flow in Chrome/Edge and a PaymentRequest fallback for other browsers.
Apple Pay: the web plugin supports starting an ApplePaySession and performing merchant validation via a server-side endpoint. Because Apple requires merchant validation using a merchant identity certificate, you must provide a validation endpoint in merchantArgs (see example below).

Example usage (pass validation endpoint in merchantArgs):

runWebPaymentRequest(
  context,
  publishableKey: 'pk_test_...',
  method: 'apple_pay',
  amount: '10.00',
  merchantArgs: {
    'merchantName': 'The Learmond Corporation',
    'appleMerchantValidationUrl': 'https://your-server.example.com/apple/validate'
  },
  onResult: (result) { /* handle result */ },
);

Example servers for merchant validation are provided in example/apple_validation_server:

node_server.js — Node/Express example that forwards the browser validationURL to Apple using a PKCS#12 certificate (.p12). Set APPLE_P12_PATH, MERCHANT_IDENTIFIER and DOMAIN_NAME in the environment.
python_server.py — small Flask proxy that uses curl with the .p12 to perform validation (minimal Python deps).

Security notes

Apple merchant validation requires your merchant identity certificate — keep it on your server only and never commit it to source control.
You must host the /.well-known/apple-developer-merchantid-domain-association file on your domain and verify the domain in Apple Developer for Apple Pay to work.
Test Google Pay in Chrome/Edge; Safari will prefer Apple Pay and may intercept PaymentRequest unless you provide the Google Pay JS SDK.

Merchant args

Use buildMerchantArgs or buildMerchantArgsFromAmount to construct the merchant arguments map. A SummaryLineItem is a simple model:

final item = SummaryLineItem(label: 'Subtotal', amountCents: 1000);

buildMerchantArgsFromAmount(amount: '10.00', ...) converts dollars to cents and can generate a default summary item.

Example app

The example/ directory contains a working integration and a merchant-args editor. Run it to preview the SDK behavior:

cd example
flutter run

Development & testing

Useful commands:

# Format
dart format .

# Static analysis
flutter analyze

# Tests
flutter test

Troubleshooting

Use dart fix --apply to apply automatic suggestions.
If Android manifest/resource merge issues occur, check for duplicated dependencies (e.g., play-services-wallet) declared by both the app and the plugin.
If native pay buttons appear visually incorrect, check your app layout wrappers; the SDK provides consistent sizing but extra parent constraints can alter appearance.

Contributing

Contributions and bug reports welcome. Please use the example/ app to reproduce UI issues and include steps in PRs.

License

MIT

Author

The Learmond Corporation