Update a provider's settings

Saves edited settings for a connected gateway (or workflow): the processor's own form values, handed to the processor and re-tested against it before they are stored. The same call decides what the gateway is enabled for, because the enabled currency and payment method lists are rewritten from the body on every save; Merchant Setup sends "all supported" each time so the server recomputes them from the processor rather than freezing yesterday's list. A settings form that asks for a second "apply" step is saving twice: there is no separate apply operation on the server.

Where you can do this

Merchant Setup: Managing a connection (Save)
API: Update a gateway (PUT /gateways/{gateway_id}) — status unchanged; body carries values and currencies

Before you start

The gateway or workflow exists and is not deleted.
Neither the record nor its processor integration is archived, if the processor is to be called at all. An archived record can still be edited through the API without one (see Rules and Dismiss an archived provider's notice); Merchant Setup never offers Save on one.

Inputs

Input	Required	Meaning and constraints
values	no	Settings form values, in the shape the processor's settings form defines. On a gateway they are merged over the stored values, so a partial post keeps the rest; OAuth-supplied values win over posted ones. On a workflow they replace the stored values outright. Omitting them leaves the stored values untouched.
status	no	When sent it must equal the record's current status. A different status turns the call into a status change and discards every other field (see Disconnect a provider, Restore an archived provider).
metadata	no	Free-form key-value pairs. Kept when omitted on a gateway; wiped when omitted on a workflow (see Rules).
tags	no	Same handling as metadata.
fields that belong to another function and are accepted on the same call	no	`oauth_data` (and the provider authorisation values it carries); see Reconnect a provider.

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	The API	VALIDATION_ERROR (400), "API body error: missing gateway object"
The record must exist	The API	NOT_FOUND (404), "Gateway not found" / "workflow not found"
The name must not be blank	The API	validations.name.notempty
The reporting code cannot be blanked on an existing record, and must be unique	The API	validations.reportingCode.notempty, validations.reportingCode.nonunique
The processor connection is re-tested with the new values and the save is rejected on failure. Not every processor can be tested: where its connector implements no check, the connection is reported as unknown and the save goes through	The API	INVALID (400) with the processor's own message, or "Invalid credentials"
Nothing is stored when that test fails: the values reach the processor before the record is written	The API	the stored settings and the record's version are unchanged
Values are not checked against the settings schema server-side; the processor's integration and Merchant Setup's rendering of that schema are the only checks	Merchant Setup screen, the API (processor integration)	the form refuses to submit; the server accepts whatever the integration accepts
The enabled and displayed currency and payment method lists are rewritten from the body on every save, for gateways	The API	a caller who sends a narrower list narrows the gateway; one who sends none widens it back to everything supported
A gateway cannot be disabled for every currency or method through this call: an empty or omitted list is read as "all supported", and even a stored "none" resolves back to everything supported when the routing and payment code reads it	The API	no way to switch a gateway off here; use Disconnect a provider
A save that changes nothing is dropped: the record is only written, versioned and announced when its contents actually differ	The API	no webhook, no version bump
Merchant Setup sends "all supported" currencies and a null legal entity on every save	Merchant Setup screen	a save from the app never narrows the gateway and never disturbs its routing
A settings form may mark a field as needing a second "apply" save. The app then saves, reloads the settings and leaves the form open; the server sees two ordinary saves and cannot tell them apart	Merchant Setup screen	the form stays open for the second save

What happens

The settings are re-tested against the processor and stored. On failure nothing changes and the caller gets the processor's own message; on success the response carries the updated gateway, including the currencies and payment methods it now offers, re-read from the processor.
A gateway still in setup becomes CREATED, or LINKED when checkout routing already points at it. A gateway that is already live keeps its status.
The checkout offers what the saved gateway now supports, from the next payment onwards; payments already taken are untouched.
GATEWAY.UPDATE reaches the instance's webhook subscribers. A save that changed nothing raises nothing, and workflows raise no event at all.
Merchant Setup returns to the provider list; a form that asked for an apply step stays open for the second save instead.

Who can do this

Roles: Admin only. Support holds neither payment_gateway nor payment_workflow, and provider setup is Admin by intent.
Permission keys (for clients managing permissions directly): payment_gateway (or *) on the gateway, checked by Shuttle; without it the caller gets UNAUTHORIZED (401), "Unauthorized". For a workflow, payment_workflow (or *) on the division named in the body, falling back to the client, checked by Shuttle; without it UNAUTHORIZED (401), "Missing required permissions". Merchant Setup gates Save on holding payment_gateway on any object, for workflows as well as gateways: a session holding payment_workflow but not payment_gateway is shown a read-only workflow form the server would have let it save, and a session holding payment_gateway on one gateway only is offered Save on every gateway and refused by the server.
Without the permission Merchant Setup disables the settings form and replaces Save with a read-only message.
Archived records are read-only in Merchant Setup: the form is disabled, so Save never appears.
Single-provider deep links lock the app to one gateway and put this form and the checkout customisation on the same page; the save here behaves the same either way.