Apple Pay - Flutter SDK

This guide explains how to integrate Nium's Apple Pay Push Provisioning SDK into a Flutter application using a Flutter method channel to call the native iOS SDK.

Before you begin

Confirm with Nium that your card program is enabled for Apple Pay push provisioning, your app has the required Apple entitlement, and your team has access to the SDK repository. Test on a compatible physical iOS device.

Credential security: The original integration example initializes the native SDK with an apiSecret. Do not embed a confidential server-side API secret in a distributed mobile application. Confirm the approved mobile authentication and SDK initialization approach with Nium before production use.

Step 1: Create a Flutter project

If you do not already have a Flutter application, run:

flutter create apple_push_provisioning_demo
cd apple_push_provisioning_demo

Open the project in your preferred IDE, such as VS Code or Android Studio.

Step 2: Configure iOS dependencies

Open your Flutter project's existing ios/Podfile. Flutter normally generates this file; do not replace its Flutter-specific configuration.

Ensure the required repositories are configured and add the Nium SDK dependency to the existing Runner target, following the repository access instructions provided by Nium.

# Add repository sources at the top of the existing Podfile, if required.
source 'https://github.com/CocoaPods/Specs.git'
source 'https://bitbucket.org/instadevelopers/push-provisioning-pod.git'

# Within the existing target 'Runner' do block:
# use_frameworks!  # Enable only if required by the SDK and compatible with your project.
# pod 'NiumPayPushProvisioning'
# pod 'TrustKit'       # Only if explicitly required by your approved SDK setup.

The lines under target 'Runner' above are illustrative additions, not a complete replacement Podfile. Keep the existing flutter_install_all_ios_pods and other Flutter-generated configuration intact.

Install the dependencies:

cd ios
pod install
cd ..

Repository access

If CocoaPods cannot access the private SDK repository, request the approved access method from Nium. Do not place Bitbucket usernames, app passwords, or tokens in a committed Podfile.

Step 3: Add a Flutter method channel

In lib/main.dart, use a method channel to request provisioning from native iOS code. Replace YOUR_CARD_HASH_ID with the actual card identifier from your application.

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(home: HomePage());
  }
}

class HomePage extends StatefulWidget {
  const HomePage({super.key});

  @override
  State<HomePage> createState() => _HomePageState();
}

class _HomePageState extends State<HomePage> {
  static const MethodChannel _channel = MethodChannel('push_provisioning');
  bool _isProvisioning = false;

  Future<void> provisionCard(String cardHashId) async {
    if (_isProvisioning) return;
    setState(() => _isProvisioning = true);
    try {
      final message = await _channel.invokeMethod<String>(
        'provisionCard',
        {'cardHashId': cardHashId},
      );
      debugPrint('Provisioning result: $message');
    } on PlatformException catch (error) {
      debugPrint('Provisioning failed: ${error.code}: ${error.message}');
    } finally {
      if (mounted) setState(() => _isProvisioning = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Apple Pay provisioning')),
      body: Center(
        child: ElevatedButton(
          onPressed: _isProvisioning
              ? null
              : () => provisionCard('YOUR_CARD_HASH_ID'),
          child: Text(_isProvisioning ? 'Adding card…' : 'Add to Apple Wallet'),
        ),
      ),
    );
  }
}

Step 4: Connect the method channel to the native iOS SDK

In ios/Runner/AppDelegate.swift, register a handler for the same channel name. The following example focuses on the Flutter-to-native callback and assumes that the Nium SDK has already been initialized using Nium's approved configuration.

import UIKit
import Flutter
import NiumPayPushProvisioning

@main
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)

    // Initialize the Nium SDK here using the approved configuration.
    // Do not hardcode confidential server-side credentials in the app.

    guard let controller = window?.rootViewController as? FlutterViewController else {
      return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }

    let channel = FlutterMethodChannel(
      name: "push_provisioning",
      binaryMessenger: controller.binaryMessenger
    )

    channel.setMethodCallHandler { call, result in
      guard call.method == "provisionCard" else {
        result(FlutterMethodNotImplemented)
        return
      }
      guard let arguments = call.arguments as? [String: Any],
            let cardHashId = arguments["cardHashId"] as? String,
            !cardHashId.isEmpty else {
        result(FlutterError(
          code: "INVALID_ARGUMENT",
          message: "cardHashId is required",
          details: nil
        ))
        return
      }
      guard let sdk = NiumCardsPushProvisioning.shared else {
        result(FlutterError(
          code: "SDK_NOT_INITIALIZED",
          message: "Nium push provisioning SDK is unavailable",
          details: nil
        ))
        return
      }

      sdk.addToWallet(viewController: controller, cardHashId: cardHashId) { sdkResult in
        DispatchQueue.main.async {
          switch sdkResult {
          case .success(let message):
            result(message)
          case .failure(let error):
            result(FlutterError(
              code: "PROVISIONING_FAILED",
              message: error.localizedDescription,
              details: nil
            ))
          }
        }
      }
    }

    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

SDK compatibility check

The NiumCardsPushProvisioning.shared and addToWallet(...) calls are based on the existing Nium documentation supplied for this guide. Confirm their signatures, initialization requirements, and supported Swift lifecycle annotations against the actual SDK version distributed to your team before copying the example into production.

Step 5: Configure transport security

The original integration uses TrustKit and an example pin for nium.com. Do not copy placeholder public-key hashes or reporting URLs into a production application: incorrect pinning can prevent all network calls from succeeding.

Follow the TLS and certificate/public-key pinning configuration supplied by Nium for the SDK version and environment you use. Confirm whether the SDK's own initialiseTrustKit(domain:) method or application-managed TrustKit configuration is required; avoid initializing both without explicit guidance.

Step 6: Build and test

Run the application on a supported physical iOS device:

flutter run

Verify the following:

1. The app has the required Apple Pay push provisioning entitlement and Nium program configuration.
2. The SDK initializes successfully without distributing confidential credentials.
3. The Add to Apple Wallet action opens the expected native provisioning flow.
4. Flutter receives either a successful result or a structured error from the native handler.
5. The application handles repeat taps, cancelled provisioning, and cards that are already provisioned.

For checking whether a card has already been provisioned, see Apple Pay – Push Provisioning. Confirm the exact status-check API exposed by your SDK version.

Troubleshooting

Problem	What to check
CocoaPods cannot fetch the SDK	Confirm private repository access with Nium; do not commit repository credentials.
Native SDK module cannot be imported	Verify the SDK pod is installed in the existing Flutter Runner target and rebuild the iOS project.
Flutter call never completes	Ensure the native method handler invokes result(...) on both success and failure.
SDK is unavailable	Verify initialization completes before the user can request provisioning.
Provisioning is not offered	Confirm card eligibility, device support, Apple entitlement, and program configuration.
TLS or certificate errors	Confirm approved TrustKit/pinning configuration; do not use placeholder hashes.

If issues persist, contact your Nium account manager or Nium Support.

Related guides

• Apple Pay – Push Provisioning
• Card Security