payorc_flutter_v2 1.0.10

A Flutter plugin for orc payment.

payorc_flutter_v2

Flutter SDK for PayOrc checkout: payment method sheet (Apple Pay, Google Pay, Tabby, Samsung Pay, pay with card), add-card flow, and related UI. Merchant keys and the PayOrc service SDK drive checkout customization (colors, available methods, wallet JSON).

Requirements

• Flutter SDK compatible with this package’s pubspec.yaml constraints.
• Merchant keys and the PayOrc service SDK drive checkout customization (colors, available methods, wallet JSON). Tabby credentials are returned by POST .../sdk/tabby/init when Tabby is enabled in checkout.

Installation

Add the dependency (path or pub.dev version):

dependencies:
  payorc_flutter_v2: ^1.0.10

import 'package:payorc_flutter_v2/payorc_flutter_v2.dart';

App setup (required for toasts / alerts)

The SDK uses BotToast for some alerts. Wrap your app and register observers once:

import 'package:payorc_flutter_v2/payorc_flutter_v2.dart';

runApp(
  PayorcRoot(
    child: MaterialApp(
      navigatorObservers: [
        ...PayorcSdk.botToastNavigatorObservers,
      ],
      home: const MyHomePage(),
    ),
  ),
);

Alternative: keep your existing MaterialApp and compose PayorcSdk.wrapMaterialAppBuilder into MaterialApp.builder (see API docs on PayorcSdk.wrapMaterialAppBuilder).

---

1. PayorcSdk.init — configure the SDK

Call once at startup (before PayorcSdk.instance or any sheet). Loads checkout customization in the background when the default internal flags apply (see implementation).

PayorcSdk.init(
  merchantKey: 'YOUR_MERCHANT_KEY',
  merchantSecret: 'YOUR_MERCHANT_SECRET',
  environment: PayorcEnvironment.sandbox, // or PayorcEnvironment.production
  language: PayorcLanguage.english,      // optional; default english
);

Parameters

Parameter	Type	Required	Description
merchantKey	String	yes	PayOrc merchant key.
merchantSecret	String	yes	PayOrc merchant secret.
environment	PayorcEnvironment	yes	sandbox or production API / gateway behavior.
language	PayorcLanguage	no	SDK language / text direction (english, arabic). Default english.

Tabby is enabled when checkout customization includes Tabby in the payment sequence. The SDK calls POST .../sdk/tabby/init at checkout time; TabbyInitData.password is the Tabby API key and TabbyInitData.merchantCode is the Tabby merchant code — do not pass these to PayorcSdk.init.

Return value

Returns the configured PayorcSdk singleton. After init, use PayorcSdk.instance anywhere.

---

2. PayorcSdk.customization — host UI overrides

Optional static call (any time after init) to override checkout-driven colors and form chrome.

Priority: each non-null argument you pass wins over checkout merchant_details from the customization API. Omitted arguments keep the previous host override (if any), then the API value, then SDK defaults. Nested objects (button, text, addCardForm, appTextField, bottomSheet) merge field-by-field: only non-null properties apply.

Calling customization bumps PayorcSdk.uiCustomizationRevision and PayorcSdk.checkoutCustomizationRevision, so widgets such as AppTextField rebuild.

Checkout API mapping (merchant_details)

customization parameter	Checkout field
inputBorderStyle	field_border (outline / underline)
appBarStyle	app_style (nativeIos / nativeAndroid)
textPrimary	text_primary
textSecondary	text_secondary
autoselectColor	autoselect_color

| appTextField.borderColor | border_color (field strokes only) |

guidanceStyle is host-only (not from checkout).

PayorcSdk.customization(
  inputBorderStyle: PayorcInputBorderStyle.outline,
  guidanceStyle: PayorcGuidanceStyle.hint,
  appBarStyle: PayorcAppBarStyle.nativeIos,
  brandColor: const Color(0xFF000000),
  button: const PayorcSdkButtonCustomization(
    backgroundColor: Color(0xFF000000),
    foregroundColor: Color(0xFFFFFFFF),
  ),
  accentColor: const Color(0xFF000000),
  text: const PayorcSdkTextCustomization(
    primary: Color(0xFF111111),
    secondary: Color(0xFF666666),
    bodyFontFamily: PayorcSdkFontFamily.inter,
    titleFontFamily: PayorcSdkFontFamily.montserrat,
    fontWeight: FontWeight.w500,
    fontSize: 15,
    letterSpacing: 0.2,
    textAlign: TextAlign.start,
    maxLines: 3,
    overflow: TextOverflow.ellipsis,
    decoration: TextDecoration.none,
    wordSpacing: 0,
    softWrap: true,
    shadows: [
      Shadow(color: Color(0x33000000), blurRadius: 2, offset: Offset(0, 1)),
    ],
    fontStyle: FontStyle.normal,
  ),
  textPrimary: const Color(0xFF111111),
  textSecondary: const Color(0xFF666666),
  cardFormValidation: const PayorcSdkCardFormValidationCustomization(
    cardHolderNameError: CardFormError(
      required: 'Card holder is required',
      invalid: 'Enter first and last name',
    ),
    cardNumberError: CardFormError(
      required: 'Card number is required',
      invalid: 'Enter a valid card number',
    ),
    expiryMonthError: CardFormError(
      required: 'Expiry is required',
      invalid: 'Invalid month',
    ),
    expiryYearError: CardFormError(
      invalid: 'Invalid year',
    ),
    cvvError: CardFormError(
      required: 'CVV required',
      invalid: '3 or 4 digits',
    ),
    invalidCardError: CardFormError(
      invalid: 'Enter a valid expiry date',
    ),
  ),
  addCardForm: const PayorcSdkAddCardFormCustomization(
    titleUseNewCard: 'Add card',
    cardNumberHint: '0000 0000 0000 0000',
    submitButtonTitleVerify: 'Verify card',
  ),
  appTextField: const PayorcSdkAppTextFieldCustomization(
    height: 48,
    borderRadius: 8,
    borderColor: Color(0xFFCCCCCC),
    padding: EdgeInsetsDirectional.only(top: 14, bottom: 10, start: 10, end: 0),
  ),
  bottomSheet: const PayorcSdkBottomSheetCustomization(
    padding: EdgeInsets.fromLTRB(24, 16, 24, 24),
    spacing: 12,
    cornerRadius: 16,
  ),
  autoselectColor: const Color(0xFF000000),
);

