User guides

These guides are how Shuttle behaves. Embedded Payments for Platforms is how you embed it, and What Shuttle Can Do is the one-page list of everything it does.

It covers the objects Shuttle works in, the ways money is collected into them, what happens to a payment and when, the screens your merchants and customers see, and the rules every operation follows. All of it is written for you, the platform, not for the people who will use the screens.

New here? Start with Core Concepts. It is the map: the records Shuttle keeps, the ways money is collected into them, and the behaviour that plays out afterwards. Once those make sense the screens, the rules and the API all read the same way, because they are the same things seen from different angles.

Nested under it: Payment Types, Payment Lifecycle and Scheduler.

Read these through one lens

Almost nothing here is fixed. Most controls can be switched off per application or per embed, several depend on the payment processor a merchant connected, and the checkout in particular is shaped almost entirely by the request your platform sends. Two merchants on your platform can meet very different versions of the same screen.

So these pages describe everything a component can do. Yours will do a subset, and choosing that subset is the point. Each guide has a “What you control” section saying which parts are your decision, and the switches themselves are listed in Merchant View Options.

Where you go on to write instructions for your own merchants or agents, these pages are the source: take the parts you have enabled and leave the rest.

The screens

• Merchant Setup connects a payment processor. A merchant accepts the terms, adds one or more processors, and chooses which payment methods the checkout offers. Their processor credentials never pass through your systems. Embedding it: component, integration guide.
• Merchant View - Operations is the day-to-day console for a merchant’s staff. Find a customer, take or refund a payment, manage a contract or a saved payment method, and read the full history of any record. Embedding it: Merchant View through shuttle.js, with a deep link deciding what the merchant lands on.
• Merchant View - Admin is the second mode of the same console: the administrative side, for settings a merchant manages for themselves. Today it holds the wording your customers read, which is set once for everybody and so is an administrator’s job rather than an agent’s. Expect it to gain more over time. Many platforms keep this mode to themselves.
• Checkout is the hosted payment page your customers reach. What the form shows, how they pay or save a payment method, what happens at a bank authentication step, and the receipt. Embedding it: component, integration guide.

Business rules

Every action that changes something, from a screen or from the API, follows the same rules: who may perform it, what must already be true, what Shuttle checks, and what happens as a result. Those are written once in Business Rules, and every screen guide and API reference page links to them.

Go there when a guide says a control “ends the agreement” and you need to know exactly when that is allowed, what it does to the outstanding charges and the payment method, and which webhook you will receive. It is also where to look before building a request: it says what Shuttle will refuse, and what it will accept from a direct API call even when a screen would not.

Start with Roles and permissions, which explains the four roles assigned to a merchant’s users and what each can do.

How to read a screen guide

Every screen page has the same shape: what the screen is for, where to find it, what you see, what you can do, and things to note.

Sections that appear on several screens are described once rather than repeated. Searching and filtering, the contract statement, the arrears panel, comments and the audit history each have one page, linked from every screen that uses them. Where a control changes something, the page links to the rule behind it.

Screenshots show the default appearance. Your branding, and the options you have set, will change what a merchant actually sees.