---
title: Configuring the Stripe Element
description: "The [Stripe](stripe) [Element](https://namazustudios.com/glossary/element/) is configured through standard Elements deployment attributes, with two of them — the API key and webhook signing secret — overridable at runtime from a superuser admin panel without a rebuild or redeploy. This page covers the…"
url: "https://namazustudios.com/docs/add-ons/commerce/stripe/configuring-the-stripe-element/"
updated: "2026-08-14"
category: "Add-Ons / Commerce / Stripe"
---

# Configuring the Stripe Element

The [Stripe](stripe) [Element](https://namazustudios.com/glossary/element/) is configured through standard Elements deployment attributes, with two of them — the API key and webhook signing secret — overridable at runtime from a superuser admin panel without a rebuild or redeploy. This page covers the available attributes, how credential precedence works, running multiple environments safely, and the Maven coordinates other Elements need to depend on it.

---

## Attributes

| Attribute | Default | Description |
| --- | --- | --- |
| `dev.getelements.elements.stripe.api.key` | *none — required* | Stripe secret API key (`sk_live_...` or `sk_test_...`). Marked sensitive. |
| `dev.getelements.elements.stripe.webhook.secret` | *none — required* | Stripe webhook signing secret (`whsec_...`), shown by Stripe when you register a webhook endpoint. Marked sensitive. |
| `dev.getelements.elements.Element.rs.root` | `/Element/stripe/api` | [REST](https://namazustudios.com/glossary/rest/) API root path for every endpoint this [Element](https://namazustudios.com/glossary/element/) exposes. |
| `dev.getelements.elements.auth.enabled` | `true` | Enables the Elements [Session](https://namazustudios.com/glossary/session/) auth filter for this [Element](https://namazustudios.com/glossary/element/)'s endpoints. |
| `dev.getelements.elements.stripe.price.cache.ttl.ms` | `300000` (5 minutes) | How long `listPrices` and the catalogue-wide `resolvePriceForMeterEventName` cache their results in memory before re-querying Stripe. |

---

## Setting Attributes

**Deployed instances** — set attributes from the admin panel under [Element](https://namazustudios.com/glossary/element/) Management. Select the deployment and edit its attributes directly; no rebuild is required.

**Local development** — set attributes as system properties when launching the `debug` module:

```
mvn -pl debug exec:java
  -Ddev.getelements.elements.stripe.api.key=sk_test_YOUR_KEY
  -Ddev.getelements.elements.stripe.webhook.secret=whsec_YOUR_SECRET
```

Defaults can also be baked into `Element/src/main/elm/dev.getelements.Element.attributes.properties` so they're packaged into the `.elm` archive itself — these are still overridden by anything set at the deployment level.

---

## Credential Precedence and the Admin Panel

The API key and webhook secret can also be set from the "Stripe" tab in the superuser admin dashboard, or directly via `PUT /stripe/config`. Values saved this way are persisted to a MongoDB document and take precedence over the deployment attributes whenever they're non-blank — `GET /stripe/config` returns the effective values with everything but the last four characters masked (e.g. `••••1234`), so the full secret is never re-displayed once saved.

This lets an operator rotate a compromised key or point a deployment at a different Stripe account without touching deployment attributes or redeploying. If no override has been saved, the [Element](https://namazustudios.com/glossary/element/) falls back to the injected attribute values above.

---

## Multi-Environment Deployments

Run separate environments (e.g. `MyGame_Dev`, `MyGame_Staging`, `MyGame_Prod`) by deploying a [Distinct](https://namazustudios.com/glossary/distinct/) instance of this [Element](https://namazustudios.com/glossary/element/) per environment, each with:

- Its own Stripe API key and webhook secret, configured independently through the Stripe → Configuration admin tab
- Its own MongoDB database (or at minimum a separate MongoDB instance), so configuration and event-log data are naturally isolated with no extra namespacing required

In the Elements platform this maps directly to creating one [Application](https://namazustudios.com/glossary/application/) deployment per environment. Because each deployment connects to its own database, the [DAO](https://namazustudios.com/glossary/dao/) layer needs no special configuration to achieve isolation.

Warning

Do not share one MongoDB database between multiple deployments of this [Element](https://namazustudios.com/glossary/element/). The configuration and webhook event-log collections use fixed, unnamespaced names (`stripe_config` and `stripe_event_log`), so sharing a database lets one deployment's credentials and event log bleed into another's.

---

## Build and Run

```
# Build everything (requires Java 21 + Maven)
mvn install

# Start local MongoDB
docker compose -f services-dev/docker-compose.yml up -d

# Run locally
mvn -pl debug exec:java
```

The admin UI panel is only built under the `build-ui` Maven [Profile](https://namazustudios.com/glossary/profile/) (`mvn install -Pbuild-ui`); its React bundle is copied into the `.elm` archive's `ui/` directory and registers a "Stripe" tab (icon: `CreditCard`, route: `stripe`) in the superuser dashboard.

---

## Maven Coordinates

Deploy the `.elm` archive built by the `Element` module. Other Elements that call `StripeService` directly (rather than only consuming its events or [REST](https://namazustudios.com/glossary/rest/) API) should also depend on the `api` module, provided at compile time:

```
<!-- .elm archive (for deployment) -->
<dependency>
    <groupId>dev.getelements.elements.stripe</groupId>
    <artifactId>element</artifactId>
    <version>1.0.3</version>
    <type>elm</type>
</dependency>

<!-- API interfaces (for other Elements that depend on this one) -->
<dependency>
    <groupId>dev.getelements.elements.stripe</groupId>
    <artifactId>api</artifactId>
    <version>1.0.3</version>
    <classifier>dev.getelements.elements.stripe.api</classifier>
    <scope>provided</scope>
</dependency>
```

---

## Integration Tests

Integration tests exercise the real Stripe API in test mode. Credentials come from environment variables so CI can inject them as secrets:

| Env var | Maven property | Purpose |
| --- | --- | --- |
| `STRIPE_TEST_API_KEY` | `stripe.test.apiKey` | Stripe test-mode secret key |
| `STRIPE_TEST_CUSTOMER_ID` | `stripe.test.customerId` | Existing test-mode customer to reuse |
| `STRIPE_TEST_PRICE_ID` | `stripe.test.priceId` | Existing test-mode price to reuse, instead of creating a new Product + Price every run |

```
export STRIPE_TEST_API_KEY=sk_test_YOUR_KEY
mvn verify -pl integration-test
```

Each variable can also be overridden per run with the matching `-Dstripe.test.*` system property. Subscription tests create and tear down a real subscription automatically. Webhook tests generate and verify their own HMAC signatures against a fixed, non-secret test key, and run without any network connection or Stripe credentials.

---

## Related Pages

- [Stripe](stripe) — [Element](https://namazustudios.com/glossary/element/) overview and core concepts
- [Stripe Webhooks and the Typed Event Bus](stripe-webhooks-and-events) — webhook Dashboard setup and the typed event list
- [Stripe REST API Reference](stripe-rest-api-reference) — full [REST](https://namazustudios.com/glossary/rest/) endpoint reference