Parameters

Parameter	Type	Description
inputBorderStyle	PayorcInputBorderStyle?	outline or underline for AppTextField. Host → checkout field_border → underline.
guidanceStyle	PayorcGuidanceStyle?	How field guidance is shown in AppTextField and LabeledField. Default label. See PayorcGuidanceStyle.
appBarStyle	PayorcAppBarStyle?	nativeAndroid or nativeIos for SDK scaffolds. Host → checkout app_style → platform default.
brandColor	Color?	Sheet / header brand fill. Fully transparent colors are ignored.
button	PayorcSdkButtonCustomization?	Primary CTA styling; non-null fields merge. See PayorcSdkButtonCustomization.
accentColor	Color?	Secondary accent (links, highlights, selection chrome).
text	PayorcSdkTextCustomization?	Typography bundle (colors, fonts, default text metrics). Non-null fields merge. See PayorcSdkTextCustomization.
textPrimary	Color?	Shorthand for primary text color. Same role as text: PayorcSdkTextCustomization(primary: …).
textSecondary	Color?	Shorthand for secondary text color (merchant_details.text_secondary).
cardFormValidation	PayorcSdkCardFormValidationCustomization?	Add-card validator message overrides. Empty/null per field → SDK default.
addCardForm	PayorcSdkAddCardFormCustomization?	Add / edit card sheet copy (titles, labels, hints, button labels). Merges across calls. See PayorcSdkAddCardFormCustomization.
appTextField	PayorcSdkAppTextFieldCustomization?	AppTextField-only height, padding, radius, border color. Merges across calls.
bottomSheet	PayorcSdkBottomSheetCustomization?	Modal sheet padding, vertical spacing, top corner radius. Merges across calls.
autoselectColor	Color?	Highlight color for auto-selected payment method. Host → checkout autoselect_color → SDK default.

---

3. Checkout — two ways to submit an order

There are two integration paths. Both end with PayOrc.submitOrder for card payments (3DS / gateway sheet). Wallets (Apple Pay, Google Pay) and Tabby complete inside their own SDK flows when you use the built-in UI or embedded widgets.

	Way 1 — SDK UI	Way 2 — Your own UI
Entry	PayorcSdk.instance.showOptionsSheet	Embedded widgets and/or PayOrc helpers
Who builds the screen	PayOrc payment-options sheet	You place buttons/tiles in your layout
Card checkout	You call PayOrc.submitOrder from onAddNewCard	Same — call PayOrc.submitOrder (or use embeds that call it for you)

Way 1 — showOptionsSheet (full SDK UI)

Use this when you want the payment method bottom sheet (Apple Pay, Google Pay, Tabby, Samsung Pay, pay with card) with minimal custom UI.

1. Build a submit-order PaymentRequest (paymentToken, order/customer/billing/shipping, urls, etc.).
2. Call PayorcSdk.instance.showOptionsSheet with that request.
3. When the user adds or confirms a card, onAddNewCard receives CardData including paymentToken (from add-card / verification). That token is required for PayOrc.submitOrder.
4. After the options sheet closes, schedule submit on the next frame (avoids presenting a modal while the sheet is still popping):

import 'package:payorc_flutter_v2/payorc_flutter_v2.dart';

