payorc_flutter_v2 1.0.3

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.0

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(0xFF000000),
    secondary: Color(0xFF000000),
  ),
  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 (primary/secondary colors; optional body/title font families). Non-null fields merge with prior customization.
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

Passed as text: on PayorcSdk.customization. Only non-null fields apply; each call merges with previous overrides.

Field	Type	Description
primary	Color?	Primary text on light surfaces / brand chrome (same role as former textPrimary).
secondary	Color?	Secondary / supporting text (same role as former textSecondary).
bodyFontFamily	PayorcSdkFontFamily?	Optional body/label font from SDK bundled font families.
titleFontFamily	PayorcSdkFontFamily?	Optional display/headline/title font from SDK bundled font families.
fontWeight	FontWeight?	Global default text weight.
letterSpacing	double?	Global default letter spacing.
textAlign	TextAlign?	Global default text alignment.
maxLines	int?	Global default max lines for SDK text widgets.
overflow	TextOverflow?	Global default overflow behavior.
decoration	TextDecoration?	Global default text decoration.
wordSpacing	double?	Global default word spacing.
softWrap	bool?	Global default soft-wrap behavior.
shadows	List<Shadow>?	Global default text shadows.
fontStyle	FontStyle?	Global default text style (normal / italic).

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.