Applications

Shuttle’s hierarchy has three levels as presented to platforms:

Organisation
├── Application (e.g. EU)
│   ├── Sandbox (sandbox credentials)
│   │   ├── Instance A
│   │   ├── Instance B
│   │   └── ...
│   └── Live (live credentials)
│       ├── Instance A
│       ├── Instance B
│       └── ...
└── Application (e.g. US)
    ├── Sandbox (sandbox credentials)
    │   ├── Instance A
    │   └── ...
    └── Live (live credentials)
        ├── Instance A
        └── ...

An organisation is your platform entity in Shuttle. Teams and access control are configured at the organisation level. Under it you have one or more applications — typically one per region or deployment. Each application has a sandbox environment for testing and a live environment for production, each with its own shared key and secret key.

Under the hood, sandbox and live are stored as separate Shuttle applications — which is why they have independent credentials. But they are presented and managed as environments within a named application.

Instances are the per-merchant unit within each environment. See Multi-tenancy / instances for how to structure and manage them.

Credentials

Each environment within an application has its own credentials, consisting of a Shared Key and a Secret Key. The shared key identifies the application environment; the secret key authenticates API requests.

Each environment has one API key, and can hold a second while you change over to a new one: create API Key 2, move your integration to its secret key, then disable API Key 1. See Authentication for platforms. Keep secret keys secure: they grant full API access to the application environment.

Webhook destination

By default, webhook events for all instances within an application are delivered to a single URL configured at the application level. Payments, refunds, checkouts, and all other events from every instance go to that destination.

An individual instance can override this via the webhook_target field on the Create Instance and Update Instance endpoints. The instance target replaces the application target for that instance — events are not sent to both destinations. Instances without their own webhook_target continue to use the application destination.

If you need an instance’s events at both destinations, set the instance webhook_target to a fan-out target listing both URLs. See Webhook destinations.

Application configuration

Certain configuration is set at the application level by Shuttle and applies to all instances within it:

• Available payment processors: Which processors your merchants can connect, based on your agreement with Shuttle.
• Available features: Which Shuttle features and products are accessible within this application (e.g., BNPL messaging, express checkout, specific payment methods).

This is managed by Shuttle during onboarding and can be adjusted by contacting support.

When to use multiple applications

By default, you have one sandbox application and one live application. Common reasons to add more:

• Distinct products or business lines: If your platform has two separate areas that need payments — for example, a marketplace and a subscriptions product — each can have its own application with independent credentials, configuration, and webhook destination.
• Multiple regions or deployments: If your infrastructure is split across data centers or regions, a separate application per deployment means webhooks arrive directly at the right server rather than routing through a central point.

Contact Shuttle support to provision additional applications.