Future<void> _startPayorcCheckout(BuildContext context) async {
  final request = PaymentRequest.submitOrder(
    // paymentToken, orderDetails, customerDetails, billingDetails,
    // shippingDetails, urls, …
  );

  await PayorcSdk.instance.showOptionsSheet(
    context,
    paymentRequest: request,
    onAddNewCard: (CardData input) {
      if (!context.mounted) return;
      WidgetsBinding.instance.addPostFrameCallback((_) {
        _submitPayorcOrder(context, input, request);
      });
    },
    onApplePayResult: (result) { /* wallet payload */ },
    onGooglePayResult: (result) { /* wallet payload */ },
    onPaymentError: (error) { /* wallet / flow errors */ },
    onTabbyAuthorized: () { /* Tabby OK */ },
    onTabbyError: (error) { /* Tabby error */ },
  );
}

void _submitPayorcOrder(
  BuildContext context,
  CardData card,
  PaymentRequest request,
) {
  PayOrc.submitOrder(
    context,
    card: card,
    paymentRequest: request,
    onSuccessPayment: (_) {
      if (!context.mounted) return;
      // Payment succeeded — navigate, refresh order, etc.
    },
    onPaymentFailed: (submitModalContext, message, {code}) {
      if (!context.mounted) return;
      // Optional analytics; SDK still shows failure / retry UI
    },
    onRetryPayment: () {},
  );
}

Notes

• onAddNewCard is required — the sheet does not call PayOrc.submitOrder for you; your app must continue checkout with the returned CardData.
• On payment failure, PayOrc.submitOrder shows the SDK failure sheet (Retry, Add new card, Use another card) and re-opens submit-order internally — you do not pass an onNewCardAdded callback.
• Apple Pay / Google Pay / Tabby use the callbacks on showOptionsSheet (or embedded equivalents); card rail always goes through PayOrc.submitOrder.

Way 2 — Your own UI (embedded widgets + PayOrc)

Use this when you do not want the full payment-options sheet and instead embed PayOrc controls in your checkout screen.

• Option A — All-in-one — PayorcEmbeddedPaymentCheckout (wallets + tiles in checkout order; see §5).
• Option B — Individual embeds — compose PayorcEmbeddedApplePayButton, Google Pay, Tabby, pay-with-card, etc. (see §5).
• Option C — PayOrc helpers only — full control over when sheets open (PayOrc):

// Add card only (WebView verification); card may include paymentToken in onAddCard
await PayOrc.addNewCard(
  context,
  paymentRequest: PaymentRequest.deriveForAddCard(submitOrderRequest),
  onAddCard: (sheetContext, card) {
    Navigator.of(sheetContext).pop();
    PayOrc.submitOrder(
      context,
      card: card,
      paymentRequest: submitOrderRequest,
      onSuccessPayment: (_) { /* success */ },
    );
  },
);

// Or submit when you already have CardData (e.g. saved card + CVV from your UI)
await PayOrc.submitOrder(
  context,
  card: card,
  paymentRequest: submitOrderRequest,
  onSuccessPayment: (_) { /* … */ },
);

See PayOrc — add card & submit order for parameter details.

---

4. PayorcSdk.instance.showOptionsSheet — payment method bottom sheet

Presents the payment options flow (Way 1 above): refreshes checkout customization, then shows Apple Pay / Google Pay / Tabby / Samsung Pay / pay-with-card, depending on your PayOrc configuration.

await PayorcSdk.instance.showOptionsSheet(
  context,
  paymentRequest: request,
  onAddNewCard: (CardData input) {
    // Card includes paymentToken — call PayOrc.submitOrder on the next frame (see §3).
  },
  onApplePayResult: (Map<String, dynamic> result) {
    // Wallet token payload from the `pay` package (debug / integrate as needed).
  },
  onGooglePayResult: (Map<String, dynamic> result) {
    // Same for Google Pay.
  },
  onPaymentError: (Object? error) {
    // Apple Pay / Google Pay or flow errors.
  },
  onTabbyAuthorized: () {
    // Tabby authorized (if Tabby enabled).
  },
  onTabbyError: (Object? error) {
    // Tabby rejected / error.
  },
);

Parameters

Parameter	Type	Required	Description
context	BuildContext	yes	Context used for theming / navigation host (see SDK implementation).
paymentRequest	PaymentRequest	yes	Checkout payload (order, customer, billing, shipping, etc.).
onAddNewCard	void Function(CardData)	yes	Card data including paymentToken when verified — call PayOrc.submitOrder on the next frame (see §3).
addCardRequest	PaymentRequest?	no	Add-card API payload; if omitted, derived via PaymentRequest.deriveForAddCard(paymentRequest).
customizationCurrency	String?	no	Overrides currency for the customization refresh query.
customizationAmount	num?	no	Overrides amount for the customization refresh query.
onApplePayWalletResult	void Function(WalletPaymentResult)?	no	Apple Pay wallet result (typed wrapper).
onApplePayPaymentResponse	void Function(PaymentResponse)?	no	Apple Pay payment API-style response when used by the integration.
onApplePayResult	void Function(Map<String, dynamic>)?	no	Raw Apple Pay result map from pay.
onGooglePayResult	void Function(Map<String, dynamic>)?	no	Raw Google Pay result map from pay.
onPaymentError	void Function(Object?)?	no	Wallet / flow errors.
onTabbyAuthorized	VoidCallback?	no	Tabby checkout authorized.
onTabbyError	void Function(Object?)?	no	Tabby errors / rejection.
onConfirm	VoidCallback?	no	Confirm path when shown by the sheet.
onSamsungPay	VoidCallback?	no	Samsung Pay selected (when enabled).

