Add a card to a digital wallet

Last updated: April 7, 2025

You can enable cardholders to add cards to their Apple or Google wallet with push provisioning in your mobile app or the Apple Wallet app, using the Card Management Android or iOS SDK.

Push provisioning means the cardholder does not have to enter the card details manually. It involves multiple parties including you, Checkout.com, the card scheme, and the wallet provider.

Information

To enable and onboard for push provisioning, contact your Account Manager. Your Account Manager collects your configuration requirements and shares your unique issuer ID.

You must:

Complete your Issuing onboarding.
Integrate the Card Management Android SDK or iOS SDK.
- Ensure you import the Android additional libraries or iOS dependencies and libraries.
- Ensure you're using the SDK's CheckoutCardManagement library.
Create or receive your private/public key pair.
Add your testing device to the device allowlist.
Implement the push-provisioning prerequisites.

Note

If you attempt push provisioning without completing your Issuing or push-provisioning onboarding, your app intentionally crashes.

Push provisioning requires a private/public key pair, which can be generated by either Checkout.com or you.

Private key – You use this to sign the JSON Web Token (JWT).
Public key – The server uses this to verify the OpenID access token provided by the issuer's identity provider (IdP). This ensures that the JWT was signed with the private key that corresponds to the public key.
Example – ABCDOEFGHIJKLMNOPqRsTu+VWx1Yzabc+DEfGhIj2kl/mN3opQr4STUV5wx6Y78z

If Checkout.com generates the key pair, we securely share the private key with you. If you generate the key pair, share it with Checkout.com through a safe store.

To generate the key pair, run the following command, providing your issuer ID from your push-provisioning onboarding:


1$ openssl ecparam -name prime256v1 -genkey -noout -out is_cko_{Issuer_id}-jwt-priv-key.pem
2
3$ openssl ec -in is_cko_cko-jwt-priv-key.pem -pubout > is_cko_{Issuer_id}-jwt-pub-key.pem

Checkout.com recommends testing push provisioning on a physical device. You must add your testing device to the allowlist for your platform:

Retrieve your SHA-256 fingerprint:
- Open Android Studio and go to the Gradle tab.
- Select the Execute Gradle Task icon.
- In the modal that appears, enter gradle signinReport, and then press Enter.
- Copy the SHA-256 value from the report output.
Complete the Push Provisioning API Access Request form as follows:
- Company name – Enter Checkout.com.
- Google Wallet use case – Select Payments card.
- Option which best describes your company – Select Card Issuer.
- App package name – Enter [your.app.package]. For example, com.checkout.levant.
- App package environment – Select Production.
- Fingerprints – Enter your SHA-256 fingerprint.
- Target launch date – Enter a date in the future, in MM/DD/YYYY format.
- Network – Select Mastercard as the card scheme.

Implement the required push-provisioning prerequisites for your platform:

You must request access to the Android Push Provisioning API.

To enable push provisioning when the cardholder starts their journey in your app or in the Apple Wallet app, you must implement two Apple extensions at the same time as your app: the Intents Extension and the Intents UI Extension.

Information

This is a certification requirement from Apple.

Information

For more information on Apple app extensions, see Apple Developer – Understand How an App Extension Works.

Follow these steps:

To enable Apple Wallet to recognize the extensions and the eligible cards, you must add an app bundle ID to the Intents Extension and Intents UI Extension in the associatedApplicationIdentifier of your Payment Network Operator (PNO). For example, com.checkout.Levant.

Alternatively, you can do this using a wildcard bundle ID.

To enable your app to share storage with the extensions, you must create an app group ID and add it to your app and both extensions. For example, if your app bundle ID is com.checkout.Levant, use the following for your app group ID: group.com.checkout.LevantApplication.

To create the app group ID, see Apple Developer – Configuring app groups.
Add the ID to your app in your xCode project, under Signing & Capabilities > Capability.

You must add the payment-pass-provisioning entitlement to your app and both extensions.

Request Apple's permission to add this entitlement at [email protected].
Add the capability to your app in your xCode project, under Signing & Capabilities > Capability.

Note

If your iOS app does not have the payment-pass-provisioning entitlement and you trigger a tokenization flow in the SDK, you may receive a missing entitlement: com.apple.developer.payment-pass-provisioning error from Apple and an SDK operation error.

Information

For more information, see:

Apple Developer – Adding Capabilities to Your App
Apple Developer – Entitlement Key Reference
Thales D1 Developer Portal – iOS Push Provisioning Access

When the cardholder starts their journey in the Apple Wallet app, the back-end Intents Extension lets Apple Wallet check with your app if the cardholder has any cards that can be digitized.

