Deploy your app with the API

Learn how to deploy your Android app to your devices through a webhook.

After Stripe reviews and approves your app for deployment, we notify you by email through a webhook. You can then follow the instructions below to deploy your app.

During deployment, your app is immediately sent and downloaded to your device. The device reboots to install the app. Devices reboot every 24 hours and apply any updates automatically. To check for and apply updates immediately, you can manually reboot your device.

You can deploy new and updated apps for Terminal devices in the Dashboard.

Add or edit a deploy group

Before you can add or edit a deploy group, you must create a Terminal location and add readers to that location. You can then assign locations to a deploy group, meaning all readers in the location receive updates from that deploy group.

After you create a deploy group, you can edit it at any time by selecting it.

Add a deploy group

On the Terminal apps tab, click Manage deploy groups.
Click Add deploy group.
Complete the following steps in the Add deploy group drawer:
- Enter a group name.
- Choose your Terminal device type.
- If desired, select the Default deploy group checkbox to create a default deploy group. A default deploy group automatically contains all locations that aren’t explicitly assigned to a different deploy group. You can create one default deploy group per device type.
- Click Done.

Manage deploy groups with destination charges

On the Terminal apps tab, click Manage deploy groups.
Select the deploy group from the list.
Click Add locations.
Choose the locations to add.
Click Done.

Manage deploy groups with direct charges

On the Terminal apps tab, click Manage deploy groups.
Select the deploy group from the list.
Click Add locations.
Select the account that you want to add locations from in the account dropdown. You must select an account before adding locations.
Choose the locations to add.
Click Done.

Deploy an app version

You can deploy your app after a Stripe reviewer approves it.

On the Terminal apps tab, choose the app that you want to deploy.
On the app details page, click Deploy version.
Choose a version of the approved app, and then click Next. You can’t deploy an earlier version of an app—the app version must be newer than the currently deployed app.
Choose the deploy group, then click Next.
Choose your preferred kiosk app, then click Next. This is the default app that launches when the Stripe reader turns on. If you only have one app to deploy, choose that app instead.
Confirm the deployment details, then click Deploy. The app deploys immediately.

Use this feature if you have multiple Stripe accounts and want to deploy the same app across accounts. Sharing one app across accounts avoids constraints with package name uniqueness and duplicate app reviews.

Designate one account to create and manage the app. Only the account that owns the app can upload new app versions, but other accounts can view and deploy the app by searching for the app ID.

On the Terminal apps tab, click the overflow menu ().
Click Search for app.
Enter the app ID and click View app details.
Click Deploy version and enter the deployment details.

Deploy your app to devices by creating a device deploy group and associating it with a location.

Create a device deploy group

Create a device deploy group with a given name and device_type.

The following response shows a tmddg_... identifier that you used to create the deployment plan.

{
  "id": "tmddg_EuEMSgeudJ0Zyw",
  "object": "terminal.device_deploy_group",
  "current_device_asset_versions": [],
  "device_type": "stripe_s700",
  "is_default": false,
  "livemode": false,
  "name": "my_toy_store_ddg"
}

Add readers to the device deploy group

Use the location API to add devices to a device deploy group. You can set the device_deploy_groups field on a location to map a device_type to the device deploy group.

The Deploy API supports the stripe_s700 device type (used by production Stripe S700 devices) and the stripe_s700_devkit device type (used by DevKit devices).

When you deploy a device asset version to a deploy group, the API validates that the compatible_device_types parameter matches the deploy group’s device_type.

Set the default app

Use the preferred_kiosk_app parameter to set the default app that launches on your devices.

Update your app

Use the device_asset_versions_to_install parameter to update the device asset version on your devices.

After you deploy your app, you can monitor its progress.

Uninstall your app

Use the device_assets_to_uninstall parameter to uninstall your app from your devices.

Launch the Stripe Reader app

You can revert your device deploy group to launch the Stripe Reader app instead of your preferred kiosk app.

In a single request, use the device_assets_to_uninstall parameter to uninstall your app, then set the preferred_kiosk_app parameter to STRIPE_APP (case sensitive). Make sure there are no third-party apps in the device deploy group.

Remove readers from a device deploy group

To remove readers from a device deploy group, set the device_deploy_groups parameter on a location to map a device_type to an empty string.

Deploy group best practices

You can sort devices into different deploy groups to roll out software independently and isolate fault in case of any issues. You might have fewer or more deploy groups based on tooling, risk tolerance, and specific business needs.

We recommend the following deploy group setup:

Alpha - Contains locations that correspond to your internal devkits or internal production devices.
Beta - Contains a small number of actual user locations. You can randomly choose these locations, select them based on meaningful criteria (for example, less risky locations), or have users opt in to the Beta deploy group based on their risk tolerance.
General - Contains all remaining actual user locations, except those in the Alpha or Beta groups. You can use a default deploy group to avoid manually assigning each remaining location.

When your app is ready for deployment, promote deploy groups from least to most risky:


1	Alpha	First, deploy to the Alpha deploy group to test your app in a way that minimizes risk to users. Discovering a bug or undesirable behavior at this stage only affects a small number of internal devices, rather than actual users and real payments.
2	Beta	Second, deploy to the Beta deploy group. This balances exposing your app to real users and not exposing all users to potential issues.
3	General	Finally, deploy to the General deploy group after addressing any issues or confirming that no issues existed for the Beta deploy group.

Next step

Monitor your deployment