showOptionsSheet returns a Future<void> that completes when the modal is dismissed or the flow finishes presenting.

---

5. Embedded payment methods

Use these when building your own checkout UI (Way 2). All embedded widgets are exported from the package.

Prerequisites

1. Call PayorcSdk.init before building embeds.
2. Wrap your app with PayorcRoot (see App setup) so SDK theme, fonts, and toasts work.
3. Pass a submit-order PaymentRequest (PaymentRequest.submitOrder, same shape as showOptionsSheet).
4. Checkout customization must be loaded (happens on init / first sheet refresh). Widgets listen to PayorcSdk.checkoutCustomizationRevision and hide themselves when a method is not enabled (SizedBox.shrink()).

Visibility

Widget	Shown when
PayorcEmbeddedApplePayButton	iOS, Apple Pay in checkout sequence, device can pay
PayorcEmbeddedGooglePayButton	Android, Google Pay config available
PayorcEmbeddedTabbyButton	Tabby enabled in checkout customization
payorcEmbeddedOpenPayWithCard	checkoutRequest.kind == submitOrder

Compose your checkout screen

import 'package:payorc_flutter_v2/payorc_flutter_v2.dart';

class CheckoutPaymentSection extends StatelessWidget {
  const CheckoutPaymentSection({super.key, required this.request});

  final PaymentRequest request; // PaymentRequest.submitOrder(...)

  @override
  Widget build(BuildContext context) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.stretch,
      children: [
        PayorcEmbeddedApplePayButton(
          paymentRequest: request,
          onPaymentSuccess: (response, rawFromPayPackage) {
            // /sdk/payment succeeded
          },
          onPaymentError: (e) {
            // Wallet, parse, network, or payment API error
          },
        ),
        const SizedBox(height: 12),
        PayorcEmbeddedGooglePayButton(
          paymentRequest: request,
          onGooglePayResult: (result) {
            // Raw token map from the `pay` package — wire to your backend if needed
          },
          onPaymentError: (e) {},
        ),
        const SizedBox(height: 12),
        PayorcEmbeddedTabbyButton(
          paymentRequest: request,
          onTabbyAuthorized: () {},
          onTabbyError: (e) {},
          style: PayorcEmbeddedCustomization.tabby(
            backgroundColor: const Color(0xFFF5F5F5),
            textColor: const Color(0xFF111111),
            height: 56,
          ),
        ),
        const SizedBox(height: 12),
        payorcEmbeddedOpenPayWithCard(
          context: context,
          checkoutRequest: request,
          style: PayorcEmbeddedCustomization.payWithCard(
            backgroundColor: const Color(0xFF111111),
            textColor: Colors.white,
            borderRadius: 12,
            height: 48,
            title: 'Pay with Card',
          ),
          onSuccessPayment: (_) {},
          onPaymentFailed: (_, message, {code}) {},
        ),
      ],
    );
  }
}

PayorcEmbeddedApplePayButton

Native Apple Pay button (iOS). Runs wallet authorization, then POST /sdk/payment internally. Does not pop your routes.

Parameter	Type	Description
paymentRequest	PaymentRequest	Required. Submit-order checkout.
onPaymentSuccess	(PaymentResponse, Map<String, dynamic>)?	/sdk/payment succeeded; second arg is raw pay result.
onPaymentError	void Function(Object?)?	Wallet errors, parse failures, or failed payment API.
margin	EdgeInsets	Default EdgeInsets.zero.
height	double	Default 48.

PayorcEmbeddedApplePayButton(
  paymentRequest: buildPayorcSdkRequest(),
  onPaymentSuccess: (response, rawFromPayPackage) {
    // Handle success — response is typed PaymentResponse
  },
  onPaymentError: (e) {
    // Handle failure
  },
),

PayorcEmbeddedGooglePayButton

Native Google Pay button (Android). Returns the wallet token map to your callback (does not call /sdk/payment inside the widget — integrate with your backend or extend as needed).

Parameter	Type	Description
paymentRequest	PaymentRequest	Required.
onGooglePayResult	void Function(Map<String, dynamic>)?	Raw result from pay after user approves.
onPaymentError	void Function(Object?)?	Native / configuration errors.
margin / height		Same as Apple Pay.

PayorcEmbeddedGooglePayButton(
  paymentRequest: buildPayorcSdkRequest(),
  onGooglePayResult: (result) {
    // Map from Google Pay — submit to your server or payment flow
  },
  onPaymentError: (e) {},
),

PayorcEmbeddedTabbyButton

One-tap Tabby row: init → Tabby SDK → WebView → confirm (same as sheet Tabby). Hidden when Tabby is not in checkout customization.

