Introduction

The Merchant Instance API is the core of the Shuttle platform. It provides direct access to all payment resources within a single merchant instance.

Payment Initiation

• Payments: API-based payments (one-time, recurring, authorisations)
• Checkouts: embedded payment experience via shuttle.js
• Payment Links: hosted payment pages via shareable URLs
• Deep Links: secure, time-limited URLs for embedded Merchant Setup and merchant views

Customer & Activity

• Accounts: your customers / payers, identified by your CRM key
• Payment Methods: tokenised cards, bank accounts, and wallets
• Transactions: the read-only ledger of all payment activity

Payment Lifecycle

• Captures: settle a previously authorised payment
• Voids: cancel an authorisation before capture
• Refunds: return money to the customer

Billing

• Contracts: the agreements behind every payment, with automatic retry logic for recurring billing
• Charges: invoices on recurring contracts

Configuration

• Gateways: merchant connections to payment processors
• Processors: available payment processor integrations
• Instances: check the capabilities of the current merchant instance

Enterprise

• Legal Entities: business entities that receive payments
• Legal Entity Routes: payment routing between entities and gateways
• Workflows: automated actions on payment events

List APIs

All list endpoints support criteria, order, and expand parameters. The available fields vary by endpoint; see individual endpoint documentation for the specific fields supported.

Criteria

The criteria parameter filters results. It supports these operators:

Combine multiple criteria with commas (AND logic):

criteria=status=ACTIVE;FAILING,[email protected]

Notes:

• Strings are case insensitive (some exceptions apply)
• Booleans are Y/N (tip: check for =Y or !=Y as some objects treat false as null)
• Remember to URL encode the criteria parameter, e.g., criteria=status%3DACTIVE%3BFAILING for criteria=status=ACTIVE;FAILING

Order

The order parameter controls sorting. It supports any field that criteria supports.

• Defaults to created;desc if not specified
• Ascending by default, append ;desc for descending
• Separate multiple fields with commas

order=updated
order=updated;desc
order=status,updated;desc

Expand

The expand parameter includes related objects in the response instead of just their IDs.

• Separate multiple fields with commas
• Some objects support nested expansion with dot notation

expand=account,payment_method
expand=account,contract.last_transaction

Without expand, related objects are returned as IDs:

{
  "transaction": {
    "id": "tr_1234_5678",
    "account": "acc_1234_9012",
    "payment_method": "pm_1234_3456"
  }
}

With ?expand=account,payment_method, the full objects are included:

{
  "transaction": {
    "id": "tr_1234_5678",
    "account": {
      "id": "acc_1234_9012",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]"
    },
    "payment_method": {
      "id": "pm_1234_3456",
      "type": "VISA",
      "last4": "4242",
      "expiry": "12/2026"
    }
  }
}

Pagination

All list endpoints support limit and offset for pagination. The response includes a meta object with total, limit, and offset.