now method

Future<PaymentData?> now({ required BuildContext context, required String customerEmail, required String reference, required double amount, required dynamic transactionCompleted(PaymentData data), required dynamic transactionNotCompleted(String reason), String? secretKey, String? currency, String? callbackUrl, VoidCallback? transactionCancelled, List<PaystackChannel>? channels, String? plan, int? invoiceLimit, String? subaccount, String? splitCode, double? transactionCharge, PaystackBearer? bearer, String? customerFirstName, String? customerLastName, String? customerPhone, List<PaystackCustomField>? customFields, List<PaystackCartItem>? cartItems, Map<String, dynamic>? metadata, Duration? timeout, bool? enableLogging, VoidCallback? onTimeout, bool showAppBar = true, String appBarTitle = 'Secure Checkout', Color? appBarColor, Color? appBarTextColor, Color? progressColor, Color? progressBackgroundColor, Widget? loadingWidget, Widget errorWidget(String error, VoidCallback retry)?, Widget? logoWidget, Color? backgroundColor, Color? cardBackgroundColor, Color? cardBorderColor, Color? primaryTextColor, Color? secondaryTextColor, Color? buttonTextColor, String? connectingText, String? waitingTitleText, String? waitingSubtitleText, String? step1Text, String? step2Text, String? step3Text, String? completedButtonText, String? reopenButtonText, String? cancelButtonText, String? verifyingText, String? verifyingSubtitleText, })

Launches the Paystack payment WebView and resolves with PaymentData when the checkout session ends (whether successful or not).

Parameters marked as optional if config set can be omitted when a global PaystackConfig has been set via configure.

---

Core (required unless global config provides a default)

• context — current BuildContext used for navigation.
• customerEmail — the customer's email address.
• reference — unique transaction reference (use generateUuidV4).
• amount — amount in the major unit (e.g. 50.0 = GHS 50.00). Converted to pesewas / kobo automatically.
• transactionCompleted — called with PaymentData on success.
• transactionNotCompleted — called with a status string on failure.
• secretKey — your Paystack secret key. Optional if config set.
• currency — ISO 4217 code e.g. "GHS". Optional if config set.
• callbackUrl — redirect URL after payment. Optional if config set.

---

Cancel callback

• transactionCancelled — called when the user explicitly closes the checkout without making a payment attempt. Distinct from transactionNotCompleted, which fires after a failed attempt.

---

Payment channels

• channels — restrict which payment options are shown to the customer.

---

Subscriptions

• plan — Paystack subscription plan code.
• invoiceLimit — number of times to charge during the plan.

---

Split payments

• subaccount — route/split payment to a subaccount (ACCT_xxxxxxxx).
• splitCode — use a pre-defined multi-recipient split group (SPL_xxx).
• transactionCharge — flat fee (major unit) for the main account when splitting. Overrides the default percentage.
• bearer — who pays the Paystack transaction fees (PaystackBearer.account or PaystackBearer.subaccount).

---

Customer prefill

• customerFirstName — pre-fills the customer's first name.
• customerLastName — pre-fills the customer's last name.
• customerPhone — pre-fills the customer's phone number.

---

Structured metadata

• customFields — list of PaystackCustomField objects shown on the Paystack Dashboard for this transaction.
• cartItems — list of PaystackCartItem line items attached to the transaction's metadata. Each item may include an optional imageUrl.
• metadata — raw additional key-value data for the transaction.

---

Network options

• timeout — maximum time to wait for the Paystack API. Defaults to 30 seconds (or the value set in PaystackConfig).
• enableLogging — if true, request/response details are printed to the console via debugPrint (no-op in release mode).
• onTimeout — called when the request times out. If null, transactionNotCompleted is called with 'timeout'.

---

UI customisation