If there are eligible cards, Apple Wallet displays your app's logo to the cardholder in a list of issuer apps. The cardholder selects your app and authenticates. Apple Wallet retrieves and displays the list of eligible cards to the cardholder, which they can then add to their wallet.

To add the extension:

In your xCode project, go to File > New > Target.
Select Intents Extension.
Add your app group ID.
In the WalletExtension.entitlements file, add the in-app provisioning capability as follows:


1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
3<plist version="1.0">
4<dict>
5    <key>com.apple.developer.payment-pass-provisioning</key>
6    <true/>
7    <key>com.apple.security.application-groups</key>
8    <array>
9        <string>group.com.yourOrgName.YourAppName</string>
10    </array>
11</dict>
12</plist>

In the Info.plist file, add the Extension-IntentHandler as follows:


1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
3<plist version="1.0">
4<dict>
5    <key>NSExtension</key>
6    <dict>
7        <key>NSExtensionPointIdentifier</key>
8        <string>com.apple.PassKit.issuer-provisioning</string>
9        <key>NSExtensionPrincipalClass</key>
10        <string>$(PRODUCT_MODULE_NAME).Extension-IntentHandler</string> 
11    </dict>
12</dict>
13</plist>

The Extension-IntentHandler is the name of the IntentHandler class in the Intents Extension.

Information

Extension-IntentHandler does not provide the card details. To retrieve card details, call the cardManager.configurePushProvisioning() method.

It must conform with the Checkout.com `IssuerProvisioningExtensionHandler` class as follows:


1@available(iOS 14.0, *)
2class IntentHandler: IssuerProvisioningExtensionHandler {
3    final public override func onError(_ error: CardManagementError.ProvisioningExtensionFailure) {
4    // Optional method to handle potential errors when the card is added to Apple Wallet
5    }
6}

This is an optional method to handle potential errors when the card is added to Apple Wallet if:

The app group ID in the cardManager.configurePushProvisioning() method is incorrect.
There are server errors.

Note

Always specify a minimum deployment for the Intents Extension. If you do not, Apple defaults to the latest iOS version and push provisioning fails for users with older versions.

Import the CheckoutCardManagement dependency into the extension target under General > Frameworks and Libraries.

The front-end Intents UI Extension provides the screen in the Apple Wallet app to authenticate the cardholder in your app.

To add the extension:

In your xCode project, go to File > New > Target.
Select Intents UI Extension.
Add your app group ID.
In the WalletExtension.entitlements file, add the in-app provisioning capability as follows:


1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
3<plist version="1.0">
4<dict>
5    <key>com.apple.developer.payment-pass-provisioning</key>
6    <true/>
7    <key>com.apple.security.application-groups</key>
8    <array>
9        <string>group.com.checkout.LevantApplication</string>
10    </array>
11</dict>
12</plist>

In the Info.plist file, add the Extension-IntentViewController as follows:


1<?xml version="1.0" encoding="UTF-8"?>
2<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
3<plist version="1.0">
4<dict>
5    <key>NSExtension</key>
6    <dict>
7        <key>NSExtensionPointIdentifier</key>
8        <string>com.apple.PassKit.issuer-provisioning.authorization</string>
9        <key>NSExtensionPrincipalClass</key>
10        <string>$(PRODUCT_MODULE_NAME).Extension-IntentViewController</string>
11    </dict>
12</dict>
13</plist>

The Extension-IntentViewController is the name of the IntentViewController class in the Intents UI Extension. It must conform with the Checkout.com IssuerProvisioningExtensionAuthorizationProviding protocol as follows:


