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

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

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)
borderColor	border_color
textPrimary or text.primary	text_primary
textSecondary or text.secondary	text_secondary
autoselectColor	autoselect_color

appTextField.borderColor overrides resting field strokes for AppTextField only (after generic borderColor). 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,
  ),
  borderColor: const Color(0xFF000000),
  autoselectColor: 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 (text.primary / merchant_details.text_primary). Same role as text: PayorcSdkTextCustomization(primary: …).
textSecondary	Color?	Shorthand for secondary text color (text.secondary / 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.
borderColor	Color?	Default resting border for SDK chrome and fields. Host → checkout border_color → #CCCCCC.
autoselectColor	int?	ARGB integer for auto-selected payment method highlight. Host → checkout autoselect_color.

---

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.

Request body support for add-card and payments

The SDK now supports passing a full request payload for both add-card and wallet/payment flows. This includes:

• PaymentRequest with order, customer, billing, shipping, and urls details
• Urls(webhookUrl: ...) included in add-card, submit-order, Tabby, Apple Pay, and Google Pay request payloads
• action parameter in PaymentRequest.submitOrder is now dynamic and can be overridden by the merchant (defaults to "AUTH")
• wallet submissions sent to the SDK /sdk/wallet/payment endpoint with the appropriate wallet type

If you need to customize the request body, build or extend PaymentRequest and pass it directly to the SDK flows.

Example request payloads

Here is a concrete example of the request bodies you can pass for a submit-order flow and an add-card flow:

final PaymentRequest paymentRequest = PaymentRequest.submitOrder(
  action: 'AUTH', // Optional; defaults to 'AUTH'
  paymentToken: '',
  orderDetails: [
    OrderDetails(
      mOrderId: '',
      amount: '1.00',
      currency: 'AED',
      description: '',
      convenienceFee: '',
      quantity: '',
    ),
  ],
  customerDetails: const CustomerDetails(
    mCustomerId: '1',
    name: 'Asif Ali',
    email: 'asif.ali@payorc.com',
    mobile: '500000000',
    code: '971',
  ),
  billingDetails: const BillingDetails(
    addressLine1: 'Dubai Marina',
    addressLine2: '',
    city: '',
    country: 'AE',
    province: '',
    pin: '',
  ),
  shippingDetails: const ShippingDetails(
    shippingName: '',
    shippingEmail: '',
    shippingCode: '',
    shippingMobile: '',
    addressLine1: '',
    addressLine2: '',
    city: '',
    province: '',
    country: '',
    pin: '',
    locationPin: '',
    shippingCurrency: '',
    shippingAmount: '',
  ),
  urls: const Urls(
    webhookUrl: 'https://webhook.site/f8f5c5b4-a4c5-4e0f-acf5-13f4ccca7543',
  ),
);

final PaymentRequest addCardRequest = PaymentRequest.addCard(
  customerDetails: const CustomerDetails(
    mCustomerId: '1',
    name: 'Asif Ali',
    email: 'asif.ali@payorc.com',
    mobile: '',
    code: '',
  ),
  billingDetails: const BillingDetails(
    addressLine1: 'Dubai Marina',
    addressLine2: '',
    city: '',
    country: 'AE',
    province: '',
    pin: '',
  ),
  shippingDetails: const ShippingDetails(
    shippingName: '',
    shippingEmail: '',
    shippingCode: '',
    shippingMobile: '',
    addressLine1: '',
    addressLine2: '',
    city: '',
    province: '',
    country: '',
    pin: '',
    locationPin: '',
    shippingCurrency: '',
    shippingAmount: '',
  ),
  urls: const Urls(
    webhookUrl: 'https://webhook.site/f8f5c5b4-a4c5-4e0f-acf5-13f4ccca7543',
  ),
  orderDetails: [
    OrderDetails.forAddCard(
      currency: 'AED',
      amount: '10',
    ),
  ],
);

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.

---

4. Helper methods for wallet and Tabby flows

These helpers let you trigger the relevant checkout flow directly without embedding the full sheet.

PayOrc.addNewCard

Use this when you want to open the add-card form directly.

PayOrc.addNewCard(
  context,
  paymentRequest: paymentRequest,
  onAddCard: (sheetContext, card) {
    // Handle the newly entered card
  },
);

The add-card request uses the same full PaymentRequest payload shape, including urls and webhook metadata when provided.

PayOrc.tabby

Use this to launch the Tabby checkout flow directly.

PayOrc.tabby(
  context: context,
  paymentRequest: paymentRequest,
  onTabbyAuthorized: (launchingContext, merchantResponse) {
    // Handle Tabby authorization response
  },
  onTabbyError: (error) {
    // Handle Tabby failure
  },
);

The Tabby request includes the full PaymentRequest payload and forwards webhook details through the request body.

PayOrc.googlePay

Use this to launch Google Pay directly on Android.

PayOrc.googlePay(
  paymentRequest: paymentRequest,
  onPaymentSuccess: (response) {
    // Final SDK payment response after Google Pay token submission
  },
  onGooglePayError: (error) {
    // Handle Google Pay failure
  },
);

This helper submits the Google Pay wallet token to the backend and returns the final payment response via onPaymentSuccess.

PayOrc.applePay

Use this to launch Apple Pay directly on iOS.

PayOrc.applePay(
  paymentRequest: paymentRequest,
  onApplePayResult: (result) {
    // Raw Apple Pay token payload from the pay package
  },
  onApplePayError: (error) {
    // Handle Apple Pay failure
  },
);

Apple Pay follows the same request-body pattern and can carry webhook URLs when included in the PaymentRequest.

---

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

Defined in lib/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.

PayorcSdkAddCardFormCustomization

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

Defined in lib/customization/payorc_sdk_app_text_field_customization.dart. 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; overrides generic borderColor on customization for text fields when set.

PayorcSdkBottomSheetCustomization

Defined in lib/customization/payorc_sdk_bottom_sheet_customization.dart. 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. Supports customizable action parameter for payments (e.g. "AUTH", "SALE"). 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.