Implementation

1. Session Token Generation #

This needs to be generated from the backend side. The API to generate a SessionToken is mentioned in Section 4. First, you need to generate a session token using the following code:

val sessionToken = networkClient.fetchSessionToken(
    env = AmwalSDK.Config.Environment.UAT, // or SIT, PROD
    merchantId = "YOUR_MERCHANT_ID",
    customerId = null, // Optional
    secureHashValue = "YOUR_SECURE_HASH"
)

2. SDK Configuration #

Configure the SDK with the required parameters:

UUID Generation #

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

// Generate a UUID for transaction ID
val transactionId = AmwalSDK.Config.generateTransactionId()

// Or generate a custom UUID manually
val customUUID = UUID.randomUUID().toString().lowercase()

The UUID generator creates lowercase UUIDs, 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 including UI customization and payment flow control.

Default Addition Values #

The SDK automatically provides default values:

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

Available Configuration Options #

UI Customization #

• useBottomSheetDesign: "true" | "false" (default: "false")
• Controls the payment screen design
• "true": Uses the newer bottom sheet design (v2) – slides up from bottom covering 90% of screen
• "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 compatibility

Usage #

// Using default additionValues
val config = AmwalSDK.Config(
    environment = AmwalSDK.Config.Environment.UAT,
    sessionToken = sessionToken,
    currency = AmwalSDK.Config.Currency.OMR,
    amount = "100",
    merchantId = "your_merchant_id",
    terminalId = "your_terminal_id",
    locale = Locale("en"),
    customerId = null,
    transactionType = AmwalSDK.Config.TransactionType.CARD_WALLET,
    transactionId = AmwalSDK.Config.generateTransactionId(),
    additionValues = AmwalSDK.Config.generateDefaultAdditionValues()
)

// Using custom additionValues with bottom sheet design and colors
val customAdditionValues = mapOf(
    "merchantIdentifier" to "merchant.custom.identifier",
    "useBottomSheetDesign" to "true",
    "primaryColor" to "#FF5733",
    "secondaryColor" to "#33FF57",
    "ignoreReceipt" to "false"
)

val configWithCustomUI = AmwalSDK.Config(
    environment = AmwalSDK.Config.Environment.UAT,
    sessionToken = sessionToken,
    currency = AmwalSDK.Config.Currency.OMR,
    amount = "100",
    merchantId = "your_merchant_id",
    terminalId = "your_terminal_id",
    locale = Locale("en"),
    customerId = null,
    transactionType = AmwalSDK.Config.TransactionType.CARD_WALLET,
    transactionId = AmwalSDK.Config.generateTransactionId(),
    additionValues = customAdditionValues
)

// Minimal configuration with just bottom sheet design
val minimalCustomValues = mapOf(
    "useBottomSheetDesign" to "true"
)

val minimalConfig = AmwalSDK.Config(
    // ... other required parameters
    additionValues = minimalCustomValues
)

Note: All boolean values should be passed as strings ("true" or "false"). Custom additionValues will be merged with defaults, with custom values taking precedence.

Available Methods #

// Generate default addition values
val defaultValues = AmwalSDK.Config.generateDefaultAdditionValues()

// Generate a transaction ID
val transactionId = AmwalSDK.Config.generateTransactionId()

Configuration Example #

val config = AmwalSDK.Config(
    environment = AmwalSDK.Config.Environment.UAT, // or SIT, PROD
    sessionToken = sessionToken,
    currency = AmwalSDK.Config.Currency.OMR, // or other supported currencies
    amount = "1.00",
    merchantId = "YOUR_MERCHANT_ID",
    terminalId = "YOUR_TERMINAL_ID",
    locale = Locale("en"), // or "ar" for Arabic
    customerId = customerId, // Optional
    transactionType = AmwalSDK.Config.TransactionType.CARD_WALLET,
    transactionId = AmwalSDK.Config.generateTransactionId(), // Optional: Auto-generated if null
    additionValues = AmwalSDK.Config.generateDefaultAdditionValues(), // Optional: Custom key-value pairs
    merchantReference = "optional-merchant-reference" // Optional: Merchant reference for transaction tracking
)

3. Starting the Payment Flow #

amwalSDK.start(
    activity = this,
    config = config,
    onResponse = { response ->
        // Handle the payment response
        when (response) {
            is AmwalSDK.Response.Success -> {
                Log.d("Payment", "Transaction successful: ${response.transactionId}")
            }
            is AmwalSDK.Response.Error -> {
                Log.e("Payment", "Transaction failed: ${response.message}")
            }
            is AmwalSDK.Response.Cancelled -> {
                Log.d("Payment", "Transaction cancelled by user")
            }
        }
    },
    onCustomerId = { customerId ->
        // Handle the customer ID
        StorageClient.saveCustomerId(context, customerId)
    }
)

3. Configuration #

Config Parameters #

• environment: Environment to use (UAT, SIT, PROD)
• sessionToken: Session token from the backend API
• currency: Currency for the transaction (OMR)
• amount: Transaction amount as string
• merchantId: Your merchant identifier
• terminalId: Your terminal identifier
• locale: Language locale (en/ar)
• customerId: Optional customer identifier
• transactionType: Type of transaction (NFC, CARD_WALLET, GOOGLE_PAY)
• transactionId: Optional unique transaction identifier (auto-generated if null)
• additionValues: Optional custom key-value pairs for SDK configuration (includes merchantIdentifier for Apple Pay)

Supported Currencies #

• OMR (Omani Rial)

Transaction Types #

• NFC (Near Field Communication)
  • Use TransactionType.NFC for NFC transactions
  • Requires NFC hardware support
  • Requires NFC permission in manifest
• CARD_WALLET
  • Use TransactionType.CARD_WALLET for digital wallet transactions
  • Card-based payments
• GOOGLE_PAY
  • Use TransactionType.GOOGLE_PAY for Google Pay transactions
  • Requires Google Pay setup

Environment Support #

• SIT (System Integration Testing)
  • Use for initial development and testing
  • Test environment with mock data
• UAT (User Acceptance Testing)
  • Use for pre-production testing
  • Real environment with test data
• PROD (Production)
  • Use for live transactions
  • Real environment with real data

Security #

The SDK implements secure hash generation for API requests. Use the SecureHashUtil class to generate secure hashes:

val secureHash = SecureHashUtil.clearSecureHash(
    secretKey = "YOUR_SECRET_KEY",
    data = mutableMapOf(
        "merchantId" to merchantId,
        "customerId" to customerId
    )
)

Error Handling #

The SDK provides comprehensive error handling through callbacks. Always implement proper error handling in your application:

try {
    // SDK operations
} catch (e: AmwalSDKException) {
    when (e) {
        is AmwalSDKException.NetworkError -> {
            // Handle network-related errors
            showErrorDialog("Network connection error")
        }
        is AmwalSDKException.InvalidConfiguration -> {
            // Handle configuration errors
            showErrorDialog("Invalid configuration")
        }
        is AmwalSDKException.NFCNotAvailable -> {
            // Handle NFC-related errors
            showErrorDialog("NFC is not available")
        }
        else -> {
            // Handle other errors
            showErrorDialog("An unexpected error occurred")
        }
    }
}

4. Getting the SDK Session Token and Calculation of Secure Hash to call the API #

Endpoint to Fetch SDKSessionToken #

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 #

Header Value

Content-Type: application/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..."
  }
}