Implementation

1. Import the SDK in your Swift file:

import amwalsdk

2. Configure the payment parameters:

// First, fetch the session token
let networkClient = NetworkClient()
networkClient.fetchSessionToken(
    env: .UAT,  // Available options: .UAT, .PROD, .SIT
    merchantId: "YOUR_MERCHANT_ID",
    customerId: nil,  // Optional, only needed for saved card functionality
    secureHashValue: "YOUR_SECURE_HASH"
) { sessionToken in
    if let token = sessionToken {
        // Create the configuration with the session token
        let config = Config(
            environment: .UAT,  // Available options: .UAT, .PROD, .SIT
            sessionToken: token,
            currency: .OMR,     // Available options: .OMR,
            amount: "AMOUNT",
            merchantId: "YOUR_MERCHANT_ID",
            terminalId: "YOUR_TERMINAL_ID",
            locale: .en,        // Available options: .en, .ar
            transactionType: .cardWallet,  // Available options: .nfc, .cardWallet, .applePay
            transactionId: Config.generateTransactionId(),  // Optional: Auto-generated if nil
            additionValues: Config.generateDefaultAdditionValues(),  // Optional - PLEASE REFER UI Customization section to understand how you can use these values for UI customization
                                                                        // Please refer to Apple Pay Specific Configuration to understand how you can provide apple pay related configurations to SDK   
            merchantReference: "optional-merchant-reference"  // Optional: Merchant reference for transaction tracking
        )
        
        // Initialize and present the payment SDK
        let sdk = AmwalSDK()
        let viewController = try sdk.createViewController(
            config: config,
            onResponse: { response in
                // Handle the payment response
                print("Payment Response: \(response ?? "No response")")
            },
            onCustomerId: { customerId in
                // Handle the customer ID if needed
                print("Customer ID: \(customerId)")
            }
        )
        
        // Present the view controller
        self.present(viewController, animated: true)
    } else {
        print("Failed to fetch session token")
    }
}

3. For SwiftUI applications, use the SDKViewControllerRepresentable:

struct PaymentView: View {
    var body: some View {
        SDKViewControllerRepresentable(
            config: config,
            onResponse: { response in
                // Handle the payment response
                print("Payment Response: \(response ?? "No response")")
            },
            onCustomerId: { customerId in
                // Handle the customer ID if needed
                print("Customer ID: \(customerId)")
            }
        )
    }
}

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

Addition Values Configuration #

The SDK supports additionValues parameters for passing custom key-value pairs that can be used for various SDK functionalities, including UI customization and payment flow control. This is particularly important for Apple Pay configuration.

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 the bottom, covering 90% of the 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 for full page design

Payment Flow #

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

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

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
let transactionId = Config.generateTransactionId()

// Or generate a custom UUID manually
let customUUID = UUID().uuidString.lowercased()

The UUID generator creates lowercase UUIDs ensuring compatibility with the payment system.