Apps & routing
An app is your product as the broker sees it. Its key identifies it; its settings decide what to create and which gateway takes each payment, so your product never changes when you do.
One key per product
Create one app per product and environment (blackevin-prod, blackevin-staging, contagorda…). Each has its own secret key, allowed return hosts and outbound webhook, and only sees its own sessions and subscriptions. Revoking one key never touches the others.
The New app form sets it up in one step: name and charges, its routes (gateways in order, each with an optional From and Until) and an optional outbound webhook. Right after, the app page shows the key and the /connect request to copy.
The key in Settings is the tenant key: it acts as admin over every app (and on the Default app unless you pass "app"). Give your products app keys.
Routes pick the gateway
- 1Routes are tried in order: the first one inside its window whose gateway is active and supports the payment takes it.
- 2A route can have a window (from Dec 1 to Dec 10, for instance): outside it the route is skipped, and the next one takes over by itself.
- 3Methods, currencies and subscriptions come from what each gateway supports; everything else is configured in the gateway itself.
- 4If a gateway fails to open the checkout, the next eligible route is tried at once; the session keeps the attempts in its metadata.
- 5An app without routes uses every active gateway of the account by priority.
What never moves
A subscription stays on the gateway it started on: the card authorization lives there, so renewals and cancellation keep going to it. Changing routes affects new payments and new subscriptions only; the app page shows how many active subscriptions stay on each gateway.
Payment or subscription
An app charges one-off payments or subscriptions (its Charges setting). /connect creates that kind; switching it changes the product's checkout without a deploy. POST /api/v1/sessions and /api/v1/subscriptions stay available for either kind.