• showAppBar — show the AppBar above the WebView (default true).
• appBarTitle — AppBar title (default "Secure Checkout").
• appBarColor — AppBar background color.
• appBarTextColor — AppBar text/icon color.
• progressColor — accent color for the loading/progress indicators and the "Try Again" button. Defaults to Paystack green (#00C386).
• progressBackgroundColor — track color for the linear progress bar. Defaults to Color(0xFF1E1E2E).
• loadingWidget — custom widget while the session initialises.
• errorWidget — custom error screen builder (receives error + retry).
• logoWidget — custom logo widget shown in the AppBar, loading screen, and waiting screen.
• backgroundColor — main Scaffold background color on web.
• cardBackgroundColor — Web checkout card background color.
• cardBorderColor — Web checkout card border color.
• primaryTextColor — Web checkout main text color.
• secondaryTextColor — Web checkout secondary/description text color.
• buttonTextColor — Web checkout primary action button text color.
• connectingText — text shown while initialising.
• waitingTitleText — title shown on the waiting card.
• waitingSubtitleText — subtitle/desc shown on the waiting card.
• step1Text — text for Step 1.
• step2Text — text for Step 2.
• step3Text — text for Step 3.
• completedButtonText — label for the primary completion button.
• reopenButtonText — label for the reopen tab link.
• cancelButtonText — label for the cancel payment link.
• verifyingText — text shown while verifying.
• verifyingSubtitleText — subtitle shown while verifying.

Implementation

Future<PaymentData?> now({
  // ── Required ─────────────────────────────────────────────────────────────
  required BuildContext context,
  required String customerEmail,
  required String reference,
  required double amount,
  required Function(PaymentData data) transactionCompleted,
  required Function(String reason) transactionNotCompleted,

  // ── Optional if global config provides them ───────────────────────────────
  String? secretKey,
  String? currency,
  String? callbackUrl,

  // ── Cancel callback ───────────────────────────────────────────────────────
  VoidCallback? transactionCancelled,

  // ── Payment channels ──────────────────────────────────────────────────────
  List<PaystackChannel>? channels,

  // ── Subscriptions ─────────────────────────────────────────────────────────
  String? plan,
  int? invoiceLimit,

  // ── Split payments ────────────────────────────────────────────────────────
  /// Subaccount code to route/split the payment to (e.g. `ACCT_xxxxxxxxxx`).
  String? subaccount,

  /// Pre-defined split group code (e.g. `SPL_xxxxxxxxxx`).
  String? splitCode,

  /// Flat fee (in major currency unit) that goes to the main account.
  /// Overrides the default percentage split when using [subaccount].
  double? transactionCharge,

  /// Who bears the Paystack transaction fees.
  PaystackBearer? bearer,

  // ── Customer prefill ──────────────────────────────────────────────────────
  /// Pre-fills the customer's first name on the checkout form.
  String? customerFirstName,

  /// Pre-fills the customer's last name on the checkout form.
  String? customerLastName,

  /// Pre-fills the customer's phone number on the checkout form.
  String? customerPhone,

  // ── Structured metadata ───────────────────────────────────────────────────
  /// Custom fields shown on the Paystack Dashboard for this transaction.
  List<PaystackCustomField>? customFields,

  /// Cart line items attached to the transaction's metadata.
  List<PaystackCartItem>? cartItems,

  /// Raw additional metadata for the transaction.
  Map<String, dynamic>? metadata,

  // ── Network options ───────────────────────────────────────────────────────
  Duration? timeout,
  bool? enableLogging,
  VoidCallback? onTimeout,

  // ── UI customisation ──────────────────────────────────────────────────────
  bool showAppBar = true,
  String appBarTitle = 'Secure Checkout',
  Color? appBarColor,
  Color? appBarTextColor,

  /// Accent color for the loading spinner, linear progress bar, verification
  /// overlay, and the "Try Again" button. Defaults to Paystack green.
  Color? progressColor,

  /// Track color for the linear progress indicator. Defaults to
  /// `Color(0xFF1E1E2E)`.
  Color? progressBackgroundColor,

  Widget? loadingWidget,
  Widget Function(String error, VoidCallback retry)? errorWidget,

  // ── Logo ──────────────────────────────────────────────────────────────────
  /// Custom logo widget displayed in the AppBar and loading/waiting screens.
  /// Accepts any widget — [Image.asset], [Image.network], an SVG, etc.
  Widget? logoWidget,

  // ── Detailed Styling & Text overrides (Web-specific, with stubs for Mobile) ──
  Color? backgroundColor,
  Color? cardBackgroundColor,
  Color? cardBorderColor,
  Color? primaryTextColor,
  Color? secondaryTextColor,
  Color? buttonTextColor,
  String? connectingText,
  String? waitingTitleText,
  String? waitingSubtitleText,
  String? step1Text,
  String? step2Text,
  String? step3Text,
  String? completedButtonText,
  String? reopenButtonText,
  String? cancelButtonText,
  String? verifyingText,
  String? verifyingSubtitleText,
}) {
  // Resolve values: direct param > global config > error.
  final resolvedKey = secretKey ?? _globalConfig?.secretKey;
  final resolvedCurrency = currency ?? _globalConfig?.currency;
  final resolvedCallbackUrl = callbackUrl ?? _globalConfig?.callbackUrl;
  final resolvedTimeout =
      timeout ?? _globalConfig?.timeout ?? const Duration(seconds: 30);
  final resolvedLogging =
      enableLogging ?? _globalConfig?.enableLogging ?? false;

  assert(
    resolvedKey != null,
    'secretKey must be provided either directly or via PayWithPayStack.configure().',
  );
  assert(
    resolvedCurrency != null,
    'currency must be provided either directly or via PayWithPayStack.configure().',
  );
  assert(
    resolvedCallbackUrl != null,
    'callbackUrl must be provided either directly or via PayWithPayStack.configure().',
  );

  // Build a merged metadata map that incorporates customerFirstName/LastName/Phone
  // as custom_fields so they appear on the Paystack Dashboard.
  final prefillFields = <PaystackCustomField>[
    if (customerFirstName != null)
      PaystackCustomField(
        displayName: 'First Name',
        variableName: 'first_name',
        value: customerFirstName,
      ),
    if (customerLastName != null)
      PaystackCustomField(
        displayName: 'Last Name',
        variableName: 'last_name',
        value: customerLastName,
      ),
    if (customerPhone != null)
      PaystackCustomField(
        displayName: 'Phone',
        variableName: 'phone',
        value: customerPhone,
      ),
  ];

  // Merge caller-supplied customFields with the prefill fields.
  final mergedCustomFields = [
    ...prefillFields,
    if (customFields != null) ...customFields,
  ];

  return Navigator.push<PaymentData>(
    context,
    MaterialPageRoute(
      builder: (context) => PaystackPayNow(
        secretKey: resolvedKey!,
        email: customerEmail,
        reference: reference,
        currency: resolvedCurrency!,
        amount: amount,
        callbackUrl: resolvedCallbackUrl!,
        paymentChannel:
            channels != null ? PaystackChannel.toStringList(channels) : null,
        plan: plan,
        invoiceLimit: invoiceLimit,
        subaccount: subaccount,
        splitCode: splitCode,
        transactionCharge: transactionCharge,
        bearer: bearer,
        customerFirstName: customerFirstName,
        customerLastName: customerLastName,
        customerPhone: customerPhone,
        customFields:
            mergedCustomFields.isNotEmpty ? mergedCustomFields : null,
        cartItems: cartItems,
        metadata: metadata,
        transactionCompleted: transactionCompleted,
        transactionNotCompleted: transactionNotCompleted,
        transactionCancelled: transactionCancelled,
        showAppBar: showAppBar,
        appBarTitle: appBarTitle,
        appBarColor: appBarColor,
        appBarTextColor: appBarTextColor,
        progressColor: progressColor,
        progressBackgroundColor: progressBackgroundColor,
        loadingWidget: loadingWidget,
        errorWidget: errorWidget,
        logoWidget: logoWidget,
        backgroundColor: backgroundColor,
        cardBackgroundColor: cardBackgroundColor,
        cardBorderColor: cardBorderColor,
        primaryTextColor: primaryTextColor,
        secondaryTextColor: secondaryTextColor,
        buttonTextColor: buttonTextColor,
        connectingText: connectingText,
        waitingTitleText: waitingTitleText,
        waitingSubtitleText: waitingSubtitleText,
        step1Text: step1Text,
        step2Text: step2Text,
        step3Text: step3Text,
        completedButtonText: completedButtonText,
        reopenButtonText: reopenButtonText,
        cancelButtonText: cancelButtonText,
        verifyingText: verifyingText,
        verifyingSubtitleText: verifyingSubtitleText,
        timeout: resolvedTimeout,
        enableLogging: resolvedLogging,
        onTimeout: onTimeout,
      ),
    ),
  );
}