Set the merchant name and country

Records the legal merchant name the customer should see at checkout and the country the merchant account is held in. Both are passed to the wallet providers: the name to Apple Pay, Google Pay and Click to Pay, the country to Google Pay as the transaction country and to Click to Pay as the registration country. It is saved as part of Merchant Setup's checkout customisation, which will not save either field without the other once a wallet payment method is enabled; the API requires neither.

Where you can do this

Merchant Setup: Your integrations (Customise Checkout)
Merchant Setup: Managing a connection (Customise Checkout (single-provider mode))
Merchant Setup: Your integrations (Save)

Before you start

The instance exists. merchant_country can only be set on an update, never while an instance is being created.
Merchant Setup shows the two fields only when network tokenization is on for the instance and a wallet payment method (Apple Pay, Google Pay or Click to Pay) is already routed or is being enabled in the same save; see Enable wallet support for the instance.
For the name to reach Apple Pay on save, the instance has Apple Pay registration on (applepay_direct) and at least one of its checkout domains is not yet verified with Apple.
For the name or country to reach Click to Pay on save, the instance has connected processors and its capabilities include at least one of Mastercard, Visa, Discover or American Express.

Inputs

The body is { "instance": {... } }.

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 an `instance` object	The API	VALIDATION_ERROR: "API body error: missing instance object"
merchant_country must be an assigned ISO 3166-1 alpha-2 code, or `XX`, or empty. User-assigned ranges (XA-XZ, QM-QZ, ZZ) are rejected so a bad code fails here rather than as an opaque wallet rejection later	The API	VALIDATION_ERROR: "invalid merchant_country (it must be a two-letter ISO 3166-1 alpha-2 country code)"
merchant_country cannot be set while an instance is being created; the create path does not carry it through	The API	VALIDATION_ERROR: "merchant_country cannot be set when creating an instance - set it with a PUT once the instance exists"
Both fields are optional server-side. Once network tokenization is on and a wallet payment method is enabled, Merchant Setup disables Save until both are set. By design: Apple Pay and Google Pay will not render without them, so the screen insists on them at the moment the merchant turns those methods on. Through the API they may be left unset.	Not the API; Merchant Setup screen refuses it	Save disabled, with the name shown in red as required
The name registered with Click to Pay is not the stored one: characters outside letters, digits, spaces and `- & '., # @ _` are stripped, runs of whitespace collapsed and the result cut to 60 characters. The stored merchant_name is left as sent	The API	the name the customer sees in Click to Pay differs from merchant_name
Google Pay takes merchant_country as the transaction country. When it is not set the checkout falls back to the customer's billing country and then the CRM country; the instance's own `country` is never used for Google Pay	The API	none; Google Pay is sent the customer's country instead of the merchant's
Click to Pay registration uses merchant_country, falling back to the instance's `country` when that is not `XX`, and to `GB` when neither is set	The API	none; the registration is made in GB
Apple Pay domain registration sends merchant_name, or the instance name when merchant_name is empty. The Apple Pay payment sheet's display name is merchant_name with no fallback	The API	the merchant session is sent with no display name
A failure registering with Apple or with Mastercard does not fail the save: the instance is saved and 200 returned. Apple Pay records a per-domain registration error on the instance; a Click to Pay failure while a registration is already active leaves the previous one in place	The API	200, with the error recorded on the instance rather than in the response

What happens

The instance stores the new merchant_name and the trimmed, upper-cased merchant_country, and the updated instance is returned; a later read reports both back. Instances can be found by merchant name in a search; merchant_country is not indexed.
Customers see the new name the next time the hosted checkout loads: it is the name in the Google Pay payment sheet, the display name on the Apple Pay sheet, and the name shown by Click to Pay. Google Pay sends the new merchant_country as the transaction country. A checkout already open keeps the old values.
An INSTANCE.UPDATE webhook is raised for the instance. No status changes, and no email or SMS is sent.
Changing the name while Click to Pay is registered replaces that registration: Mastercard cannot rename one, so a new registration is created and the old deleted once the new one succeeds. If it fails, the previous registration stays and the checkout keeps showing the old name.
Apple Pay is re-registered only when the instance has Apple Pay on and at least one checkout domain is still unverified. A name change on an instance whose domains are all verified does not re-register, so Apple keeps the name it was given; saving from Merchant Setup covers this by re-saving the Apple Pay route afterwards.
A change to either field queues a re-save of every active payment gateway on the instance. Nothing the operator can see changes as a result.

Who can do this

Roles: Admin only. Instance settings are an Admin action by intent.
Setup app: Save is offered only to a session holding payment_gateway; without it the row renders as read-only. The name and country editor itself is not gated, so a session without the key can open it and type but has no way to save.
The fields are offered only once network tokenization is on for the instance and a wallet payment method is enabled; see Enable wallet support for the instance for the platform option behind that.