Parameter	Type	Description
paymentRequest	PaymentRequest	Required.
onTabbyAuthorized	VoidCallback?	Tabby checkout authorized.
onTabbyError	void Function(Object?)?	Init / WebView / confirm errors.
tabbyCheckoutLauncherContext	BuildContext?	Use when this subtree has no Navigator (defaults to widget context).
onTapTabby	VoidCallback?	Override tap (skip default Tabby flow).
style	PayorcEmbeddedCustomization?	Optional tile styling via PayorcEmbeddedCustomization.tabby.
margin	EdgeInsets	Outer padding.

PayorcEmbeddedTabbyButton(
  paymentRequest: buildPayorcSdkRequest(),
  onTabbyAuthorized: () {
    // BNPL authorized
  },
  onTabbyError: (e) {},
  style: PayorcEmbeddedCustomization.tabby(
    backgroundColor: const Color(0xFFF5F5F5),
    textColor: const Color(0xFF111111),
    height: 56,
    borderRadius: 12,
    selectedBackground: const Color(0xFFE8F0FE),
    selectedBorder: const Color(0xFF1A73E8),
  ),
),

payorcEmbeddedOpenPayWithCard

SDK “Pay with Card” button: opens add-card sheet, then PayOrc.submitOrder on the next frame (same card path as Way 1).

Parameter	Type	Description
context	BuildContext	Required. Host context for modals.
checkoutRequest	PaymentRequest	Required. Must be submitOrder.
addCardRequest	PaymentRequest?	Defaults to deriveForAddCard(checkoutRequest).
onSuccessPayment	void Function(BuildContext)?	Submit-order success sheet completed.
onPaymentFailed	callback	Optional hook before SDK failure UI.
onRetryPayment	VoidCallback?	User tapped Retry.
style	PayorcEmbeddedCustomization?	Optional button + add-card sheet styling via PayorcEmbeddedCustomization.payWithCard.

payorcEmbeddedOpenPayWithCard(
  context: context,
  checkoutRequest: buildPayorcSdkRequest(),
  style: PayorcEmbeddedCustomization.payWithCard(
    backgroundColor: const Color(0xFF111111),
    textColor: Colors.white,
    borderRadius: 12,
    height: 48,
    title: 'Pay with Card',
  ),
  onSuccessPayment: (_) {},
  onPaymentFailed: (ctx, message, {code}) {},
),

PayorcEmbeddedCustomization (Tabby & Pay with Card)

Optional style on SDK-built embeds. Apple Pay and Google Pay use native platform buttons and do not accept this type.

Widget	style
PayorcEmbeddedTabbyButton	yes — use PayorcEmbeddedCustomization.tabby
payorcEmbeddedOpenPayWithCard	yes — use PayorcEmbeddedCustomization.payWithCard
PayorcEmbeddedApplePayButton	no
PayorcEmbeddedGooglePayButton	no

PayorcEmbeddedCustomization.tabby

Styles the Tabby tile row (PayMethodTile).

Parameter	Type	Description
backgroundColor	Color?	Tile fill. When omitted, uses checkout accent or SDK default grey.
textColor	Color?	Title text color.
height	double?	Fixed tile height.
borderRadius	double?	Corner radius (default 12).
borderColor	Color?	Unselected tile outline.
accent	Color?	Accent passed into add-card / sheet flows when opened from embeds.
selectedBackground	Color?	Fill when the tile is selected.
selectedBorder	Color?	Border when selected; falls back to accent.

style: PayorcEmbeddedCustomization.tabby(
  backgroundColor: const Color(0xFFF5F5F5),
  textColor: const Color(0xFF111111),
  height: 56,
),

PayorcEmbeddedCustomization.payWithCard

Styles the Pay with Card button and the add-card / submit-order sheets opened from it. On tap, applyToSdk() merges button, border, and sheet corner overrides for that flow.

Parameter	Type	Description
backgroundColor	Color?	Button fill.
textColor	Color?	Button label color.
borderRadius	double?	Button corner radius.
height	double?	Button height.
borderColor	Color?	Button outline; also applied to AppTextField borders in the sheet.
title	String?	Overrides default Pay with Card label.

payorcEmbeddedOpenPayWithCard(
  context: context,
  checkoutRequest: buildPayorcSdkRequest(),
  style: PayorcEmbeddedCustomization.payWithCard(
    backgroundColor: const Color(0xFF111111),
    textColor: Colors.white,
    borderRadius: 12,
    height: 48,
    title: 'Pay with Card',
  ),
  onSuccessPayment: (_) {},
  onPaymentFailed: (ctx, message, {code}) {},
),

PayorcEmbeddedPaymentCheckout (all-in-one)

Single widget: Apple Pay + Google Pay + Tabby + Samsung + Pay with Card in checkout sequence order (matches showOptionsSheet methods). Wraps children with SDK theme.

