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.pem23$ 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.
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)
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>> ->2result.onSuccess {3// You receive a list of the cardholder's cards that you can display in your UI4// Returned card details include the last four digits of the PAN, expiry date, cardholder name, card status, and card ID5}.onFailure {6// If something goes wrong, you receive an error with more information7}8}
Once you've retrieved the card that you want to add to a digital wallet, call the card.provision()
method:
1card.provision(2activity = {The_activity_to_handle_the_provision_outcome},3cardholderId = "{Id_of_cardholder_performing_provisioning_operation}",4configuration = ProvisioningConfiguration(/* */),5provisioningToken = "{JWT_generated_for_operation}",6completionHandler = { 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 guide2override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {3super.onActivityResult(requestCode, resultCode, data)4card.handleCardResult(requestCode, resultCode, data)5}
Provide a ProvisioningConfiguration
object to the SDK as follows:
1ProvisioningConfiguration(issuerID, // Your unique issuer identifier from Checkout.com2serviceRSAExponent, // As a bytearray object3serviceRSAModulus, // As a bytearray object4serviceURLString, // The URL of the D1 Service Server5digitalServiceURLString) // The URL for the digital card operation
issuerID
– Provide your issuer ID from your push-provisioning onboarding.serviceRSAExponent
andserviceRSAModulus
– 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 |
---|---|---|
string | Header | The encryption algorithm used. This can be one of:
|
string | Header | The token key identifier: |
URL | Payload | The token audience: |
string | Payload | The token scope: |
URL | Payload | The token issuer: |
| Payload | The date and time when the token expires, in UTC. |
string | Payload | The unique identifier for the cardholder. |
| Payload | The date and time when you want the token issued, in UTC. |
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}67Payload: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}1617Signature: "{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}
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{6statusCode = 500;7statusMessage = "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.