Apple Pay Specific Configuration

Apple Pay Specific Configuration #

When implementing Apple Pay, the merchantIdentifier in additionValues must match your Apple Pay merchant ID configured in your Apple Developer account and Xcode project.

Important: The merchantIdentifier value in additionValues should match:

1. Your Apple Pay merchant ID from Apple Developer Portal
2. The merchant ID configured in Xcode under “Signing & Capabilities” → “Apple Pay”
3. The merchant ID registered with AmwalPay

Usage Examples #

Example 1: Using Default Addition Values (for AmwalPay’s default Apple Pay merchant) #

let config = Config(
    environment: .UAT,
    sessionToken: token,
    currency: .OMR,
    amount: "100",
    merchantId: "your_merchant_id",
    terminalId: "your_terminal_id",
    locale: .en,
    transactionType: .applePay,
    transactionId: Config.generateTransactionId(),
    additionValues: Config.generateDefaultAdditionValues()
    // This generates: ["merchantIdentifier": "merchant.applepay.amwalpay"]
)

Example 2: Using Custom Apple Pay Merchant Identifier with UI Customization #

// For your own Apple Pay merchant ID with bottom sheet design and colors
let customAdditionValues = [
    "merchantIdentifier": "merchant.com.yourcompany.applepay",
    "useBottomSheetDesign": "true",
    "primaryColor": "#FF5733",
    "secondaryColor": "#33FF57",
    "ignoreReceipt": "false"
]

let config = Config(
    environment: .UAT,
    sessionToken: token,
    currency: .OMR,
    amount: "100",
    merchantId: "your_merchant_id",
    terminalId: "your_terminal_id",
    locale: .en,
    transactionType: .applePay,
    transactionId: Config.generateTransactionId(),
    additionValues: customAdditionValues
)

Example 3: Minimal Configuration with Bottom Sheet Design #

// Using just bottom sheet design with default colors
let minimalCustomValues = [
    "useBottomSheetDesign": "true"
]

let config = Config(
    environment: .UAT,
    sessionToken: token,
    currency: .OMR,
    amount: "100",
    merchantId: "your_merchant_id",
    terminalId: "your_terminal_id",
    locale: .en,
    transactionType: .cardWallet,
    transactionId: Config.generateTransactionId(),
    additionValues: minimalCustomValues
)

Example 4: Adding Additional Custom Values #

// You can add more custom key-value pairs alongside merchantIdentifier
let extendedAdditionValues = [
    "merchantIdentifier": "merchant.com.yourcompany.applepay",
    "useBottomSheetDesign": "true",
    "primaryColor": "#7F22FF",
    "ignoreReceipt": "true"
]

let config = Config(
    environment: .UAT,
    sessionToken: token,
    currency: .OMR,
    amount: "100",
    merchantId: "your_merchant_id",
    terminalId: "your_terminal_id",
    locale: .en,
    transactionType: .applePay,
    transactionId: Config.generateTransactionId(),
    additionValues: extendedAdditionValues
)

Note: All boolean values should be passed as strings ("true" or "false"). Custom additionValues will be merged with defaults, with custom values taking precedence.
terminalId: “your_terminal_id”,
locale: .en,
transactionType: .nfc, // or .cardWallet
transactionId: Config.generateTransactionId(),
additionValues: nil // Optional for non-Apple Pay transactions

#### Available Methods
swift
// Generate default addition values (includes default Apple Pay merchant identifier)
let defaultValues = Config.generateDefaultAdditionValues()
// Returns: ["merchantIdentifier": "merchant.applepay.amwalpay"]

// Generate a transaction ID
let transactionId = Config.generateTransactionId()
// Returns: A lowercase UUID string (e.g., "a1b2c3d4-e5f6-7890-abcd-ef1234567890")

Key Points for Apple Pay Integration #

1. Merchant Identifier Consistency: Ensure the merchantIdentifier in additionValues matches your Apple Pay configuration
2. Required for Apple Pay: The merchantIdentifier key is mandatory when using transactionType: .applePay
3. Optional for Other Payment Types: For NFC and Card Wallet transactions, additionValues can be nil or contain custom tracking data
4. Case Sensitive: The key name merchantIdentifier is case-sensitive
5. Format: Apple Pay merchant identifiers typically follow the format: merchant.com.yourcompany.identifier

Configuration Options #

Currency #

• OMR (Omani Rial)

Language #

• en (English)
• ar (Arabic)

Environment #

• UAT (Testing environment)
• PROD (Production environment)

Transaction Types #

• NFC (Near Field Communication)
• CARD_WALLET (Card Wallet payments)
• APPLE_PAY (Apple Pay integration)

Apple Pay Requirements #

When using Apple Pay transactions, you must:

1. Enable Apple Pay capability in your Xcode project:

• Open your project in Xcode
• Select your target
• Go to “Signing & Capabilities”
• Click “+” and add “Apple Pay”
• Configure your merchant ID in the capability settings

1. Share your Apple Pay merchant ID with AmwalPay:

• Contact our support team
• Provide your Apple Pay merchant ID
• We will configure our systems to accept payments from your merchant ID

Security #

The SDK implements secure hash generation for transaction validation. Make sure to:

1. Keep your secret key secure
2. Generate the secure hash on your server
3. Never expose sensitive credentials in your client-side code