Parameter	Type	Description
themeHostContext	BuildContext	Required. Context for wrapWithSdkTheme.
paymentRequest	PaymentRequest	Required.
addCardRequest	PaymentRequest?	Optional add-card payload.
onSubmitOrderSuccess	void Function(BuildContext)?	Card payment success.
onSubmitOrderPaymentFailed / onSubmitOrderRetry		PayOrc.submitOrder hooks.
onPaymentSuccess	callback	Apple Pay /sdk/payment success.
onGooglePayResult / onPaymentError		Google Pay / wallet errors.
onTabbyAuthorized / onTabbyError		Tabby callbacks.
onSamsungPay	VoidCallback?	After Samsung Confirm.
spacing	double	Vertical gap between rows (default 12).

PayorcEmbeddedPaymentCheckout(
  themeHostContext: context,
  paymentRequest: buildPayorcSdkRequest(),
  onPaymentSuccess: (response, raw) {},
  onSubmitOrderSuccess: (_) {},
  onTabbyAuthorized: () {},
  onSamsungPay: () {},
),

---

Enums (quick reference)

PayorcEnvironment

Value	Meaning
sandbox	Sandbox / test endpoints.
production	Production endpoints.

PayorcLanguage

Value	Effect
english	English LTR.
arabic	Arabic RTL.

PayorcInputBorderStyle

Value	Use
outline	Bordered text fields.
underline	Underline-only text fields.

PayorcGuidanceStyle

Controls AppTextField and LabeledField. Set via guidanceStyle: on PayorcSdk.customization (host-only; not loaded from checkout).

Value	AppTextField	LabeledField
label	Guidance from label or title is shown as a floating label (FloatingLabelBehavior.auto). Optional hint stays as placeholder text. A separate title row appears only when both title and label are set.	Shows the uppercase label above the child.
hint	No floating label (FloatingLabelBehavior.never). Placeholder uses hint, or label / title when hint is omitted. No standalone title row above the field.	Returns only the child (no label above).

Default after PayorcSdk.init: label.

PayorcSdkTextCustomization

Pass an instance as text: on PayorcSdk.customization. The constructor exposes only named parameters; every parameter is optional (null = do not override). Only non-null fields apply; each PayorcSdk.customization call merges with earlier calls and with checkout-driven defaults. New fields may be added in future SDK versions without breaking existing call sites.

Constructor shape (same order as the SDK source):

const PayorcSdkTextCustomization({
  Color? primary,
  Color? secondary,
  PayorcSdkFontFamily? bodyFontFamily,
  PayorcSdkFontFamily? titleFontFamily,
  FontWeight? fontWeight,
  double? fontSize,
  double? letterSpacing,
  TextAlign? textAlign,
  int? maxLines,
  TextOverflow? overflow,
  TextDecoration? decoration,
  double? wordSpacing,
  bool? softWrap,
  List<Shadow>? shadows,
  FontStyle? fontStyle,
});

Field	Type	Description
primary	Color?	Primary body / title text on light surfaces (SDK primary text role; same intent as legacy textPrimary).
secondary	Color?	Secondary / supporting text (same intent as legacy textSecondary).
bodyFontFamily	PayorcSdkFontFamily?	Optional bundled font for body and labels. When set, overrides checkout font_name for body-scale styles unless headlines use titleFontFamily.
titleFontFamily	PayorcSdkFontFamily?	Optional bundled font for display / headline / title styles. When null, bodyFontFamily or checkout font_name applies for those roles too.
fontWeight	FontWeight?	Default weight for SDK text widgets where the customization is applied.
fontSize	double?	Default font size for SDK text widgets where applied.
letterSpacing	double?	Default letter spacing.
textAlign	TextAlign?	Default text alignment.
maxLines	int?	Default max lines for display text where applied.
overflow	TextOverflow?	Default overflow behavior for display text.
decoration	TextDecoration?	Default text decoration (underline, etc.).
wordSpacing	double?	Default word spacing.
softWrap	bool?	Default soft-wrap for display text.
shadows	List<Shadow>?	Default text shadows.
fontStyle	FontStyle?	Default font style (FontStyle.normal / FontStyle.italic).

PayorcSdkFontFamily

Bundled font families shipped with the package (pubspec.yaml / PayorcSdkFontFamily in code). Use with bodyFontFamily and titleFontFamily. Names map to Flutter fontFamily strings (e.g. inter → "Inter").

Value	Bundled family name
roboto	Roboto
openSans	Open Sans
lato	Lato
lora	Lora
montserrat	Montserrat
notoSans	Noto Sans
notoSerif	Noto Serif
nunito	Nunito
raleway	Raleway
bitter	Bitter
inter	Inter
inconsolata	Inconsolata
ptSans	PT Sans
ptSerif	PT Serif
pridi	Pridi
robotoSlab	Roboto Slab
sourceSansPro	Source Sans Pro
titilliumWeb	Titillium Web
ubuntuMono	Ubuntu Mono
beVietnamPro	Be Vietnam Pro
chakraPetch	Chakra Petch
hahmlet	Hahmlet
zenMaruGothic	Zen Maru Gothic

PayorcSdkButtonCustomization

Passed as button: on PayorcSdk.customization. Replaces the former standalone buttonColor parameter; only non-null fields apply.

