Apple Pay - Push Provisioning

The Nium Push Pay SDK enables an iOS application to offer an Add to Apple Wallet experience. Cardholders can initiate provisioning of an eligible card from the application without manually entering its card details.

The application manages the user experience, while the SDK provides the Nium push-provisioning integration.

Before you integrate

Confirm SDK access, supported iOS and Xcode versions, eligible card programs, Apple Wallet entitlements, and the authentication model with your Nium representative.

The SDK initialization example below includes an apiSecret parameter. Do not embed a confidential server-side API secret in a distributed mobile application. Confirm with Nium whether this parameter accepts a mobile-safe credential or requires a backend-mediated integration before implementation.

Integration overview

1. Install the SDK using CocoaPods.
2. Configure the SDK and required Apple Wallet entitlements.
3. Add the Add to Apple Wallet button.
4. Check whether the card is already provisioned and update button visibility.
5. Initiate card provisioning when the cardholder taps the button.
6. Configure SSL pinning as required by the SDK, before making network requests.

note

The steps below reflect the method names and parameters in the existing integration guide. SDK version compatibility, method signatures, and initialization order must be confirmed against the current Nium SDK package.

Step 1: Install the SDK

Install CocoaPods

CocoaPods manages third-party iOS dependencies. If CocoaPods is not already installed, follow your organization's approved installation procedure. The original guide uses:

sudo gem install cocoapods
pod setup

Create a Podfile

Close Xcode and run the following commands from your project directory:

cd /path/to/your/project
pod init
open -a Xcode Podfile

Update the Podfile

Replace YourProjectName with your application's Xcode target name.

source 'https://github.com/CocoaPods/Specs.git'
source 'https://bitbucket.org/instadevelopers/push-provisioning-pod.git'

target 'YourProjectName' do
  use_frameworks!
  pod 'NiumPayPushProvisioning'
end

note

Confirm that the private CocoaPods repository is accessible to your development team and that the repository URL and package name remain current.

Install the dependencies:

pod install

Open the generated .xcworkspace file when working with the CocoaPods-integrated project.

Step 2: Configure the SDK

Import the SDK in the relevant Swift source file:

import NiumPayPushProvisioning

The documented initialization requires the following values:

Parameter	Purpose
clientHashId	Nium client identifier
customerHashId	Customer identifier
walletHashId	Wallet identifier
apiSecret	SDK authentication value; handling must be confirmed with Nium
env	SDK environment

The existing guide provides this initialization pattern:

// Illustrative only: confirm credential handling and SDK signature.
NiumCardsPushProvisioning.initialize(
    clientHashId: "clientHashId",
    customerHashId: "customerHashId",
    walletHashId: "walletHashId",
    apiSecret: "SDK_AUTH_VALUE_FROM_APPROVED_FLOW",
    env: .production
)

Credential security

Do not hardcode production secrets, place them in source control, or expose them in application logs. Obtain Nium's approved mobile authentication and credential-handling instructions before using this initialization pattern.

Step 3: Add the Apple Wallet button

Create the button within a suitable container view and register its tap action:

let addToAppleWalletButton = AddPassButton().createButton(
    .black,
    superview: buttonContainerView
)

addToAppleWalletButton.addTarget(
    self,
    action: #selector(addToWalletAction),
    for: .touchUpInside
)

Ensure that the button is shown only for eligible cards and devices. Confirm the SDK's eligibility and availability checks with Nium.

Step 4: Check provisioning status

Before showing an Add to Apple Wallet action, check whether the card is already provisioned.

Check a single card

The SDK guide identifies the method getSingleCardProvisionStatus(cardSuffix:completion:), which returns a Boolean result.

// Illustrative: replace the suffix and confirm the current SDK signature.
NiumCardsPushProvisioning.shared?.getSingleCardProvisionStatus(
    cardSuffix: cardSuffix,
    completion: { result in
        switch result {
        case .success(let isProvisioned):
            DispatchQueue.main.async {
                addToAppleWalletButton.isHidden = isProvisioned
            }
        case .failure(let error):
            // Handle the error and decide whether to retry the status check.
            print(error.localizedDescription)
        }
    }
)

Check multiple cards

The existing guide also references getMultiCardProvisionStatus for checking a list of card suffixes.

// Illustrative: confirm the exact array parameter and result model.
NiumCardsPushProvisioning.shared?.getMultiCardProvisionStatus(
    cardSuffix: cardSuffixes,
    completion: { result in
        switch result {
        case .success(let cardDetails):
            for cardDetail in cardDetails {
                // Update the matching card's button using cardDetail.status.
                // Do not use one shared button for multiple card results.
            }
        case .failure(let error):
            print(error.localizedDescription)
        }
    }
)

note

The single-card and multi-card methods check provisioning status. They do not provision a card. Card provisioning is initiated in Step 5.

Step 5: Provision the card

When the cardholder taps the button, call the documented addToWallet(viewController:cardHashId:completion:) method with the card's card hash ID, not the card number.

@objc func addToWalletAction() {
    NiumCardsPushProvisioning.shared?.addToWallet(
        viewController: self,
        cardHashId: cardHashId,
        completion: { result in
            switch result {
            case .success(let message):
                print("Apple Wallet provisioning completed: \(message)")
                // Refresh provisioning status and update the UI.
            case .failure(let error):
                print(error.localizedDescription)
                // Present an appropriate error or retry option.
            }
        }
    )
}

The completion callback indicates whether the SDK reports provisioning success or failure. Refresh the card's provisioning status after completion to ensure the application displays the correct action.

Step 6: Configure SSL pinning

The original SDK instructions describe initializing TrustKit in the application's launch flow:

do {
    try NiumCardsPushProvisioning.initialiseTrustKit(domain: "nium.com")
} catch {
    print(error.localizedDescription)
}

important

Confirm the required domain, supported certificate-pinning configuration, and initialization order with Nium. If SSL pinning is mandatory, configure it before the SDK makes network requests. Do not assume that nium.com is the correct domain for every environment.

Apple Wallet entitlement

Apple Wallet in-app provisioning requires the appropriate entitlement and program configuration. The original guide refers to an entitlement setup link but does not provide the destination.

Action required: Add the approved Apple entitlement and Nium onboarding instructions here once confirmed. Do not consider the integration production-ready until the entitlement and provisioning eligibility have been verified.

Implementation checklist

• Confirm card-program eligibility and supported SDK/iOS versions.
• Obtain access to the Nium SDK repository.
• Confirm the mobile-safe authentication flow; do not ship server-side secrets.
• Complete Apple Wallet entitlement setup.
• Initialize the SDK and required SSL pinning in the correct order.
• Show the Add to Apple Wallet button only when appropriate.
• Handle successful provisioning, errors, and already-provisioned cards.
• Test the integration in Nium's supported non-production environment before launch.

Related guide

See Digital Wallet Tokenization for the wider digital-wallet integration context.