1@available(iOS 14.0, *)
2class IntentViewController: UIViewController, IssuerProvisioningExtensionAuthorizationProviding {
3    var completionHandler: ((PKIssuerProvisioningExtensionAuthorizationResult) -> Void)?
4
5    private let authButton = UIButton(type: .system)
6
7    override func viewDidLoad() {
8        super.viewDidLoad()
9        // UI configurations
10
11        authButton.addTarget(self, action: #selector(buttonTapped(_:)), for: .touchUpInside)
12    }
13
14    @IBAction func buttonTapped(_ sender: UIButton) {
15        // Method to retrieve the cardholder ID from your app
16        let cardholderID = fetchCardHolderId()
17
18        // Fetched for the cardholder ID after authentication succeeds
19        let issuerToken = fetchIssuerToken()
20
21        // Method to tell the Apple Wallet app to continue the flow
22        login(issuerToken) { [weak self] (error: CardManagementError.ProvisioningExtensionFailure?) in
23            if error != nil {
24                self?.completionHandler?(.canceled)
25            } else {
26                self?.completionHandler?(.authorized)
27            }
28        }
29    }
30}

Note

Always specify a minimum deployment for the Intents UI Extension. If you do not, Apple defaults to the latest iOS version and push provisioning fails for users with older versions.

Import the CheckoutCardManagement dependency into the extension target under General > Frameworks and Libraries.

Information

For more information on how to share data between your app and the Intents UI Extension, see Apple Developer App Extension Programming Guide – Handling Common Scenarios.

Once you have completed the setup, the flow for the cardholder to add their card to their wallet is as follows:

Authenticate the cardholder.
Retrieve the cardholder's cards.
Configure push provisioning.
Provide a JSON Web Token.
If you're provisioning from within your app, verify the cards' digitization status.
Provision the card.

You are responsible for performing Strong Customer Authentication (SCA) on the cardholder for each session where they use functionality provided by the SDK. This applies to both the sandbox and production SDK environments.

Pass an access token that your app receives from your authentication back end.


1val token = "{Access_token}"
2cardManager.logInSession(token)


1let token = "{Access_token}"
2cardManager.logInSession(token: accessToken)

Once you’ve authenticated the cardholder and your app, call the cardManager.getCards() method to retrieve a list of their cards:


1cardManager.getCards { result: Result<List<Card>> ->
2  result.onSuccess {
3    // You receive a list of the cardholder's cards that you can display in your UI
4    // Returned card details include the last four digits of the PAN, expiry date, cardholder name, card status, and card ID
5  }.onFailure {
6    // If something goes wrong, you receive an error with more information
7  }
8}


1cardManager.getCards { result in
2  switch result {
3  case .success(let cards):
4    // You receive a list of the cardholder's cards that you can display in your UI
5    // Returned card details include last four digits of the PAN, expiry date, cardholder name, card status, and card ID
6  case .failure(let error):
7    // If something goes wrong, you receive an error with more information
8  }
9}

Call the checkoutCardManager.configurePushProvisioning() method:


1checkoutCardManager.configurePushProvisioning(
2    activity = {Activity_to_handle_the_provisioning_outcome},
3    cardholderId = "{Dd_of_cardholder_performing_operation}",
4    configuration = ProvisioningConfiguration(/* */),
5    completionHandler = { result: Result<Unit> -> /* Callback after the operation is complete*/ })

Provide a ProvisioningConfiguration object to the SDK as follows:


1ProvisioningConfiguration(issuerID,                 // Your unique issuer identifier from Checkout.com
2                          serviceRSAExponent,       // As a bytearray object 
3                          serviceRSAModulus,        // As a bytearray object
4                          serviceURL,               // The URL of the D1 Service Server
5                          digitalCardURL)           // The URL for the digital card operation

issuerID – Provide your issuer ID from your push-provisioning onboarding.
serviceRSAExponent and serviceRSAModulus – To retrieve these values from the Public Key Privacy Enhanced Mail (PEM) file, run the following command:


1openssl rsa -pubin -inform PEM -text -noout < pubkey.pem

serviceURLString – Provide the following URL: https://client-api.d1.thalescloud.io/.
digitalServiceURLString – Provide the following URL: https://hapi.dbp.thalescloud.io/mg/tpc.

Information

For more information on the ProvisioningConfiguration object fields, see Thales D1 Developer Portal – Initial Setup.

Call the cardManager.configurePushProvisioning() method:


1cardManager.configurePushProvisioning(cardholderID: "{Id_of_cardholder_performing_operation}",
2                                      appGroupId: "{Your_Apple_App_Group_Id}",
3                                      configuration: ProvisioningConfiguration(/* */),
4                                      walletCards: "List of cards and UI images for the Apple Wallet app to use [(Card, UIImage)]",
5                                      completionHandler: "Completion handler that returns the configuration operation result ((CheckoutCardManager.OperationResult) -> Void)")

The card images must meet the same functional requirements as for Apple Pay and Direct Near-Field Communication Access. For example:

1536 x 969 resolution
Less than 4 MB
Square corners
No chip contacts

For more information, contact your Apple project contact, PNO, or service provider relationship manager.

Provide a ProvisioningConfiguration object to the SDK as follows:


1ProvisioningConfiguration(issuerID,                 // Your unique issuer identifier from Checkout.com
2                          serviceRSAExponent,       // As a data object
3                          serviceRSAModulus,        // As a data object
4                          serviceURLString,         // The URL of the D1 Service Server
5                          digitalServiceURLString)  // The URL for the digital card operation

issuerID – Provide your issuer ID from your push-provisioning onboarding.
serviceRSAExponent and serviceRSAModulus – To retrieve these values from the Public Key Privacy Enhanced Mail (PEM) file, run the following command:


1openssl rsa -pubin -inform PEM -text -noout < pubkey.pem

serviceURLString – Provide the following URL: https://client-api.d1.thalescloud.io/.
digitalServiceURLString – Provide the following URL: https://hapi.dbp.thalescloud.io/mg/tpc.

Information

For more information on the ProvisioningConfiguration object fields, see Thales D1 Developer Portal – Initial Setup.

Provide a unique JSON Web Token (JWT) for every provisioning call for each device or app. Ensure the token is supported in your back end. The token format must be unique and differ from all other tokens the SDK consumes.

Information

For more information, see Thales D1 Developer Portal – SDK Login.
For full guidance on generating JWTs, see Thales D1 Developer Portal – Backend Authorization.
Do not use any mobile end examples from this guidance in the production environment.

To generate the token, provide the following properties and sign it using your private key:

Token property	Description	Generated token
`scope` string	The token scope: `thales:d1`	`scope` string
`subject` string	The unique identifier for the cardholder.	`sub` string
`issuedAt`	The date and time when you want the token issued, in UTC. Set to the current date and time. Format – ISO 8601	`iat` Android – datetime iOS – double
`issuer` URL	The token issuer, including your Checkout.com issuer ID from onboarding: `https://bpsd1-demo-a2oidc.d1-dev.thalescloud.io/oidc/\{issuerId}`	`iss` URL
`audience` URL	The token audience, including your Checkout.com issuer ID: `https://client-api.d1.thalescloud.io/oidc/\{issuerId}`	`aud` URL
`expirationTime`	The date and time when the token expires, in UTC. Set to a value less than 15 minutes after the current date and time. Format – ISO 8601	`exp` Android – datetime iOS – double
`jwtKeyID` string	The token key identifier: `d1api-{Your-Checkout.com-client-name}-01`	`kid` string

alg is the encryption algorithm used. This can be one of: ES256 or RS256.


1Header:
2{
3  "alg" : "ES256", 
4  "kid" : "d1api-{Your_Checkout.com_client_name}-01"
5}
6
7Payload:
8{
9  "aud" : "https://client-api.d1.thalescloud.io/oidc/\{issuerId}",
10  "scope" : "thales:d1",
11  "iss" : "https://bpsd1-demo-a2oidc.d1-dev.thalescloud.io/oidc/\{issuerId}",
12  "exp" : "2025-01-31T10:20:30.456",
13  "sub" : "crh_d3ozhf43pcq2xbldn2g45qnb44",
14  "iat" : "2025-01-31T10:20:30.456"
15}
16
17Signature
18{Signature generated using your private key and hash function}

If you're provisioning from within your app, call the card.getDigitizationState() method to verify the digitization status of the cardholder's cards.

Note

If the cardholder has multiple cards, call this method for each card synchronously. If you attempt asynchronous calls, each new execution overrides the previous one.


1card.getDigitizationState(token: "{JWT_generated_for_operation}",
2              completionHandler: "Completion handler that returns the digitization result ((CheckoutCardManager.CardDigitizationResult) -> Void)")

Cards can have the following digitization statuses:

Digitization status	Description
`DIGITIZED`	The card is digitized on all associated devices.
`NOT_DIGITIZED`	The card is digitized on some but not all associated devices, or is not digitized on any associated devices. Note If you continue to receive this status after the card is added to the wallet, check that your app is correctly configured on the Token Service Provider (TSP) portal.
`PENDING_IDV`	Prompt the cardholder to activate the card to enable digitization on their device.
`DIGITIZATION_IN_PROGRESS`	The card is being digitized.


1card.getDigitizationState(provisioningToken: "{JWT_generated_for_operation}",
2                          completionHandler: "Completion handler that returns the digitization result ((CheckoutCardManager.CardDigitizationResult) -> Void)")

Cards can have the following digitization statuses:

Digitization status	Description
`digitized`	The card is digitized on all associated devices.
`notDigitized`	The card is digitized on some but not all associated devices, or is not digitized on any associated devices. Display in your app an Add to Apple Wallet button. For instructions, see Apple Developer – PKAddPassButton. Note If you continue to receive this status after the card is added to the wallet, check that your app is correctly configured on the Token Service Provider (TSP) portal.
`pendingIDVLocal`	The cardholder must verify their identity to digitize the card on an Apple mobile device. For example, phone verification.
`pendingIDVRemote`	The cardholder must verify their identity to digitize the card on an Apple Watch. For example, phone verification.

Call the card.provision() method:


1card.provision(
2    activity = {Activity_to_handle_the_provisioning_outcome},
3    token = "{JWT_generated_for_operation}",
4    completionHandler = { result: Result<Unit> -> /* Callback after the operation is complete*/ 
5  }
6)

Handle the push-provisioning response in the same activity you used for the card.provision method:


1// Required to handle the card result
2override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
3    super.onActivityResult(requestCode, resultCode, data)
4    card.handleCardResult(requestCode, resultCode, data)
5}

