Use digital wallets with Issuing

Stripe provides an SDK wrapper around a private Google library for push provisioning. To distribute your app on the Google Pay Store with push provisioning you need to:

• Request access to Google Pay. After you complete the form, expect approval within a few hours to a day.
• After receiving approval, download Google’s TapAndPay private SDK. The most recently tested version of the TapAndPay SDK is version 18.
• Request access to the push provisioning API for your app. You must provide your application ID to be added to Google’s allowlist. Details on this process are available in Google’s documentation. After the process is complete, Google grants push provisioning entitlements.
• After Google has granted push provisioning entitlements, contact Stripe with your application name, application ID, card network, and card name to complete this step.

• Import Google’s private SDK.
• Import Stripe’s SDK.

dependencies {
  [... your dependencies]
  implementation 'com.stripe:stripe-android-issuing-push-provisioning:1.2.2'
}

For more context, see the code snippets and references to the sample app at each step. For this step, see how the sample app imports these SDKs.

• Prepare your backend to create ephemeral keys for your cards. See section below.
• Create an EphemeralKeyProvider that extends PushProvisioningEphemeralKeyProvider. As the ephemeral key provider will be passed to another activity, it also needs to implement Parcelable (see Parcelable). For more context, see how the sample app defines its EphemeralKeyProvider.
• Implement the Add to Google Pay button according to Google’s specifications. The sample app provides an example of the button adhering to branding guidelines.

To check the status of your users’ cards, use listTokens() to retrieve a list of all of your cards already present on the device. Compare the value of getFpanLastFour() on each returned object to Stripe’s last4) property of the Issued Card object for the card you want to add. Discard all non-matching objects from the response list.

• If the resulting list is empty, it means that the card you intend to add isn’t present on the device yet. You can proceed with displaying the button as described below.
• If the resulting list contains a TokenInfo object, check its TokenState by invoking getTokenState().
  • If the status is TOKEN_STATE_NEEDS_IDENTITY_VERIFICATION, your user has already attempted to manually add the given card to their device. Display the Add to Google Pay button, but help them to recover from this situation by wiring the onActivityResult listener to the tokenize() method as outlined in Google’s documentation.
  • If the status is anything else, the card is already present on the device. Do not display a Google Pay button.

Make sure to provide your application ID to Stripe before starting internal testing. Setup can take more than a week, and the consequences of an incomplete setup include receiving inconsistent responses to these two methods. The result of listTokens() only contains cards added after Stripe completes the setup.

• When a user taps the button, launch Stripe’s PushProvisioningActivity using the PushProvisioningActivityStarter.

new PushProvisioningActivityStarter(
  this, // The Activity or Fragment you are initiating the push provisioning from
  new PushProvisioningActivityStarter.Args(
  "Stripe Card", // The name that will appear on the push provisioning UI
  ephemeralKeyProvider, // Your instance of EphemeralKeyProvider
  false // If you want to enable logs or not
)).startForResult();

For more context, see how the sample app launches PushProvisioningActivity.

This prepares the push provisioning and launches the UI to add the card to the wallet. Implement the callback in your onActivityResult.

protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
  if (requestCode == PushProvisioningActivityStarter.REQUEST_CODE) {
    if (resultCode == PushProvisioningActivity.RESULT_OK) {
      PushProvisioningActivityStarter.Result success = PushProvisioningActivityStarter.Result.fromIntent(data);
    } else if (resultCode == PushProvisioningActivity.RESULT_ERROR) {
      PushProvisioningActivityStarter.Error error = PushProvisioningActivityStarter.Error.fromIntent(data);
    }
  }
}

For more context, see how the sample app implements onActivityResult.

If the provisioning was successful, you’ll receive a PushProvisioningActivityStarter.Result containing a cardTokenId which is Google’s ID for the card in the active wallet. You can use the rest of the wallet functions with this ID.

If the provisioning encountered an error, a PushProvisioningActivityStarter.Error will be returned with a code and a message. The message is a developer-friendly text explaining the error. The code can have the following values:

The push provisioning implementation exposes methods that expect you to communicate with your own backend to create a Stripe Ephemeral Key and return a JSON of it to your app. This key is a short-lived API credential that you can use to retrieve the encrypted card details for a single instance of a card object.

To make sure that the object returned by the Stripe API is compatible with the version of the iOS or Android SDK you’re using, the Stripe SDK lets you know what API version it prefers. You must explicitly pass this API version to our API when creating the key.

curl https://api.stripe.com/v1/ephemeral_keys \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "issuing_card"="{{ISSUING_CARD_ID}}" \
  -H "Stripe-Version: {{API_VERSION}}"

{
    "id": "ephkey_1G4V6eEEs6YsaMZ2P1diLWdj",
    "object": "ephemeral_key",
    "associated_objects": [
        {
            "id": "ic_1GWQp6EESaYspYZ9uSEZOcq9",
            "type": "issuing.card"
        }
    ],
    "created": 1586556828,
    "expires": 1586560428,
    "livemode": false,
    "secret": "ek_test_YWNjdF8xRmdlTjZFRHelWWxwWVo5LEtLWFk0amJ2N0JOa0htU1JzEZkd2RpYkpJdnM_00z2ftxCGG"
}

For more context, see how the sample backend creates a Stripe Ephemeral Key.

All testing must be done in live mode, with live Issuing cards, and on physical devices.