React Native

Fiuu React Native payment module for iOS and Android.

Repository: Mobile-XDK-Fiuu_React_Native

Package: fiuu-mobile-xdk-reactnative on npm (1.0.27+)

Wiki: Installation Guide

The GitHub repository is an example + docs project. It does not contain the XDK library source — install the published npm package.

Requirements

Requirement	Version
npm plugin	fiuu-mobile-xdk-reactnative 1.0.27+
Node.js	22.13.0+ (example app on RN 0.87)
React Native	0.76+ (example app: 0.87)
Minimum Android SDK (minSdkVersion)	26+
Android compile SDK	37+ (required by Fiuu Android Library 3.34.41+)
Xcode	15+
Minimum iOS	16+

Bundled native SDK versions

Platform	Dependency	Version
Android	com.github.FiuuPayment:Mobile-XDK-Fiuu_Android_Library (JitPack)	3.34.41
iOS	FiuuXDKSwift (CocoaPods, via the plugin podspec)	1.1.1

Installation

npm install fiuu-mobile-xdk-reactnative@1.0.27

TypeScript types ship with the package. Do not add a manual declare module 'fiuu-mobile-xdk-reactnative' stub.

Android

1. Ensure JitPack is in the host app repositories (settings.gradle or android/build.gradle):

maven { url 'https://jitpack.io' }

2. Set minSdk 26 and compileSdk 37.
3. Rebuild the Android app. The library autolinks via React Native CLI (RN 0.76+).

iOS

cd ios && pod install && cd ..

pod install pulls FiuuXDKSwift 1.1.1 automatically. If CocoaPods reports a Swift/xcframework linking error, enable static frameworks in your Podfile:

ENV['USE_FRAMEWORKS'] = 'static'

Add the following to your app Info.plist:

Key	Value
App Transport Security Settings → Allow Arbitrary Loads	YES
NSPhotoLibraryUsageDescription	Payment images
NSPhotoLibraryAddUsageDescription	Payment images

Payment Details Object

var paymentDetails = {
  'mp_username': 'username',
  'mp_password': 'password',
  'mp_merchant_ID': 'merchantid',
  'mp_app_name': 'appname',
  'mp_verification_key': 'vkey123',
  'mp_amount': '1.10',
  'mp_order_ID': 'orderid123', // Must be unique per payment attempt
  'mp_currency': 'MYR',
  'mp_country': 'MY',
  'mp_channel': 'multi',
  'mp_bill_description': 'billdesc',
  'mp_bill_name': 'billname',
  'mp_bill_email': 'email@domain.com',
  'mp_bill_mobile': '+1234567',
  'mp_express_mode': false,
  'mp_allowed_channels': ['credit', 'credit3'],
  'mp_language': 'EN',
};

See Payment Parameters for the complete parameter list.

Unique order ID

Generate a new mp_order_ID for every payment attempt (for example Date.now() plus a random suffix). Reusing an order ID can cause transaction failures.

Start Payment

The JavaScript wrapper validates mp_merchant_ID, mp_verification_key, and mp_amount before calling native code. Missing or placeholder values are returned immediately to errorCallback as a plain string — no backend transaction is created.

Always provide both successCallback and errorCallback so your app can handle success, failure, cancellation, and validation errors reliably.

import fiuupayment from 'fiuu-mobile-xdk-reactnative';

fiuupayment.startFiuu(
  paymentDetails,
  (data) => {
    // successCallback — StatCode "00" (captured)
    console.log('Payment result:', data);
    // data is a plain object: data.StatCode, data.TranID, data.VrfKey, etc.
  },
  (error) => {
    // errorCallback — validation errors (string) OR failed backend payload (object)
    console.log('Payment error:', error);
    if (typeof error === 'object' && error.StatCode) {
      console.log(error.ErrorCode, error.ErrorDesc);
    }
  }
);

Response format

Both Android and iOS return the raw backend payload as a plain JavaScript object in your callbacks — not an encoded or double-stringified JSON string. The JavaScript layer parses Android JSON strings before invoking your callback; iOS returns dictionaries that are normalized the same way.

Callback	When it fires	Payload type
successCallback	StatCode / status_code is "00"	Object
errorCallback	StatCode is "22" (pending, cash channels)	Object (raw backend payload)
errorCallback	StatCode / status_code is "11" or other failure codes	Object (raw backend payload)
errorCallback	Missing credentials, native module not linked, no Activity/window	String

Route business logic using the status field present in the payload:

• "00" → successCallback — payment captured / successful
• "22" → errorCallback with object payload — pending (cash channels); not a final success
• "11" → errorCallback — failed / canceled — inspect ErrorCode / ErrorDesc (Google Pay / Apple Pay) or err_desc (standard channels)

Platform parity

Access fields directly (data.StatCode, data.TranID, etc.). Do not call JSON.stringify() on the callback argument unless you need a string for logging or storage — the library already parses backend JSON for you.

Standard channel result (Fiuu XDK checkout)

Standard webview checkout (when mp_channel is set) returns the legacy format:

{
  "status_code": "00",
  "amount": "1.00",
  "chksum": "abcdefghijklmnopqrstuvwxyz1234567890",
  "pInstruction": 0,
  "msgType": "C6",
  "paydate": 1741858781,
  "order_id": "1741858760492",
  "err_desc": "",
  "channel": "credit",
  "app_code": "",
  "txn_ID": "2754048669",
  "mp_secured_verified": false
}

Verify on your backend with:

chksum = MD5(mp_merchant_ID + msgType + txn_ID + amount + status_code + secret_key)

See Response Handling for the full standard format reference.

Google Pay / Apple Pay result

Google Pay (omit mp_channel) and Apple Pay return the StatCode format.

Sample successful result:

