payorc_flutter_v2 1.0.5

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.
• A PayOrc merchant key and merchant secret.
• Optional Tabby credentials if you enable Tabby (tabbyApiKey).

Installation

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

dependencies:
  payorc_flutter_v2: ^1.0.5

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
  tabbyApiKey: 'pk_test_...',            // optional; omit to disable Tabby
  tabbyMerchantCode: 'ae',               // Tabby region / merchant code (e.g. ae, sa)
  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.
tabbyApiKey	String?	no	Tabby public key; when set, Tabby SDK is configured and Tabby can appear in the options sheet.
tabbyMerchantCode	String	no	Tabby merchant code (default 'ae').
language	PayorcLanguage	no	SDK language / text direction (english, arabic). Default english.

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. Omitted parameters leave previous or API-driven values in place where applicable.

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: const [
      Shadow(color: Color(0x33000000), blurRadius: 2, offset: Offset(0, 1)),
    ],
    fontStyle: FontStyle.normal,
  ),
  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',
    ),
  ),
  borderColor: const Color(0xFF000000),
);

Parameters

Parameter	Type	Description
inputBorderStyle	PayorcInputBorderStyle?	outline or underline for SDK text fields.
guidanceStyle	PayorcGuidanceStyle?	label or hint guidance for AppTextField input text.
appBarStyle	PayorcAppBarStyle?	nativeAndroid or nativeIos for SDK app bars; platform default if unset.
brandColor	Color?	Sheet / header brand fill. Fully transparent colors are ignored (fall back).
button	PayorcSdkButtonCustomization?	Primary CTA styling (background, label color, outline, radius, height, loading color, etc.). Non-null fields merge with prior customization.
accentColor	Color?	Secondary accent (links, highlights, borders where used).
text	PayorcSdkTextCustomization?	Typography overrides: colors, bundled PayorcSdkFontFamily for body vs titles, and optional defaults (fontWeight, fontSize, letterSpacing, textAlign, line/clipping and decoration fields). Non-null fields merge with prior customization and fall back to checkout API values when unset.
cardFormValidation	PayorcSdkCardFormValidationCustomization?	Add-card validator message overrides. If a message is null/empty, SDK default validation text is used.
borderColor	Color?	Default border / stroke color for SDK chrome; when unset, default is #CCCCCC.

---

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

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

await PayorcSdk.instance.showOptionsSheet(
  context,
  paymentRequest: request,
  onAddNewCard: (CardData input) {
    // User completed add-card / card details — continue checkout (e.g. submit order).
  },
  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	Called when the user adds or confirms card data from the flow.
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.

---

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

Value	Use
label	Show input guidance as floating label text.
hint	Show input guidance as hint/placeholder text.

PayorcSdkTextCustomization

Defined in lib/src/customization/payorc_sdk_text_customization.dart. 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.

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. See lib/data/models/payment_request.dart.
• CardData — Cardholder, expiry, CVV, optional email/phone, tokens for saved cards. See lib/data/models/card_data.dart.
• PayorcSdk.instance — Throws if PayorcSdk.init was not called; use PayorcSdk.isInitialized to guard.

---

Related APIs (short)

| API | Purpose | | ------------------------------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | --- | | | | | | | | PayOrc.addNewCard / PayOrc.submitOrder | Lower-level add-card and submit-order sheet helpers (src/payorc.dart). | | |

---

License

See the repository or package metadata for license terms.