Route a payment method to a provider
Makes a payment method (cards, ACH, SEPA, a wallet, and so on) available at checkout for a legal entity through a chosen payment gateway, optionally with fraud workflows attached. A legal entity route is the record that says "this method, in these currencies, goes to this gateway". Creating one is a conflict-aware operation: whatever route served the method before is archived, run down or left alone according to the conflict mode, and the currencies and methods it still needs to cover are split off into routes of their own. Changing the gateway or the workflows on an existing route is a plain edit with no conflict handling at all.
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 legal entity exists.
- The gateway exists and is connected. Merchant Setup only offers gateways whose own payment method list includes the method; for a wallet it offers only a gateway that also supports CARDS and declares a network token feature.
- A wallet method is only listed at all once the instance and the platform application have wallets switched on (see Enable wallet support for the instance); Click to Pay is additionally listed only when the instance carries ENABLE_WALLETS_BETA, which is Merchant Setup's own rule and not a server one; see Enable wallet support for the instance.
- On update, the route exists and is not already in RUNDOWN.
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 legal_entity_route object naming legal_entity, and gateway must be present (it may be null) | The API | VALIDATION_ERROR: "API body error: missing legal_entity_route object", "legal_entity required", "gateway required" |
| The legal entity must exist | The API | INVALID, Shuttle error BOLT-7082 (object not found) |
| On update the route must exist | The API | NOT_FOUND "legal_entity_route not found"; apiValidation.error.not.found "legal_entity_curr |
| Shuttle's own create validation (a gateway must be named; without rules, currencies and payment methods are mandatory unless the gateway is UNSUPPORTED) cannot be reached through this API: Shuttle always sends a gateway key, defaulting to UNSUPPORTED, and always sends a rules object | The API | not reachable; apiValidation.error.mandatory "paymentGateway" / "currencies" / "paymentMethods" and error.company.link.fields.notempty apply only to direct Shuttle callers |
| gateway sent as null means UNSUPPORTED: the routes clashing with the request are archived or run down and no route is created in their place | The API | the method stops being offered; see Stop offering a payment method |
| Creating with no conflict_mode archives the clashing route (INACTIVE); RUNDOWN sets it to RUNDOWN so it keeps serving saved cards and contracts; RETAIN leaves it active | The API | see Effects |
| The currencies and methods of a clashing route that the request does not cover are split into new routes on the old gateway, so nothing silently stops being offered. remove_conflicts skips the split | The API | see Effects |
| A new route is merged into an existing active route of the same gateway that has exactly the same currencies (the method is added to it) or exactly the same methods (the currency is added to it), instead of a second route being created | The API | the existing route is updated, not replaced |
| Naming a single card brand, or omitting payment_method_types, gives a CARDS route; and when the gateway's card methods carry network tokens, APPLEPAY and GOOGLEPAY routes are created for it in the same call. Naming CARDS explicitly adds no wallet routes | The API | extra routes created, or not, depending on how the method was named |
| The server does not check that the gateway supports the method named; Merchant Setup only offers gateways whose method list includes it | Merchant Setup screen | control not offered |
| Workflow ids are not checked. An id that names nothing, or an archived workflow, is stored and then skipped both when the checkout is configured and when a payment runs | The API | accepted as sent, never runs |
| An update writes the gateway, the workflows and the rules and nothing else: a legal_entity, currencies or payment_method_types sent with it is accepted and dropped, because the route edit reads none of them, and the route's stored rules are resent when the body carries none | The API | accepted as sent, no effect |
| A division sent on a route is dropped: it is not forwarded, the stored route has no division field and no route returns one, so the division Merchant Setup sends on every save changes nothing. It is the gateway that carries a division (Connect a payment processor), and the gateway's and the legal entity's team permissions that scope the route | The API | accepted as sent, no effect |
What happens
- The method is offered at the checkout through the chosen gateway from the next checkout the customer opens, and payments taken through it run the fraud workflows named on the route.
- Creating a route answers with every route the call changed, not only the new one: the new route at LINKED, whatever happened to the route that served the method before, and any route split off to keep that route's other currencies and methods covered.
- The route that served the method before is archived, left serving only saved cards and contracts, or left fully active, according to conflict_mode. When the new route can save cards, a fallback route is added for the new gateway so cards saved to it keep working after a later change.
- The legal entity and the gateway show as LINKED once a route exists for them.
- Saving an Apple Pay or a Google Pay route registers the merchant's checkout domains with Apple and switches Apple Pay on for the instance. If a domain is not serving Apple's verification file the save still succeeds and only the customer's Apple Pay tap fails, so the domain is worth checking after the first wallet route.
- Updating a route replaces its gateway and workflows and nothing else: no route is run down, no fallback is created, and saved cards on the old gateway are left without a route.
Who can do this
- Roles: Admin only.
- Permission keys (for clients managing permissions directly): Shuttle checks the session's team permissions when it saves the route:
legal_entity_curr(or*) on both the legal entity and the gateway, which the gateway's own permission row carries (see Connect a payment processor). A session without them is refused inside the save, but the refusal is swallowed: a create answers HTTP 304 NOT_MODIFIED "No routes modified" and an update answers INVALID carrying Shuttle error BOLT-7031, instead of NO_PERMISSION. Merchant Setup gates Save onpayment_gateway, which no Support role holds, and shows the section read-only without it. - Wallet routes can be created whatever the wallet settings say: the instance feature and the platform application feature gate the checkout code that offers Apple Pay and Google Pay, and Merchant Setup's listing, not this function (see Enable wallet support for the instance).
- Single-provider mode: reached by a deep link to one gateway, it offers only that gateway and makes Merchant Setup send conflict_mode RETAIN instead of RUNDOWN.
Related
Updated 14 minutes ago
Did this page help you?