Connect a payment processor

Creates a payment gateway for the instance: a connection to a payment processor, set up either by authorising Shuttle at the processor (OAuth, or the processor's own embedded onboarding script) or by entering credentials into the processor's settings form. The gateway is created first and the credentials are then tested at the processor: a rejected connection is reported to the merchant but the gateway it created stays behind. When the merchant has no routing yet Merchant Setup also names the organisation legal entity, and the same call routes the new provider for every payment method it supports, which is what makes the checkout start using it. The sandbox "Skip" shortcut is the same function with the SANDBOX processor and seeded values.

Where you can do this

Merchant Setup: Adding a payment processor (the processor row, then Connect {name})
Merchant Setup: Adding a payment processor (skip)
Merchant Setup: Entering connection details (Save)
API: Create a gateway (POST /gateways) — body carries processor, values and optionally oauth_data and legal_entity

Before you start

The instance resolves to an application (the platform's product configuration for it).
The processor is an integration of an active or hidden vendor and has a configuration for the instance's environment: the sandbox configuration for a sandbox instance, the live one otherwise.
For an OAuth processor, a completed authorisation at the processor whose token is still cached; the token expires an hour after the authorisation returns.
For the sandbox shortcut, a sandbox instance with no connected provider and a sandbox processor that is visible to it.
Nothing about existing gateways: the same processor can be connected again, creating a second gateway.

Inputs

Input	Required	Meaning and constraints
name	no	Display name. Defaults to the processor's name
code	no	Your reference for the gateway. Must be unique across gateways; generated when omitted
values	no	The processor's settings values, as its own settings form defines them. Posted values win over values supplied by the OAuth authorisation, which win over the processor's defaults
metadata	no	Custom key-value pairs stored on the gateway
tags	no	References for searching

Rules

Checked by the API means Shuttle refuses the request however it is sent; a screen name means only that screen refuses it, and a direct API call would be accepted.

Rule	Checked by	What you see
The body must carry a gateway object naming a processor	The API	VALIDATION_ERROR (400): "API body error: missing gateway object"
Whether the processor is visible to the instance is not checked on create; Merchant Setup offers only visible processors, narrowed by the deep link's processor list and the country filter	Merchant Setup screen	the processor is not in the picker
The instance must resolve to an application	The API	INVALID_REQUEST (400): "Invalid endpoint"
The processor is mandatory on create	The API	MANDATORY: "validations.paymentGateway.gatewayType.notempty"
A name is mandatory; Shuttle defaults it to the processor's name, so this only bites a caller that sends an empty one	The API	MANDATORY: "validations.name.notempty"
The reporting code must be unique across the instance's gateways; left blank it is generated	The API	INVALID: "validations.reportingCode.nonunique"
The processor connection is tested by the provider integration before the settings are stored, and a failure rejects them. The test runs only when settings values were supplied and the processor implements a connection check; a processor without one reports the connection as unknown and always saves	The API	INVALID (400) with the processor's message: "Invalid credentials", "Connection Failed", or the processor's own text
Settings values are not checked against the processor's settings schema server-side; the processor's own save and Merchant Setup's form are the only checks	Merchant Setup screen	form validation
status sent on create is dropped: every gateway starts at SETUP and Shuttle moves it itself. Merchant Setup sends CREATED	The API	silent
status_reason sent on create is dropped: Shuttle's create request carries no field for it, so a new gateway never has one, even though the gateway object returns it. Shuttle writes it only on a status change of its own	The API	silent
Omitting currencies or payment_method_types on create enables the gateway for everything the processor supports; on an existing gateway the same omission disables it, see Update a provider's settings	The API	silent
The merchant must accept the terms before Merchant Setup will let a provider be connected; not enforced server-side	Merchant Setup screen	the app sends the merchant to the terms screen first, see Accept Shuttle's terms for the instance
The sandbox shortcut is offered only on a sandbox instance that has no gateway yet and whose sandbox processor is visible; it connects the SANDBOX processor with cards, ACH and SEPA enabled, network tokenisation on and a 60-second pending window	Merchant Setup screen	the shortcut is not shown
Merchant Setup names a legal entity only when the instance has no routing at all, and always the organisation entity; an API caller may name any legal entity. A second provider connected through the app is therefore created unrouted and takes no payments until it is routed	Merchant Setup screen	no routing is created with the gateway, see Route a payment method to a provider
Connecting the same processor twice is allowed; only a single-provider deep link prevents it, by opening the existing connection instead and refusing outright when the instance already has other connections	Merchant Setup screen	a second gateway for the same processor is created

What happens

A gateway is created for the processor and appears on the merchant's provider list, named after the processor unless a name was given. It starts at SETUP, reaches CREATED once the processor's settings are stored (or the processor needs none), and LINKED once it has routing.
The credentials are tested at the processor as part of the call. A rejected connection returns the processor's own message and stores nothing, but the gateway it created is still on the list and has to be reconnected (Reconnect a provider) or archived (Disconnect a provider).
When the merchant had no routing at all, the organisation legal entity is routed to the new provider for every payment method it supports, so the checkout starts offering it; where an existing route is displaced it is run down rather than removed, so saved cards on the old provider keep working (Route a payment method to a provider). When routing already exists, nothing is routed and the new provider takes no payments until it is.
The response carries the new gateway: its id, status, the account name the processor reports, and the currencies and payment methods the processor accepts.
GATEWAY.CREATED is delivered, with LEGAL_ENTITY_ROUTE.CREATED for each route created; the provider is added to the instance's settings. No email or SMS is sent.

Who can do this

Roles: Admin only. Support does not hold payment_gateway, and by design does not set up providers.
Permission keys (for clients managing permissions directly): payment_gateway (or *), checked by Shuttle against the division the gateway is created in: the division in the body, or the instance-wide division when none is sent, which is what Merchant Setup sends. Without it the call is refused with NO_PERMISSION (403) "apiValidation.error.permissions"; without a valid session, UNAUTHORIZED (401). Shuttle checks nothing on this route, unlike Update a provider's settings, which checks payment_gateway on the gateway itself. Merchant Setup enables its connect controls for anyone holding payment_gateway (or *) on any object, so a user whose key is scoped to a single division sees the controls and is refused by Shuttle. The sandbox shortcut and the processor picker are not gated at all in the app; only the connect confirmation and the settings form are.
App options: a single-provider deep link restricts which processor can be connected and suppresses the surrounding navigation; a deep link may also carry a processor list that narrows the picker, and a country that presets its filter. All of that is Merchant Setup's routing, not the server's.