Field	Type	Description
backgroundColor	Color?	Primary CTA fill (same role as former buttonColor).
foregroundColor	Color?	Label / icon on the primary button.
disabledBackgroundColor	Color?	Fill when the button is disabled.
sideBorderColor	Color?	1px outline; use transparent to omit outline (default).
borderRadius	double?	Corner radius for SDK buttons that read host defaults.
height	double?	Height for default SDK buttons (LoaderButton / AppButton).
fontWeight	FontWeight?	Primary CTA label weight.
loadingIndicatorColor	Color?	Spinner color when LoaderButton is loading.

PayorcSdkCardFormValidationCustomization

Passed as cardFormValidation: on PayorcSdk.customization. Use this to override add-card validation messages field-by-field.

Field	Type	Description
cardHolderNameError	CardFormError?	Card holder name validation messages (required, invalid).
cardNumberError	CardFormError?	Card number validation messages (required, invalid).
expiryMonthError	CardFormError?	Expiry month validation messages (required, invalid).
expiryYearError	CardFormError?	Expiry year validation messages (required, invalid).
cvvError	CardFormError?	CVV validation messages (required, invalid).
invalidCardError	CardFormError?	Generic invalid card/expiry format messages (required, invalid).

CardFormError

Used by PayorcSdkCardFormValidationCustomization to override validator message types.

Field	Type	Description
required	String?	Message shown when field is empty.
invalid	String?	Message shown when format/value is invalid.

PayorcSdkAddCardFormCustomization

Pass as addCardForm: on PayorcSdk.customization. Non-null fields merge across calls. Strings are shown as-is (not passed through .localize()).

Field	Description
titleUseNewCard / titleEditCard	Sheet header for add vs edit card.
subtitleAdd / subtitleEdit	Subtitle under the header.
cardHolderNameLabel, cardNumberLabel, expiryLabel, cvvLabel, emailLabel, mobileLabel	Field labels (used with PayorcGuidanceStyle.label / LabeledField).
cardHolderNameHint, cardNumberHint, expiryHint, cvvHint, emailHint, mobileHint	Placeholders for AppTextField.
countrySearchHint	Country picker search hint.
submitButtonTitleVerify / submitButtonTitleSaveChanges	Primary action labels.

PayorcSdkAppTextFieldCustomization

Pass as appTextField: on PayorcSdk.customization. Affects AppTextField only.

Field	Type	Description
height	double?	Minimum height wrapper around the inner TextFormField.
padding	EdgeInsetsGeometry?	InputDecoration.contentPadding.
borderRadius	double?	Corner radius for outline borders (ignored for underline style).
borderColor	Color?	Resting field border for AppTextField. Host → checkout border_color → #CCCCCC.

PayorcSdkBottomSheetCustomization

Pass as bottomSheet: on PayorcSdk.customization. Applies to payment options, add card, payment failed/success, submit order, and similar modals.

Field	Type	Description
padding	EdgeInsetsGeometry?	Sheet content padding (default fromLTRB(24, 16, 24, 24)).
spacing	double?	Default vertical gap between blocks (legacy 12); section gaps use 2 × spacing.
cornerRadius	double?	Top corner radius of the rounded sheet surface.

PayorcAppBarStyle

Value	Use
nativeAndroid	Android-style app bar behavior.
nativeIos	iOS-style app bar behavior.

PaymentViewType (on PaymentRequest)

Value	Meaning
bottomsheet	Present review / gateway as a bottom sheet.
screen	Full-screen gateway (requires extra gateway builder where applicable).

PaymentRequestType

Value	Meaning
submitOrder	Pay existing checkout (paymentToken, urls, …).
addCard	Add-card only payload (no payment token).

---

Core types

• PaymentRequest — Build with PaymentRequest.submitOrder(...) or PaymentRequest.addCard(...), or derive add-card from checkout with PaymentRequest.deriveForAddCard.
• CardData — Cardholder, expiry, CVV, optional email/phone, tokens for saved cards.
• CustomerDetails — mCustomerId, name, email, mobile, code (dial country code, digits only, e.g. 971). Passed on every PaymentRequest.
• PayorcSdk.instance — Throws if PayorcSdk.init was not called; use PayorcSdk.isInitialized to guard.

---

Customer details on card checkout

When the shopper pays with card, the SDK may show an add-card sheet. What you pass in PaymentRequest.customerDetails controls which extra fields the shopper sees.

CustomerDetails fields: mCustomerId, name, email, mobile, code (country dial code without +, e.g. 971).

Quick rules

• Pass name, email, and mobile from your app when you already know them → the SDK hides those fields and uses your values.
• Pass them as "" (empty string) when you do not have them → the SDK asks the shopper on the add-card sheet.
• Empty means: "", null, or the text "null" (whitespace is ignored).

Cardholder name (name)

• You provide the name → shopper only enters card number, expiry, and CVV.
• You pass an empty name → shopper must enter cardholder name (first and last name required).
• Customize labels, hints, and error messages with PayorcSdk.customization(addCardForm: …) and cardFormValidation: ….

Mobile (mobile + code)

