v9 (current) v8
Edit Page

Configuration

RESTHeart

restheart-stripe is configured through the stripeConfig block. Everything is disabled by default: enabling the module is a deliberate act.

RESTHeart uses its default configuration; you only need an override file for the settings that differ.

Quick start

Create an override file (e.g. stripe.conf):

# enable the module and set credentials
/stripeConfig/enabled -> true
/stripeConfig/secret-key -> "sk_test_..."
/stripeConfig/webhook-secret -> "whsec_..."

# enable subscriptions
/stripeConfig/subscriptions/enabled -> true
/stripeConfig/subscriptions/default-plan -> free
/stripeConfig/subscriptions/success-url -> "https://app.example.com/billing?success=true"
/stripeConfig/subscriptions/cancel-url -> "https://app.example.com/billing?canceled=true"
/stripeConfig/subscriptions/portal-return-url -> "https://app.example.com/billing"

# enable products
/stripeConfig/products/enabled -> true
/stripeConfig/products/default-currency -> eur
/stripeConfig/products/success-url -> "https://shop.example.com/done?session={CHECKOUT_SESSION_ID}"
/stripeConfig/products/cancel-url -> "https://shop.example.com/cart"

# enable the plugins you need
/stripeService/enabled -> true
/stripeInitializer/enabled -> true
/stripeWebhookService -> { "enabled": true }

# subscriptions plugins
/stripeCheckoutService/enabled -> true
/stripePortalService/enabled -> true
/stripeSubscriptionService/enabled -> true
/stripePlansService/enabled -> true
/stripeCatalogCache/enabled -> true
/stripeLicensesService/enabled -> true

# products plugins
/ordersCheckoutInterceptor/enabled -> true
/ordersCheckoutResponseInterceptor/enabled -> true

Start RESTHeart:

java -jar restheart.jar -o stripe.conf
Warning

Never write Stripe keys literally in a file that gets committed. Use environment variable expansion in the override file:

/stripeConfig/secret-key -> "${STRIPE_SECRET_KEY}"
/stripeConfig/webhook-secret -> "${STRIPE_WEBHOOK_SECRET}"

Or pass them via RHO:

RHO='/stripeConfig/secret-key->"'$STRIPE_SECRET_KEY'"' java -jar restheart.jar -o stripe.conf

Structure

stripeConfig:
  enabled:              # master switch
  secret-key:           # shared — Stripe API key
  webhook-secret:       # shared — webhook signing secret
  teams-collection:     # shared — default: teams

  subscriptions:
    enabled:            # subscriptions mode on/off
    default-plan:       # plan for entities with no subscription
    plans:              # the plan catalog
    success-url:        # checkout redirect
    cancel-url:         # checkout redirect
    portal-return-url:  # portal return URL
    notifications:      # per-notification enabled flags
    templates:          # custom email template paths

  products:
    enabled:            # products mode on/off
    catalog-collection: # default: catalog
    orders-collection:  # default: orders
    transactions-collection: # default: transactions
    inventory-collection:    # optional — omit to disable stock checks
    default-currency:   # default: eur
    buyer-email-field:  # default: _id
    success-url:        # checkout redirect
    cancel-url:         # checkout redirect
    session-expires-minutes: # default: 60
    max-line-items:     # default: 50
    max-quantity-per-line:   # default: 100
    automatic-tax:      # default: true
    shipping-options:   # for physical products
    notifications:      # order-confirmed, order-refunded
    init-enabled:       # default: true, set false for multi-tenant on-demand init

Credentials and database are shared across both modes. Each mode has its own sub-section.

Shared keys

Key Default Description

enabled

false

Master switch for the module.

secret-key

(none)

Stripe secret API key. Required.

webhook-secret

(none)

Webhook signing secret. Required.

teams-collection

teams

Collection holding team documents.

The MongoDB database is sourced from mongoRealmAuthenticator.users-db, not from stripeConfig. This prevents the two modules from drifting apart:

/mongoRealmAuthenticator/users-db -> "myapp"

Subscriptions keys

Key Default Description

enabled

false

Subscriptions mode on/off.

default-plan

free

Plan id for entities with no subscription.

default-trial-period-days

0

Fallback trial days.

success-url

(empty)

Checkout redirect after payment.

cancel-url

(empty)

Checkout redirect on abandonment.

portal-return-url

(empty)

Customer Portal return URL.

plans

(empty)

Plan catalog. See Plans & Seats.

Products keys

Key Default Description

