Enable wallet support for the instance
Switches wallet support on or off for the merchant by adding or removing ENABLE_WALLETS from the instance's features. Server-side the flag does exactly one thing: it decides whether the hosted checkout is given the Apple Pay and Google Pay code it needs to draw those buttons. It does not enable a wallet on its own — a wallet payment method still has to be routed to a gateway that can process a network token — and it does not gate Click to Pay, which the checkout serves from the merchant's own Click to Pay registration instead. In Merchant Setup it is the switch that unlocks the wallet payment methods on the checkout customisation panel, and it saves the moment it is flipped.
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 (Enable Apple Pay / Google Pay support)
Before you start
- The instance exists. Nothing about its state has to be true first: the flag can be set before any provider is connected and before any wallet method is routed.
- For buttons to appear at the checkout the instance also needs a wallet payment method routed to a gateway that can process a network token (Route a payment method to a provider). The flag on its own shows nothing.
- Merchant Setup offers the switch only when the platform application carries the enable_wallets feature and at least one connected gateway serving CARDS declares network token support on one of its payment methods. The server checks neither.
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" |
| features must be an array | The API | VALIDATION_ERROR: "invalid features (it must be an array)" |
| The strings inside features are not checked against any list: an unrecognised value is stored, read back and does nothing | The API | accepted as sent |
| features replaces the stored list in full. A caller sending only ENABLE_WALLETS drops every other feature the instance had; Merchant Setup always sends the current list plus or minus the one value | The API | the other features are silently lost |
| Shuttle compares the version the API itself read at the start of the save, not the one the caller sent, so only another instance edit landing inside that window is refused rather than overwritten | The API | INVALID: "validations.concurrency.other.user" |
| ENABLE_WALLETS gates one thing and one thing only: whether the hosted checkout is served the Apple Pay and Google Pay code. Nothing else server-side reads it | The API | without it the checkout receives an empty response for both wallets and draws no buttons |
| Click to Pay is not gated by the flag. The checkout offers it whenever the instance has an active Click to Pay registration and the routed gateway can take a raw card number and process a network token. ENABLE_WALLETS_BETA has no server-side meaning anywhere | The API and the hosted checkout | Click to Pay is unaffected by the switch |
| Routing a wallet method does not require the flag: an Apple Pay or Google Pay route saved against a network-token gateway marks the instance for direct Apple Pay and registers its checkout domains with Apple whether or not wallets are enabled (not enforced server-side; Merchant Setup only lists wallet methods when the flag is set) | The API and Merchant Setup screen | the route is created and the domains registered |
| The platform application must carry the enable_wallets feature before the switch is offered. The feature is set in the developer portal and has no server-side effect at all | Merchant Setup screen | switch hidden |
| A connected gateway serving CARDS must declare a network token feature on one of its payment methods before the switch is offered; not enforced server-side | Merchant Setup screen | switch hidden |
| Google Pay on a gateway that takes a raw card number and can authenticate it is deliberately held back in Merchant Setup until the checkout and Shuttle halves ship, so all three wallets stand or fall on the same network token test | Merchant Setup screen | Google Pay not offered on such a gateway |
| Merchant Setup hides the switch once wallets are enabled, so wallets can only be turned off again through the API | Merchant Setup screen | switch not shown |
What happens
- With ENABLE_WALLETS set, the Apple Pay and Google Pay buttons appear at the checkout for any wallet method already routed to a gateway; without it they never render, whatever routes exist. A checkout opened within about a minute of the change may still behave as it did before.
- The instance's features become exactly the list sent, and the call answers with the whole instance as stored, features included.
- INSTANCE.UPDATE is raised for the instance.
- Turning wallets off changes nothing else: wallet routes stay in place, Apple Pay domain registrations stay registered, and the merchant name and country are untouched. Only the buttons stop.
- The same call can register the merchant for Click to Pay as a side effect. An instance that has a connected provider and a merchant name but no active Click to Pay registration is onboarded on any instance update, this one included, and the operator will see a Click to Pay registration appear that they did not ask for here.
- An instance already set up for Apple Pay may have its checkout domains re-registered with Apple, and domains that have dropped off the list withdrawn, on the same call.
Who can do this
- Roles: Admin only.
- Platform option: the application feature enable_wallets, set in the developer portal's gateway setup settings, because Apple Pay and Google Pay need the platform's checkout domains registered and certified. It only decides whether Merchant Setup offers the switch.
- Instance option: ENABLE_WALLETS_BETA, a second value carried in the same features list. Only Merchant Setup reads it, to decide whether to offer Click to Pay as a routable method; no screen sets it, so it arrives through the API.
Related
Updated 1 day ago
Did this page help you?