• You provide the mobile → mobile field is hidden; your number is sent with the payment.
• You pass an empty mobile → shopper must pick a country code and enter their phone number.
• Set code to your shopper’s dial code (e.g. 971) so the correct country is pre-selected when possible.
• If payment fails because of a wrong or missing phone, the SDK can show the mobile field again.

Email (email)

• You provide the email → email field is hidden.
• You pass an empty email → shopper must enter a valid email.
• If payment fails because of a wrong email, the SDK can show the email field again.

What the shopper always enters (new card)

• Card number
• Expiry (MM / YY)
• CVV

Contact fields above are added only when your customerDetails left them empty.

Tips for integrators

• Know your user at checkout? Fill name, email, and mobile in PaymentRequest.submitOrder — shortest card form for the shopper.
• Guest checkout? Leave name and/or mobile as "" — the SDK collects them during add-card.
• Same rules everywhere — applies to showOptionsSheet, PayOrc.addNewCard, embedded pay-with-card, and add-card after a failed payment.
• Fix contact after payment error — reopen add-card with recoveryErrorCode and recoveryErrorMessage on PayOrc.addNewCard so the shopper sees what to correct.

Examples

Guest — SDK asks for name and mobile:

customerDetails: const CustomerDetails(
  mCustomerId: 'cust_123',
  name: '',
  email: '[e-mail]',
  mobile: '',
  code: '971',
),

Logged-in user — card fields only:

customerDetails: const CustomerDetails(
  mCustomerId: 'cust_123',
  name: 'Jane Doe',
  email: '[e-mail]',
  mobile: '501234567',
  code: '971',
),

---

PayOrc — add card & submit order (without the full sheet)

PayOrc is exported from the package. Use it for Way 2 or as the submit step after Way 1 (onAddNewCard).

PayOrc.addNewCard

Opens the add-card bottom sheet: signed add-card API, optional WebView verification. onAddCard receives the sheet BuildContext and CardData (often with paymentToken after success).

Parameter	Type	Description
context	BuildContext	Host context for the modal.
paymentRequest	PaymentRequest	Add-card payload (PaymentRequest.addCard or deriveForAddCard).
onAddCard	void Function(BuildContext, CardData)	Required. Card entered / verified.
onCancel	void Function(BuildContext)?	Defaults to Navigator.pop.
initialCard	CardData?	Pre-fill or edit saved card.
savedCardEditMode	bool	Edit UI for saved card (read-only PAN).
recoveryErrorCode / recoveryErrorMessage	String?	Re-open after mobile/email validation errors (E0021 / 43).

PayOrc.submitOrder

Opens the non-dismissible submit-order bottom sheet: signed payment API, 3DS / gateway handling, then a success confirmation sheet.

On payment failure the SDK (on the next frame) shows the payment-failed UI with:

User action	SDK behavior
Retry	Calls optional onRetryPayment, then re-opens submit-order with the same card.
Add new card	Opens add-card (using the same submit-order paymentRequest), then re-opens submit-order with the new CardData.
Use another card	Lets the user pick a saved card, then re-opens submit-order with that card.

You do not implement onNewCardAdded — failure recovery is handled inside the SDK.

await PayOrc.submitOrder(
  context,
  card: card, // CardData with paymentToken for new-card checkout
  paymentRequest: submitOrderRequest,
  mountedCheckContext: context, // optional; used for mounted checks (defaults to context)
  onSuccessPayment: (submittingContext) {
    // User dismissed the success confirmation sheet
  },
  onPaymentFailed: (submitModalContext, message, {code}) {
    // Optional — runs before SDK shows the failure sheet (analytics, logging)
  },
  onRetryPayment: () {
    // Optional — user tapped Retry on the failure sheet
  },
);

Parameter	Type	Required	Description
context	BuildContext	yes	Host context used to present the submit-order modal.
card	CardData	yes	Card to charge. New-card flow needs paymentToken on CardData (from add-card / onAddNewCard).
paymentRequest	PaymentRequest	yes	Submit-order payload (PaymentRequestType.submitOrder). Also used for failure-sheet saved cards and Add new card.
onSuccessPayment	void Function(BuildContext)?	no	Called when the user finishes the success confirmation sheet; receives submit-order sheet context.
mountedCheckContext	BuildContext?	no	Context checked with mounted before showing failure UI (defaults to context).
onPaymentFailed	void Function(BuildContext submitModalContext, String message, {String? code})?	no	Optional hook when /sdk/payment fails; SDK still presents failure / retry UI.
onRetryPayment	VoidCallback?	no	Optional hook when the user taps Retry; SDK re-presents submit-order afterward.

Returns Future<void> that completes when the submit-order modal is dismissed.

---

Related APIs (short)

API	Purpose
PayOrc.addNewCard / PayOrc.submitOrder	Add-card and submit-order modals (PayOrc); see §3.
Embedded widgets	§5 Embedded payment methods — compose checkout without showOptionsSheet.
PaymentRequest.deriveForAddCard	Build add-card request from a submit-order request.

---

License

See the repository or package metadata for license terms.