Add a card to a digital wallet

Last updated: March 12, 2025

You can enable cardholders to add cards to their Apple or Google wallet with push provisioning in your mobile 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.

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.
Complete your push-provisioning onboarding.
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.

When you request to enable push provisioning, your Account Manager collects your configuration requirements and shares your unique issuer ID.

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.

To generate the public and private keys yourself:

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

Share the public key with Checkout.com through a safe store.

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.

You must implement the push-provisioning prerequisite for your platform:

You must request access to the Android Push Provisioning API.

If you're using an SDK version below 1.1.3, you must test using a physical device or Rosetta simulators. You must have the payment-pass-provisioning entitlement added to Signing & Capabilities in your iOS app.

To request Apple's permission to add this entitlement, contact Apple at [email protected].

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

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.
Provision the card.
Configure provisioning.
Provide a JSON Web Token.

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 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}

Once you've retrieved the card that you want to add to a digital wallet, call the card.provision() method:


1card.provision(
2    activity = {The_activity_to_handle_the_provision_outcome},
3    cardholderId = "{Id_of_cardholder_performing_provisioning_operation}",
4    configuration = ProvisioningConfiguration(/* */),
5    provisioningToken = "{JWT_generated_for_operation}",
6    completionHandler = { result: Result<Unit> -> /* Callback after the operation is complete*/ 
7  }
8)

Then, make a call to handle the push provisioning response in the same activity you used for the card.provision method:


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


1card.provision(cardholderID: "{Id_of_cardholder_performing_provisioning_operation}",
2               configuration: ProvisioningConfiguration(/* */),
3               provisioningToken: "{JWT_generated_for_operation}"),
4               completionHandler: "{Completion_handler_returning_the_outcome_of_the_operation} ((CheckoutCardManager.OperationResult) -> Void)”)

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                          serviceURLString,         // The URL of the D1 Service Server
5                          digitalServiceURLString)  // The URL for the digital card operation


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 each provisioning call and ensure it's supported in your back end. The token format must be unique and differ from all other tokens the SDK consumes.

Note

You must provide a unique provisioning token for each device or app.
For more information, see Thales D1 Developer Portal – SDK Login.

Information

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

The token must have the following properties:

Token property	Location	Description
`alg` string	Header	The encryption algorithm used. This can be one of: `ES256` `RS256`
`kid` string	Header	The token key identifier: `d1api-{Your-Checkout.com-client-name}-01`
`aud` URL	Payload	The token audience: `https://client-api.d1.thalescloud.io/oidc/\{issuerId}`
`scope` string	Payload	The token scope: `thales:d1`
`iss` URL	Payload	The token issuer: `https://bpsd1-demo-a2oidc.d1-dev.thalescloud.io/oidc/\{issuerId}`
`exp` Android – datetime iOS – double	Payload	The date and time when the token expires, in UTC. The value must be less than 15 minutes after the current date and time. Format – ISO 8601
`sub` string	Payload	The unique identifier for the cardholder.
`iat` Android – datetime iOS – double	Payload	The date and time when you want the token issued, in UTC. Set this to the current date and time. Format – ISO 8601
`{jwtPrivateKey}` string	Signature	Your private key for signing the token.

An example token is formatted as follows:


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: "{jwtPrivateKey}"

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.

For iOS, you can also test and mock API calls in the stub environment.

Note

For iOS, 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.

Add a card to a digital wallet

Information

Before you begin

Note

Push-provisioning onboarding

Private and public keys

Device allowlists

Note

Push-provisioning prerequisites

Note

Information

How it works

Authenticate the cardholder

Retrieve the cardholder's cards

Provision the card

Configure provisioning

Information

Provide a JSON Web Token

Note

Information

Information

Testing

Testing environments

Note

iOS provisioning validation

Note

Troubleshooting

Android

iOS

Note

Information

Information