Implementation

1. Session Token Generation #

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:

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.NFC // For NFC transactions
)

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. Starting the Payment Flow #

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")
        }
    }
}

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

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

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