SDK API Reference
Reference tables for the Mobile Payment SDK v2.0.4 — every configuration attribute, enum, method, and exception, with the Kotlin and Swift names side by side. For guided integration steps see the Android, iOS, and Flutter pages.
PaymentSDKConfiguration attributes
Used at initialization and (per value) by the runtime update methods.
| Attribute | Sub-attribute | Description |
|---|---|---|
localization | Localization settings — replaces the removed v1.x language enums | |
availableLanguages | Languages the user can select from the SDK UI (ordered set). English and Arabic are used by default if none are set. | |
availableLanguages[].code | Language alpha-2 code (ISO 639-1): en, ar, ku (Kurdish), … null = follow the system language. Android wraps codes in LanguageCode (from nv-i18n); iOS uses plain strings. | |
availableLanguages[].name | Language name to display in the UI | |
selectedLanguageCode | UI language to apply. Any ISO 639-1 code; English is used by default. | |
writingDirection | RIGHT_TO_LEFT / rightToLeft, LEFT_TO_RIGHT / leftToRight, SYSTEM / auto. System direction by default. | |
theme | DARK / dark, LIGHT / light, SYSTEM / auto. System theme by default. | |
skipResultScreen | Skip the SDK's result screen. Boolean; false by default. | |
connectionSettings | Connection settings (URL, keys, certificates) | |
baseUrl | Payment gateway base URL | |
publicKey | Payment gateway public key | |
certificates | Payment scheme certificates (scheme, certificate, algorithm) | |
tdsSettings | 3DS authentication flow settings — replaces the v1.x flat authenticationFlow / tdssUICustomization | |
authFirst | Flow to try first: SDK (embedded 3DS SDK / application flow) or BROWSER (web-view flow). SDK by default. | |
authFallback | Fall back to the other flow if the first fails. Boolean; false by default. | |
tdssUICustomization | 3DS SDK UI customization per EMVCo requirements | |
paymentMethodChoice | Who renders the method-selection screen: ON_SDK / onSdk (SDK draws its chooser) or ON_APP / onApp (your app decides). ON_APP by default. | |
availablePaymentMethods | Methods offered in the UI (ordered set): PAYMENT_TOKEN, CARD, ALIPAY (Pay with SuperQi), AQSATI. PAYMENT_TOKEN + CARD by default — SuperQi is off unless you add ALIPAY. | |
aliPaySettings | Settings of the Pay with SuperQi (ALIPAY) method | |
showFirst | Option displayed first: QR or LINK (deep link). QR by default. | |
qrToDeepLinkFallback | Also show an "open the payment app" button next to the QR. Boolean; false by default. | |
deepLinkToQrFallback | Also show a QR (and app-download option) next to the deep-link button. Boolean; false by default. | |
merchant | Merchant display settings. Required on Android — build() throws SdkIllegalStateException without it. Optional on iOS. | |
name | Merchant name to display for the payment | |
logoUrlLight | Merchant logo URL for the light theme | |
logoUrlDark | Merchant logo URL for the dark theme | |
finishPaymentUri | iOS only. URI that returns the payer to your app after an external-wallet (SuperQi deep-link) payment, e.g. finon://payment. Must match a registered CFBundleURLTypes URL scheme; Android declares its scheme in AndroidManifest.xml instead. | |
language | Deprecated. v1.x UI language enum, kept for backward compatibility; localization.selectedLanguageCode has priority. | |
writingDirection | Deprecated. v1.x top-level direction; localization.writingDirection has priority. | |
tdssUICustomization | Deprecated. v1.x top-level 3DS customization; tdsSettings.tdssUICustomization has priority. |
Enums
| Enum | Kotlin values | Swift values | Notes |
|---|---|---|---|
AvailablePaymentMethods | CARD, ALIPAY, PAYMENT_TOKEN, AQSATI | .CARD, .ALIPAY, .PAYMENT_TOKEN, .AQSATI | ALIPAY = Pay with SuperQi; AQSATI = BNPL installments |
PaymentMethodChoice | ON_SDK, ON_APP | .onSdk, .onApp | SDK default: on-app |
PaymentTypeAliPay | QR, LINK | .QR, .LINK | AliPaySettings.showFirst |
AuthTypeTDS | SDK, BROWSER | .SDK, .BROWSER | TDSSettings.authFirst |
Theme | LIGHT, DARK, SYSTEM | .light, .dark, .system | |
WritingDirection | LEFT_TO_RIGHT, RIGHT_TO_LEFT, SYSTEM | .leftToRight, .rightToLeft, .auto | |
| Token type | AUTH, NON_RECUR, UNAUTH | same | See PaymentDetails.tokenType below |
SDK methods
| Method | Kotlin (Android) | Swift (iOS) |
|---|---|---|
| Initialize | PaymentSDK.initialize(context, config, exitCallback) | PaymentSDK(with: config) (instance) |
| Process payment | PaymentSDK.processPayment(paymentDetails, onSuccess, onError) | sdk.processPayment(paymentDetails, onSuccess:, onError:) — call inside Task { @MainActor } |
| Set customer info | — (passed in PaymentDetails.customerInfo) | sdk.setCustomerInfo(...) — must be called before payments to initialize local storage |
| Update configuration | PaymentSDK.updateConfiguration(value) — overloaded per type: method set, PaymentMethodChoice, AliPaySettings, LanguageCode, Theme, PaymentSDKLocalization | sdk.updatePaymentSDKConfiguration(theme:), (selectedLanguage:), (writingDirection:), (availablePaymentMethods:), (paymentMethodChoice:), (aliPaySettings:) |
| Get payment tokens | PaymentSDK.getPaymentTokens(accountId) → List<PaymentToken> | PaymentSDK.getPaymentTokens(for: accountId) → [PaymentToken] |
| Latest token transactions | PaymentSDK.getLatestTokenTransactions(paymentToken) | PaymentSDK.getLatestTokenTransactions(for: paymentToken) |
| Block payment token | PaymentSDK.blockPaymentToken(paymentToken) | PaymentSDK.blockPaymentToken(for: paymentToken) |
| Transfer payment tokens | PaymentSDK.transferPaymentTokens(accountId, tokens) | PaymentSDK.transferPaymentTokens(accountId, tokens) |
| Set gateway base URL / key | PaymentSDK.setPaymentGatewayBaseUrl(...) | PaymentSDK.setPaymentGatewayBaseUrl(...) |
| Set scheme certificate | PaymentSDK.setPaymentSchemaCertificate(scheme, certificate, algorithm) | PaymentSDK.setPaymentSchemaCertificate(for:with:algorithm:) |
| Form-closure subscription | Exit callback passed to initialize / PaymentSDK.exitSdk { ... } | Observe the finon_pay_sdk_on_back_click notification; confirm with sdk.cancel() |
Base URL normalization differs per platform
Android expects a trailing / on baseUrl and appends it itself; iOS strips it. Pass the raw URL
to each platform and let the native side normalize.
PaymentDetails attributes
| Attribute | Sub-attribute | Description |
|---|---|---|
paymentId | Payment identifier returned from the payment gateway | |
requestId | Request identifier from the application | |
customerInfo | Payer's data | |
accountId | Account (user) identifier. Must be non-null in v2.0.4. | |
amount | Payment amount (null for non-payment operations) | |
currency | Payment currency | |
paymentMethod | Method for the payment | |
paymentType | PAYMENT_TOKEN, CARD, ALIPAY (Pay with SuperQi), or AQSATI | |
paymentToken | PaymentToken.id when paymentType is PAYMENT_TOKEN | |
nonPaymentOperation | Marks a non-payment operation; amount must be null | |
withoutAuthenticate | Operation without payer authentication | |
needPaymentToken | Generate a paymentToken from a successful payment; must be true for non-payment operations | |
tokenType | Requested token type, in descending capability: AUTH (any operations), NON_RECUR (any except recurring), UNAUTH (authentication only). If the requested capability is lower than what the operation produced, the requested type is returned; otherwise the resulting token is returned. | |
additionalInfo | Extra display data as <key1>:<value1>,<key2>:<value2>,… | |
aPlusWalletId | Wallet identifier for Facial Recognition Authentication |
Exceptions
| Exception | Thrown when |
|---|---|
SDKNotInitializedException | An SDK feature is used before initialization completed |
SDKAlreadyInitializedException | initialize is called again within the same application lifecycle |
SDKRuntimeException | Unexpected runtime error (network, server, invalid input) during an SDK operation |
SdkIllegalStateException | Android: PaymentSDKConfiguration.Builder().build() called without setMerchant(...) |
Handling examples for each are on the Android and iOS pages.
Flutter channel quick reference
Channel name: payment_sdk_flutter — full wrapper and bridge code in
Flutter Integration.
| Channel method | Purpose | Key arguments |
|---|---|---|
initializeSDK | Build the native config and initialize the SDK | baseUrl, publicKey, terminalId, authUsername, authPassword, language (english/arabic/kurdish/auto), theme, writingDirection, availablePaymentMethods (List<String>), paymentMethodChoice, aliPayShowFirst, merchantName, merchantLogoUrlLight, merchantLogoUrlDark |
processPayment | Run a payment through the native SDK UI | paymentId, requestId, amount, currency, accountId, paymentType, paymentToken, needPaymentToken, tokenType, additionalInfo |
getPaymentTokens | Saved tokens for an account | accountId |
updatePaymentMethods | Reconfigure a running SDK | availablePaymentMethods, paymentMethodChoice, aliPayShowFirst |
| Channel error code | Platform | Meaning |
|---|---|---|
SDK_NOT_INITIALIZED | both | Called before initializeSDK succeeded |
SDK_ALREADY_INITIALIZED | both | initializeSDK called twice |
PAYMENT_ERROR | both | Payment failed or was cancelled |
UPDATE_ERROR | Android | Runtime reconfiguration failed |
INVALID_ARGUMENTS | iOS | Malformed argument map |