Restrict a payment method by transaction amount
Limits when a payment method is offered to online customers by transaction amount: a minimum and a maximum per currency, or a currency in which the method is not offered at all. The limits are held on the legal entity route under the ECOMMERCE source. The checkout receives them with its configuration and hides the method before the customer can choose it; Shuttle checks them again when the payment is submitted. A merchant uses this to keep, say, bank debit off small baskets, or to stop offering cards in a currency they no longer settle.
Where you can do this
- Merchant Setup: Payment method amount rules (Save)
Before you start
- The route exists, is not archived, and carries at least one payment method type.
- The route is LINKED or ACTIVE. Merchant Setup offers the rules control only for those; a run-down route can still be addressed by the API, where the change is dropped (see Rules).
- The gateway the route points at is connected and offers the method.
- No feature option gates this; any route can carry rules.
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 | The API | VALIDATION_ERROR "API body error: missing legal_entity_route object" |
| The route must exist | The API | 404 NOT_FOUND "legal_entity_route not found"; Shuttle's own check answers NOT_FOUND "apiValidation.error.not.found" naming "legal_entity_curr" and the key |
| A rules object with no source key is stored under ECOMMERCE; one that already names a source is stored as sent | The API | accepted as sent |
| Only the ECOMMERCE block is ever read. A MOTO, POS or RECURRING block is stored and returned but never applied at checkout or at payment | The API | accepted as sent, no effect |
| The rule shape is not validated: an unknown currency code, a misspelled key or an extra sub-key is stored and simply never matches a payment | The API | accepted as sent, no effect |
| The rules sent replace the route's whole rule set; there is no partial update. Send the complete ECOMMERCE block, including any limits you want to keep | The API | limits not resent are lost |
| currencies and payment_method_types inside the ECOMMERCE block are where the route's own lists live, so sending them changes which currencies and methods the route serves. The same two fields sent at the top level of the body are ignored | The API | route lists replaced |
| A payment whose amount is below the minimum or above the maximum for its currency (a maximum of 0 rejects every amount) is refused when it is submitted; the full submission rule set is on Take a one-off payment | The API, mirrored by the hosted checkout | BOLT-7109 (minimum) / BOLT-7110 (maximum) |
| Saving a payment method without charging it is not checked against the amount limits, because it does not go through payment submission; on a disallowed currency only the checkout's hiding stops it | The API | method offered unless the checkout hides it, see Save a payment method without charging it |
| An existing contract's scheduled collections are never re-checked against the limits: only a fresh checkout or payment submission is | The API | limits do not apply |
| Only ACTIVE and LINKED routes contribute rules to the checkout configuration; a run-down route's stored limits are ignored there, though it still contributes its currencies and methods so saved cards keep working | The API | limits not applied at checkout |
| The checkout applies the limits only in a customer-present session (source ECOMMERCE or POS); a MOTO session is offered the method and refused at submission. Stated with the rest of the submission rules on Take a one-off payment | The hosted checkout | method offered, then BOLT-7109 / BOLT-7110 |
| When any live route on the channel carries amount limits, the checkout asks for the amount before it works out which methods to offer; a tokenise-only checkout does not | The hosted checkout | amount field shown and required |
| Which currencies Merchant Setup offers is fixed for some methods: ACH to USD, SEPA to EUR, BACS to GBP; otherwise the gateway's currencies, or every ISO code when the gateway lists none. Not enforced server-side | Merchant Setup screen | currency not offered |
| A maximum must be greater than the minimum, a maximum typed as 0 is refused (0 is reserved for the disallow switch), and both must be numeric. Not enforced server-side | Merchant Setup screen | validation message above the buttons, Save blocked |
| A currency can only be disallowed on a route whose gateway serves more than one currency; the single-currency form has no disallow switch, so disallowing the only currency needs the API | Merchant Setup screen | control not offered |
| Turning the restriction switch off removes every limit for the method; the currencies and methods the route serves are left alone | Merchant Setup screen, the API | rules.ECOMMERCE.amount removed |
| Saving rules identical to the stored ones is skipped entirely: no version change, no webhook, no re-index | The API | 200, nothing happens |
What happens
- The method's limits become whatever was sent, replacing what was there. New checkouts pick them up at once; the checkout customisation screen marks the method as having a rule applied.
- In a customer-present checkout the method disappears for any amount outside the limits, and for a currency whose maximum is 0 it is never offered at all. A customer who reaches submission anyway (a phone order, or an amount changed after the method was chosen) is refused with the route-rule error and has to pick another method.
- Sending currencies or payment_method_types inside the rules changes which currencies and methods the route serves, not just its limits.
LEGAL_ENTITY_ROUTE.UPDATEis raised for the route, and separately for every sibling route the update copies the rules onto.- Saving a card for the customer is unaffected, and so are contracts already running: their collections are not measured against the limits.
- An identical save does nothing at all, so a Save that changed nothing raises no webhook and leaves the route untouched.
Who can do this
- Roles: Admin only. Routing and provider setup are Admin work by design, so Support is not intended to have it.
- Permission keys (for clients managing permissions directly): Shuttle does check the session's team permissions on a route save,
legal_entity_curr(or*) on both the legal entity and the gateway, and swallows a refusal rather than reporting it: see Route a payment method to a provider. Merchant Setup is the only gate: it requirespayment_gatewayand otherwise shows the form read-only with "Changes cannot be saved in read only mode". Support does not hold that key. - No feature option applies. The screen is reached from the checkout customisation screen's payment method row, and only for a method that is switched on and whose route is LINKED or ACTIVE.
Related
Updated about 3 hours ago
Did this page help you?