Core Concepts

Shuttle is easier than it looks. There are records it keeps, a handful of ways money gets collected into them, and some behaviour that plays out over time. Everything else — the screens, the API, the webhooks, the business rules — is one of those three seen from a different angle.

This page is the map. Read it once and the rest of the documentation stops being a list of features.

1. The records

Five objects carry almost everything. Whatever a merchant does on a screen, and whatever you send to the API, it comes down to creating or changing one of these. If you only take one-off payments, read the table and then the section under it — there is a shortcut.

The first four are the spine of a payment and read in order: who, what they agreed, what is due, what moved. The payment method hangs off the account rather than sitting in that chain, which is why one method can pay for several contracts and a contract can change method without disturbing anything else.

One-off payments: the payment object

Most integrations only ever take one-off payments, and for those you do not need to think about contracts and charges at all.

Underneath, a single purchase is still a contract with one charge and one transaction, which completes the moment it is paid. That is deliberate, and it is why the same rules, the same screens and the same webhooks serve a £5 donation and a three-year instalment plan. But you do not have to assemble those three yourself: Shuttle returns a payment — a convenience object carrying the amount, currency, status, gateway result, reference, account, payment method and settlement figures together in one place.

So take a one-off payment and read the payment in the response. The contract and transaction are returned alongside it if you need them, and they are what you will reach for once you start collecting over time.

How they fit together

An account owns contracts and payment methods. A contract holds charges. A charge is settled by one or more transactions, each drawing on one of the account's payment methods. Money attributed to a transaction moves the charge towards complete, and a contract with nothing outstanding and nothing scheduled completes itself.

Two of these come into existence earlier than people expect. The account is created when you prepare a checkout, before the customer has seen the form. The contract and the transaction are written before the payment processor is called, so both exist while the money is still in flight — see When a payment is interrupted, which sets out exactly what exists at each point.

2. How money gets collected

There is more than one way to reach those records, and a platform usually uses two or three. They differ in who is present, who builds the request and where the customer enters their details — but they all end in the same account, contract, charge and transaction, and they all follow the same Business Rules.

Before any of them works, the merchant has to have connected a payment processor. That is its own component and its own guide: Merchant Setup · Guide.

Choosing between these at the level of how much you build — zero-code, payment links, or a full white-label integration — is covered in Platform Integration Approaches.

3. What happens over time

A one-off card payment is usually finished when the request returns: approved or declined, and that is that. These three pages are for everything that is not — an agreement that collects again next month, a bank debit that settles days later, an attempt that ended without an answer.

• Payment Types — the four shapes a contract can take, and the request that creates each. Single pay-now, scheduled one-time, recurring, and an explicit schedule of charges.
• Payment Lifecycle — not every payment is approved or declined on the spot. Some payment rails are asynchronous by design and take days to settle; others are held back, by a fraud tool waiting on a decision or by a processor that never gave a clear answer. The page sets out what a transaction can be, what each state means, and the distinction that matters most: PENDING resolves itself, UNRESOLVED will not, and they need opposite responses.
• Scheduler — what drives everything future-dated. Creating the next charge, attempting collection, retrying a failure, and completing or suspending the contract.

4. What a person sees

Shuttle provides the screens for the parts of payments that need a person. Each is embedded in your product and documented twice: a component page for embedding it, and a guide for what is actually on it.

• Merchant Setup — a merchant connects a payment processor and chooses what the checkout offers.
• Merchant View - Operations — the merchant's staff find a customer, take or refund a payment, and manage contracts and saved payment methods.
• Merchant View - Admin — the administrative side of the same console, for settings a merchant manages for themselves. Today that is the wording customers read, edited once for everybody.
• Checkout — the customer pays, or saves a payment method without paying, and sees their receipt.

Most of what these screens offer can be switched off per application or per embed, so decide what yours does rather than assuming a merchant sees all of it: Merchant View Options.

5. What is allowed

Every operation that changes something — from a screen or from the API — follows one set of rules: who may do it, what must already be true, what Shuttle checks, what it changes, and which webhook you get. Those are written once in Business Rules, and everything else links to them.

Go there when this page says a contract "completes" and you need to know exactly when that happens, or when a guide says a control "ends the agreement" and you need to know what that does to the outstanding charges. It is also where to look before building a request: it says what Shuttle will refuse, and what a direct API call is allowed to do even where a screen would not.

Start with Roles and permissions.

Where to go next