View Categories

Implementation

A React Native library for integrating the Amwal Pay payment gateway into your React Native applications.

Prerequisites #

  • React Native project (0.79+)
  • Node.js 18 or higher
  • iOS: Xcode and CocoaPods installed
  • Android: Android Studio and JDK installed

Step 1: Install the Package #

npm install react-amwal-pay
# or
yarn add react-amwal-pay

Step 2: Configure React Native (Required) #

Create or update react-native.config.js in your project root:

const path = require('path');
const pkg = require('react-amwal-pay/package.json');

module.exports = {
  project: {
    ios: {
      automaticPodsInstallation: true,
    },
  },
  dependencies: {
    [pkg.name]: {
      root: path.join(__dirname, 'node_modules/react-amwal-pay'),
      platforms: {
        ios: {},
        android: {},
      },
    },
  },
};

Step 3: iOS Setup #

3.1 Update Podfile #

Add the following configuration to your ios/Podfile inside the post_install block:

post_install do |installer|
  react_native_post_install(installer, config[:reactNativePath])

  # Set "Build Libraries for Distribution" to NO for amwalsdk
  installer.pods_project.targets.each do |target|
    if target.name == 'amwalsdk'
      target.build_configurations.each do |config|
        config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'NO'
        config.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'x86_64'
      end
    end
  end
end

3.2 Install Pods #

cd ios
pod install
cd ..

3.3 iOS Build Setting (Manual Step) #

After pod installation, you need to set “Build Libraries for Distribution” to NO in Xcode:

  1. Open your iOS project in Xcode
  2. Go to Pods project
  3. Select amwalsdk target
  4. In Build Settings, search for “Build Libraries for Distribution”
  5. Set it to NO
Build Libraries Setting

3.4 Configuring amwalsdk Subspec (Optional) #

The library uses amwalsdk as a dependency and supports both Release and Debug subspecs. By default, it uses the Debug subspec. To change this, you can set the AMWAL_SUBSPEC environment variable in your Podfile:

# In your Podfile
ENV['AMWAL_SUBSPEC'] = 'Release' # or 'Debug'

Or you can set it when running pod install:

AMWAL_SUBSPEC=Release pod install

Step 4: Android Setup #

No additional Android configuration is required. The SDK uses React Native’s autolinking feature.

Note: The SDK requires minimum SDK 24 (Android 7.0). Ensure your android/build.gradle has:

minSdkVersion = 24

Step 5: Clean and Rebuild #

After installation, clean and rebuild your project:

# iOS
cd ios
rm -rf Pods Podfile.lock
pod install
cd ..

# Android
cd android
./gradlew clean
cd ..

# Rebuild your app
npm run ios
# or
npm run android

Troubleshooting #

  • Pods fail to install: Clean pods and reinstall (rm -rf Pods Podfile.lock && pod install)
  • Linking issues: Ensure react-native.config.js is in your project root
  • Build errors: Clean build folders and rebuild your project
  • iOS build errors: Verify that “Build Libraries for Distribution” is set to NO for amwalsdk target

Usage #

import {
  AmwalPaySDK,
  Environment,
  Currency,
  TransactionType,
  UuidUtil,
  type AmwalPayConfig,
  type AmwalPayResponse
} from 'react-amwal-pay';

// Configure Amwal Pay
const config: AmwalPayConfig = {
  environment: Environment.SIT, // Environment.UAT or Environment.PRODUCTION
  currency: Currency.OMR, // or other supported currencies
  transactionType: TransactionType.CARD_WALLET,
  locale: 'en', // or 'ar'
  merchantId: 'xxxxx',
  terminalId: 'xxxxx',
  amount: '1',
  secureHash: 'GENERATED_HASH',
  customerId: 'customer-id', // optional
  sessionToken: 'your-session-token',
  transactionId: 'custom-transaction-id', // optional: auto-generated if not provided
  merchantReference: 'optional-merchant-reference', // optional: merchant reference for transaction tracking
  additionValues: { // optional: custom key-value pairs for SDK configuration
    merchantIdentifier: 'merchant.applepay.amwalpay', // for Apple Pay configuration
    useBottomSheetDesign: 'true', // use bottom sheet design (v2)
    primaryColor: '#FF5733', // custom primary color
    secondaryColor: '#33FF57', // custom secondary color
    ignoreReceipt: 'false' // show receipt after transaction
  },
  onCustomerId(customerId) {
    console.log('Customer ID:', customerId);
  },
  onResponse(response) {
    console.log('Payment Response:', response);
  }
};

// Initialize and start payment
const handlePayment = async () => {
  try {
    // Validate required fields
    if (!isConfigValid(config)) {
      console.error('Please fill in all required fields');
      return;
    }

    const amwalPay = AmwalPaySDK.getInstance();
    await amwalPay.startPayment(config);
  } catch (error) {
    console.error('Error starting payment:', error);
  }
};