Call the card.provision() method:


1card.provision(provisioningToken: "{JWT_generated_for_operation}"),
2               completionHandler: "Completion handler that returns the provisioning operation result ((CheckoutCardManager.OperationResult) -> Void)")

Information

If you have integration questions or issues, contact your issuing representative or [email protected].

You can only test push provisioning in the SDK's production environment.

However, you can also test and mock method calls in the stub environment.

Note

If you use the SDK's CheckoutCardManagementStub library instead of CheckoutCardManagement, the push provisioning operation behaves as expected, but no interaction takes place between Checkout.com, Apple Wallet, or the card scheme.

The result depends on which Checkout.com environment you use with the stub environment:

Sandbox environment – You receive a pushProvisioningFailure error, because push provisioning is only available in production.
Production environment – You receive an OperationResult success message.

To validate push provisioning, you must test on a physical device using one of the following methods:

Ad-hoc provisioning profiles
TestFlight distribution – Ensure you've added the testing device to the allowlist.

Checkout.com has verified that TestFlight distribution results in correct tokenization flows, including usable push-provisioned cards in Apple Pay. We recommend this for validating end-to-end tokenization flows.

Note

You can only validate using XCode if the build is distributed via TestFlight. This applies to debug builds, direct releases, and archived release builds installed directly on the physical device. The tokenization flow fails and you receive a Could Not Add Card error from Apple.