enabled

false

Products mode on/off.

catalog-collection

catalog

Product definitions.

orders-collection

orders

Order documents.

transactions-collection

transactions

Money ledger.

inventory-collection

(none)

Stock data. Omit to disable stock checks.

default-currency

eur

Currency when a product has none.

buyer-email-field

_id

User-document field for buyer email.

success-url

(empty)

Checkout redirect after payment.

cancel-url

(empty)

Checkout redirect on abandonment.

session-expires-minutes

60

Checkout session lifetime.

max-line-items

50

Maximum items per cart.

max-quantity-per-line

100

Maximum quantity per item.

automatic-tax

true

Enable Stripe Tax.

init-enabled

true

Set false for on-demand init (multi-tenant).

Plugins

Each plugin is enabled independently.

Plugin Role

stripeConfig

Reads the stripeConfig block. Required.

stripeService

Holds the SubscriptionOwnerProvider. Required.

stripeInitializer

Validates config, creates indexes, registers @subscription. Required.

stripeWebhookService

POST /stripe/webhook. Required.

Subscriptions:

stripeCheckoutService

POST /stripe/checkout

stripePortalService

POST /stripe/portal

stripeSubscriptionService

GET /stripe/subscription

stripeLicensesService

/stripe/licenses

stripePlansService

GET /stripe/plans

stripeCatalogCache

Display data cache for /stripe/plans

Products:

ordersCheckoutInterceptor

Validates cart, creates Checkout session

ordersCheckoutResponseInterceptor

Adds _id, checkout_url, secret to response

Startup validation

stripeInitializer runs before the HTTP server starts and logs errors when:

  • secret-key or webhook-secret is missing

  • default-plan does not name a declared plan (subscriptions only)

Important

RESTHeart catches initializer exceptions and logs them — it does not abort startup. Check the log for [stripe] errors.

On success:

[stripe] plugin initialised — mode=TEST, db=myapp, subscriptions=true, products=true

Notifications

Subscriptions

Notification Default Sent when

payment-failed

false

Invoice payment fails

trial-will-end

false

Trial ending in 3 days

subscription-canceled

true

Subscription deleted

over-limit

true

Seat limit exceeded

Products

Notification Default Sent when

order-confirmed

true

Order paid

order-refunded

true

Refund recorded

Notifications use the emails plugin. If absent, they are silently skipped.

Complete example

# stripe.conf — override file for restheart-stripe

/mongoRealmAuthenticator/users-db -> "myapp"

# ── shared ──
/stripeConfig/enabled -> true
/stripeConfig/secret-key -> "${STRIPE_SECRET_KEY}"
/stripeConfig/webhook-secret -> "${STRIPE_WEBHOOK_SECRET}"

# ── subscriptions ──
/stripeConfig/subscriptions/enabled -> true
/stripeConfig/subscriptions/default-plan -> free
/stripeConfig/subscriptions/default-trial-period-days -> 14
/stripeConfig/subscriptions/success-url -> "https://app.example.com/billing?success=true"
/stripeConfig/subscriptions/cancel-url -> "https://app.example.com/billing?canceled=true"
/stripeConfig/subscriptions/portal-return-url -> "https://app.example.com/billing"

/stripeConfig/subscriptions/plans -> {
  "free": { "seats": { "mode": "capped", "max": 1 } },
  "gold": {
    "price-id-monthly": "price_xxx",
    "price-id-annual": "price_yyy",
    "trial-period-days": 30,
    "seats": { "mode": "capped", "max": 10 }
  }
}

# ── products ──
/stripeConfig/products/enabled -> true
/stripeConfig/products/default-currency -> eur
/stripeConfig/products/buyer-email-field -> _id
/stripeConfig/products/success-url -> "https://shop.example.com/done?session={CHECKOUT_SESSION_ID}"
/stripeConfig/products/cancel-url -> "https://shop.example.com/cart"
/stripeConfig/products/automatic-tax -> true

# ── plugins ──
/stripeService/enabled -> true
/stripeInitializer/enabled -> true
/stripeWebhookService -> { "enabled": true }
/stripeCheckoutService/enabled -> true
/stripePortalService/enabled -> true
/stripeSubscriptionService/enabled -> true
/stripePlansService/enabled -> true
/stripeCatalogCache/enabled -> true
/stripeLicensesService/enabled -> true
/ordersCheckoutInterceptor/enabled -> true
/ordersCheckoutResponseInterceptor/enabled -> true