Instances

Instances represent the merchants on your platform. Each instance is an isolated environment with its own accounts, payment methods, gateways, transactions, and configuration.

Instance Key

The instance_key is your identifier for the merchant — unique within your application. This is typically your merchant ID or a combination of environment and merchant ID (e.g., PROD_12345).

Creating an Instance

When creating an instance, provide at minimum an instance_key and name. You can also set:

• Contact details: contact_name, contact_email, contact_phone, country (used for support)
• Merchant name: merchant_name is the display name shown to customers in Apple Pay and Click to Pay prompts. Falls back to name if not set. Can be updated at any time.
• Receipt format: template for transaction references. Must contain #TRANSACTIONKEY# (zero-left-padded 8-digit number incrementing per instance from 10000, e.g., 00010000) or #TRANSACTIONID# (same number unpadded, prefixed with the client ID, e.g., 1234_10000 — globally unique). Some gateways require unique references across all connections — if you connect multiple instances to the same gateway account, use a unique prefix per instance (e.g., MERCHANT1-#TRANSACTIONKEY#), or use #TRANSACTIONID# which is globally unique without a prefix. Note that some gateways impose a maximum reference length — if the formatted value exceeds the limit, it will be front-trimmed.
• Secret key: set secret_key: "NEW" to generate a per-instance API key, allowing the merchant to authenticate directly against their instance without the platform's credentials. Retrieve it with ?expand=secret_key.
• Checkout URLs: domains where you embed the Shuttle checkout widget. Required to enable Apple Pay and Google Pay on those domains. Only list domains where you host the checkout widget yourself — Shuttle automatically registers its own hosted pages (payment links, app.shuttleglobal.com). Not needed if you only use Shuttle-hosted payment pages.
• Terms acceptance: set tcs_accepted: true if you've collected proof of T&C acceptance
• Legal entities: (enterprise) array of entities that can receive payment

Deleting an Instance

Deletion is irreversible. It immediately marks the instance as INACTIVE. No further payment instructions will be issued, including cancellations of in-flight operations. Authorised payments not yet captured will lapse.

See Also

For managing an instance's configuration after creation, see the Merchant Instance API Instances endpoints (get, update, capabilities).