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.

You can create multiple sets of credentials for an application — each generates a new shared key and secret key pair. Keep secret keys secure: they grant full API access to the application environment.

Webhook Destination

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.

Instance-level webhook overrides are also available via the webhook_target field on the Create Instance and Update Instance endpoints, but the application-level destination is the default for all instances.

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.