// Helper function to validate config
const isConfigValid = (config: Partial<AmwalPayConfig>): boolean => {
  return Boolean(
    config.environment &&
    config.secureHash &&
    config.currency &&
    config.amount &&
    config.merchantId &&
    config.terminalId &&
    config.locale &&
    config.transactionType
  );
};

UUID Generation #

If you need to generate a custom transaction ID, you can use the built-in UUID utility:

import { UuidUtil } from 'react-amwal-pay';

// Generate a UUID for transaction ID
const transactionId = UuidUtil.generateTransactionId();

// Or use the lower-level generator
const uuid = UuidUtil.generateV4();

The UUID utility generates lowercase UUIDs in v4 format, ensuring compatibility with the payment system.

Addition Values Configuration #

The SDK supports additionValues parameter for passing custom key-value pairs that can be used for various SDK functionalities.

Default Addition Values #

The SDK automatically provides default values:

  • merchantIdentifier: “merchant.applepay.amwalpay” (used for Apple Pay configuration)

Available Configuration Options #

You can customize the SDK behavior using the following additionValues keys:

UI Customization #

  • useBottomSheetDesign: 'true' | 'false' (default: 'false')
  • Controls the payment screen design
  • 'true': Uses the newer bottom sheet design (v2)
  • 'false': Uses the original full-screen design
  • primaryColor: Hex color string (e.g., '#FF5733')
  • Sets the primary theme color for the SDK UI
  • secondaryColor: Hex color string (e.g., '#33FF57')
  • Sets the secondary theme color for the SDK UI

Payment Flow #

  • ignoreReceipt: 'true' | 'false' (default: 'false')
  • Controls whether to show the receipt screen after transaction
  • 'true': Skips the receipt display
  • 'false': Shows the receipt screen
  • merchantIdentifier: String (default: 'merchant.applepay.amwalpay')
  • Apple Pay merchant identifier for iOS

Usage Examples #

// Using default additionValues (automatically applied)
const config = {
  // ... other configuration
  // additionValues will automatically include merchantIdentifier
};

// Using custom additionValues with UI customization
const customConfig = {
  // ... other configuration
  additionValues: {
    useBottomSheetDesign: 'true',
    primaryColor: '#FF5733',
    secondaryColor: '#33FF57',
    ignoreReceipt: 'false',
    merchantIdentifier: 'merchant.custom.identifier'
  }
};

// Minimal configuration with bottom sheet design
const minimalConfig = {
  // ... other configuration
  additionValues: {
    useBottomSheetDesign: 'true'
  }
};

Custom additionValues will be merged with defaults, with custom values taking precedence.

Note: All boolean values should be passed as strings ('true' or 'false').

Configuration #

The AmwalPayConfig interface includes the following properties:

  • environment: The environment to use (SIT or UAT or PRODUCTION)
  • currency: The currency for the transaction (e.g., OMR)
  • transactionType: The type of transaction (e.g., CARD_WALLET)
  • locale: The language locale (‘en’ or ‘ar’)
  • merchantId: Your merchant ID
  • terminalId: Your terminal ID
  • amount: The transaction amount
  • secureHash: Your secure hash for authentication
  • customerId: (Optional) The customer’s ID
  • sessionToken: Your session token
  • transactionId: (Optional) Unique transaction identifier – auto-generated if not provided
  • merchantReference: (Optional) Merchant reference for transaction tracking
  • additionValues: (Optional) Custom key-value pairs for SDK configuration (includes merchantIdentifier for Apple Pay)
  • onCustomerId: (Optional) Callback function for customer ID updates
  • onResponse: (Optional) Callback function for payment response

Getting the SDK Session Token #

Environment URLs #

Stage #

  • Base URL: https://test.amwalpg.com:14443
  • Endpoint: Membership/GetSDKSessionToken

Production #

  • Base URL: https://webhook.amwalpg.com
  • Endpoint: Membership/GetSDKSessionToken

Description #

This endpoint retrieves the SDK session token.

Headers #

HeaderValue
Content-Typeapplication/json

Sample Request #

{
  "merchantId": 22914,
  "customerId": "ed520b67-80b2-4e1a-9b86-34208da10e53",
  "requestDateTime": "2025-02-16T12:43:51Z",
  "secureHashValue": "AFCEA6D0D29909E6ED5900F543739975B17AABA66CF2C89BBCCD9382A0BC6DD7"
}

Sample Response #

{
  "success": true,
  "message": "Success",
  "data": {
    "sessionToken": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0..3yAPVR3evEwvIdq808M2uQ..."
  }
}
Updated on January 28, 2026

What are your Feelings

  • Happy
  • Normal
  • Sad