If you receive the following ERROR_CORE authorization failure, ensure your testing device date is in the future:


1ERROR_CORE [20001] (3) (401) {"error_reference":"TCsTqQepR8w4GRVnTVS7jlC1cTrk772v","securityEvent":true}

You may receive an API_UNAVAILABLE error code or message from Google Pay. For example:


1AppsFilter: interaction: PackageSetting{ba9eff6 com.google.android.gms.tapandpay.issuer.devapp.littlebear/10337} -> PackageSetting{6e03871 com.checkout.levant/10405} BLOCKED
2
3API: TapAndPay.TAP_AND_PAY_API is not available on this device. Connection failed with: ConnectionResult{statusCode=API_UNAVAILABLE, resolution=null, message=null}

This could be for the following reasons:

During testing, you did not add your device to the Google allowlist.
In production, your cardholder does not have Google Wallet installed. Prompt them to install the app via the Play Store.

If tokenization flows fail outside the SDK once they reach Apple Pay, you can debug the Apple Pay app directly for better visibility of the failure reason.

Install custom logging profiles on the physical testing device, and then trigger sysdiagnose. You can retrieve the logs from the iOS device filesystem.

You receive a generic Apple error, for example:


1Response: [...]
2{
3   [...]
4}
5{
6   statusCode = 500;
7   statusMessage = "Broker Service Response exception”;
8}

Note

If you get this error when using a TestFlight distributed build, the SEID or Adam ID may not be correctly added to the Apple device allowlist.

Information

For full guidance, see Apple Developer – Profiles and Logs.

You may receive an ERROR_DEVICE_ENVIRONMENT_UNSAFE message for the following reasons:

You've attached a debugger to the release version of the binary application.
You're attempting push-provisioning flows on a device the SDK considers unsafe. For example, a rooted device.

Information

For information on countermeasures that can trigger this error, see Thales D1 Developer Portal – Security Countermeasures.

If the Apple Wallet App does not display your app logo in the list of issuer apps, this may be because:

Your app was not installed and opened, or the cardholder did not go through the push-provisioning configuration.
You provided an incorrect app group ID in the cardManager.configurePushProvisioning() method.
You did not add your app group ID to the Intents Extension and/or Intents UI Extension.
You did not add the bundle IDs for the Intents Extension and/or Intents UI Extension to the PNO's associatedApplicationIdentifier.
The cardholder has already added this card to their wallet.
The device user disabled the authentication method used by the extension.

Information

Before you begin

Note

Private/public key pair

Device allowlists

Push-provisioning prerequisites

How it works

Authenticate the cardholder

Retrieve the cardholder's cards

Configure push provisioning

Information

Provide a JSON Web Token

Information

Generated token example

Verify digitization status

Note

Note

Provision the card

Information

Testing

Troubleshooting

Authorization failure

Google Pay unavailable