Merchant instance API

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.

Paging

List endpoints return a page at a time: limit records (20 if not set, at most 1,000), after skipping offset records. offset + limit can’t exceed 5,000. To read more than 5,000 records, page by a field such as created instead: see Paging through results.

Criteria

The criteria parameter filters results. It supports these operators:

Operator	Description	Example
=	Exact match. Separate multiple values with ; for IN	status=ACTIVE;FAILING
!=	Not equal	status!=ARCHIVE
~=	Partial match (case insensitive)	email~=example.com
>, >=, <, <=	Comparison	created>=2024-01-01
<>	Between. Separate values with ;	created<>2024-01-01;2024-12-31
!	Is null	completed!
!!	Is not null	payment_method!!

Combine multiple criteria with commas (AND logic):

criteria=status=ACTIVE;FAILING,email=dave@gmail.com

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": "jane@example.com"
    },
    "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.