{
  "StatCode": "00",
  "StatName": "captured",
  "TranID": "30824452",
  "Amount": "1.11",
  "Domain": "SB_molpayxdk",
  "VrfKey": "7c34xxxxxxxxxxxxxxxxxxxxxxxx2000",
  "Channel": "credit",
  "OrderID": "1717661730213",
  "Currency": "MYR",
  "ErrorCode": null,
  "ErrorDesc": null
}

Sample failed result:

{
  "StatCode": "11",
  "StatName": "failed",
  "TranID": "3930144154",
  "Amount": "1.01",
  "Domain": "SB_molpayxdk",
  "Channel": "GooglePay",
  "OrderID": "1786112102436041689",
  "Currency": "MYR",
  "ErrorCode": "GOOGLEPAY_PE",
  "ErrorDesc": "Payment aborted."
}

Pre-flight validation error (string):

When required fields are missing or the native module is unavailable, errorCallback receives a plain string:

Missing or invalid required payment field(s): mp_merchant_ID, mp_verification_key. Please provide valid Fiuu merchant credentials before starting a payment.

Verify Google Pay / Apple Pay payments on your backend using:

VrfKey = md5(Amount + secret_key + Domain + TranID + StatCode)

See Response Handling for full parameter reference.

Google Pay (Android only)

Omit mp_channel to launch the Google Pay flow automatically on Android.

var paymentDetails = {
  'mp_sandbox_mode': true,
  'mp_core_env': '4', // Sandbox — use '2' or omit for production
  'mp_merchant_ID': 'YOUR_MERCHANT_ID',
  'mp_verification_key': 'YOUR_VERIFICATION_KEY',
  'mp_order_ID': `${Date.now()}${Math.floor(Math.random() * 1_000_000)}`,
  'mp_currency': 'MYR',
  'mp_country': 'MY',
  'mp_amount': '1.01',
  'mp_bill_description': 'Test Google Pay',
  'mp_bill_name': 'GPay',
  'mp_bill_email': 'example@gmail.com',
  'mp_bill_mobile': '123456789',
  'mp_company': 'Your Company Name', // Merchant name shown in Google Pay UI
  'mp_gpay_channel': ['SHOPEEPAY', 'TNG-EWALLET', 'CC'], // Optional — limit payment methods
  'mp_extended_vcode': false,
};

SHOPEEPAY and TNG-EWALLET apply to MY / MYR only; other countries support CC (card). See Payment Parameters for all Google Pay options.

Production requirements:

• Follow Google's production access guide (Gateway integration type).
• Register your app package name + signing certificate SHA-1 fingerprint with Google Pay / Fiuu for your merchant account.
• Debug builds fail with signing-key mismatch until registered.
• Use a signed release build with production credentials (mp_sandbox_mode: false).

Apple Pay (iOS only)

var paymentDetails = {
  'mp_express_mode': true,
  'mp_allowed_channels': ['ApplePay'],
  'mp_channel': 'ApplePay',
  'mp_merchant_ID': 'YOUR_MERCHANT_ID',
  'mp_verification_key': 'YOUR_VERIFICATION_KEY',
  'mp_ap_merchant_ID': 'YOUR_APPLE_PAY_MERCHANT_ID',
  'mp_order_ID': `${Date.now()}${Math.floor(Math.random() * 1_000_000)}`,
  'mp_currency': 'MYR',
  'mp_country': 'MY',
  'mp_amount': '1.01',
  'mp_bill_description': 'Test Apple Pay',
  'mp_bill_name': 'Apple Pay',
  'mp_bill_email': 'example@gmail.com',
  'mp_bill_mobile': '123456789',
  'mp_extended_vcode': false,
};

Requirements:

1. Plugin 1.0.27 or later (hides the standard XDK webview behind the Apple Pay sheet)
2. Valid Fiuu merchant account with Apple Pay enabled
3. Enable the Apple Pay capability on your app target in Xcode (Signing & Capabilities). Xcode writes the entitlements locally — do not copy an entitlements file from the sample repo
4. mp_ap_merchant_ID set to your Apple Pay merchant identifier from Apple Developer (this is not your Fiuu merchant ID)
5. Test on a real device with Apple Pay configured (simulator support is limited)

Cash channel payments

Cash channels return pending status ("22") on first completion. To re-display payment instructions later, pass mp_transaction_id from the earlier result. See Payment Parameters — Cash Channel Payment Process.

Environment configuration

Set mp_core_env to select the XDK environment. See Core Integration for the full environment table.

mp_core_env	Environment	Base URL
1	Production - V1	https://pay.fiuu.com/RMS/API/xdk/
2	Production - V2	https://xdk.fiuu.com/
3	UAT - V2	https://uat-xdk.fiuu.com/
4	Sandbox - V2	https://sandbox-xdk.fiuu.com/
(default)	Production - V2	https://xdk.fiuu.com/

Example app UI notes

The repository includes FiuuReactExampleProject/ (FiuuReactExampleProject/App.tsx) as the merchant-style reference — both callbacks are captured into app state rather than only showing a transient alert.

• Android: use Theme.AppCompat.Light.NoActionBar (or hide the action bar) to prevent the native action bar from flashing when returning from the Fiuu payment Activity.
• iOS: the plugin presents the Fiuu SDK in a full-screen modal. For Apple Pay (plugin 1.0.27+), the webview stays hidden so only the Apple Pay sheet is visible.

Deeplink Setup

React Native requires a DeeplinkActivity for e-wallet redirection. See Deeplink Setup.

Test with:

npx react-native run-android --mode=release

Related Guides

• Expo — Expo-managed workflow variant
• Payment Parameters
• Deeplink Setup
• Response Handling
• Core Integration
• Installation Guide (Wiki)