Change the payment method on a contract

Points a contract's future collections at a different saved payment method, and where the contract is in arrears brings the next collection forward so the new method is tried straight away. No money moves inside the request. It is used by support staff when a customer's card has failed or expired, and by the customer from the hosted checkout or portal. There are two server paths: an explicit contract update carrying payment_method, and a tokenisation that names the contracts the new method should be attached to.

Where you can do this

Merchant View: Contract (Change Payment Method)
Merchant View: Paid by (Change Payment Method)
The hosted checkout: Payment form (Confirm (confirm page, TOKENISE, checkout request names contracts))
API: Update a contract (PUT /contracts/{contract_id}) — body carries payment_method (optionally next_payment)
API: Create a checkout (POST /checkouts) — action TOKENISE with contracts[] naming the contract; sets up the selection, the change itself is the PUT above or the tokenise below
The hosted checkout: the hosted checkout submits in TOKENISE mode with contracts[] in the request; forwarded as POST /c/api/payment_methods with contracts
API: Create a payment method (POST /payment_methods) — body carries contracts[] (the attach happens inside payment.tokenise)
Automatically (Shuttle): payment method save (fingerprint relink) — a method becomes ACTIVE within a minute of a successful transaction and matches an existing ACTIVE, SINGLEUSE or EXPIRED method of the same account, gateway, card type and fingerprint: the old method is archived and its active contracts are repointed to the new one

Before you start

The contract is an ongoing (recurring, variable-amount or scheduled) agreement that is not completed, cancelled, cancelling or failed. Setup and suspended contracts are accepted by the server; Merchant View does not offer them.
The new payment method exists and belongs to the contract's account.
Via tokenisation, the new method must reach ACTIVE (a redirect-based method is parked until the gateway confirms it).

Inputs

Input	Required	Meaning and constraints
payment_method	yes (update path)	Id of a saved payment method on the same account (`pm_` prefix accepted). The same id as the contract already carries is a no-op. Cannot be cleared through this route.
next_payment	no (update path)	Overrides the retry-now date the change would otherwise set; the literal `now` is accepted. Constraints are those of Reschedule the next payment.
contracts	yes (tokenise path)	Ids of the contracts the new method is attached to once it is active.
checkout: action, contracts, account, currency, legal_entity, source	yes (admin path)	Merchant View sends `action` TOKENISE, the contract's account, currency and legal entity, `source` MOTO and `contracts` with the one contract; the hosted checkout carries `contracts` through to the tokenise request.

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 payment method must belong to the contract's account; Shuttle does not re-check ownership on the update path, only Shuttle does	The API	VALIDATION_ERROR: "Invalid payment_method"
The payment method must exist	The API	not found error surfaced from Shuttle
A completed, cancelled, cancelling or failed contract cannot take a new method through the update path; a non-ongoing contract type is refused	The API	INVALID: "Invalid value for field contract (status … is not editable)." / "Invalid value for field contract (type … does not support scheduled charge edits)."
A one-off contract cannot be updated	The API	VALIDATION_ERROR: "cannot update non-recurring contracts"
The payment method cannot change as part of a resume	The API	VALIDATION_ERROR: "Cannot change payment_method on resume"
A status change cannot be combined with a payment method change in one Shuttle request (reachable only with `bypass_validation` and a target status)	The API	INVALID (BOLT-7086): "newStatus cannot be combined with other contract edit fields"
Attaching an ACTIVE method that does not expire before the next charge to an ongoing contract in FAILING or ERROR promotes it to ACTIVE; a method that expires first leaves the status alone	The API	status change as stated, otherwise silent
Clearing the method on an ACTIVE contract puts it into FAILING; only the legacy Shuttle routes can clear it, the `/c/api` update never sends an empty method	The API	status change as stated
A method that is expired today, archived, inactive, failed or single-use gives no retry date; the path is still rewritten to it	The API	silent
The retry-now date is set only when the contract is an ongoing type in progress with an outstanding amount, its retries are not exhausted under the client's retry schedule (counted from the last failed or not-attempted transaction), and cancelling retries was not requested; on an ongoing-scheduled contract the date is the earliest collectable date for the next unpaid charge after the method's advance notice, and a future date already set on an overdue contract is kept	The API	silent
After the change, the save clears the next payment date again if the contract is in ERROR, COMPLETE, CANCELLED, FAILED or SUSPENDED, has an unattributed amount, a zero amount or nothing outstanding	The API	silent; no collection is scheduled
Via tokenisation: the attach runs only once the new method is ACTIVE; a redirect-based method parks the contract ids on the method and attaches them when the gateway reports the token (a SETUP contract then becomes ACTIVE); a method the gateway rejects becomes INACTIVE and the contracts are untouched	The API	contracts unchanged until then
Via tokenisation: an amended or replaced contract resolves to its live successor before it is updated (also on the legacy routes)	The API	silent
Via tokenisation: no per-permission check beyond the account session match; gateway support for saving cards and the one-tokenisation-per-session lock are rules of Save a payment method without charging it	The API	see Save a payment method without charging it
After a successful tokenise the hosted checkout reports the selection to Merchant View, which repeats the change as an update; the server treats a matching id as a no-op. After a redirect-based tokenise no message reaches Merchant View; the screen picks up the change through Shuttle's object-update stream, which the contract view subscribes to	Merchant View screen	no error; the contract refreshes when the update event arrives

What happens

The contract's future collections are taken from the new payment method. On the update path the response carries the updated contract; on the tokenise path it carries the new payment method, and the named contracts are attached once that method is ACTIVE (a redirect-based method attaches them when the gateway confirms it; a rejected method leaves the contracts unchanged).
Where the contract is in arrears and retries remain, the next collection is brought forward (normally at once) and the outstanding amount is tried on the new method; next_payment overrides that date. Success clears the failing state, failure follows the normal retry schedule.
A contract in FAILING or ERROR returns to ACTIVE when the new method is ACTIVE and does not expire before the next charge.
Sending the id the contract already carries changes nothing and returns OK.
CONTRACT.UPDATE is raised for the contract unless it is still in SETUP; webhook subscribers receive it.
Later, if the new method turns out to be the same card as an existing saved method after a successful payment, the old method is archived and any other active contracts on it move to the new one, each raising its own CONTRACT.UPDATE.

Who can do this

Roles: Admin only today; intended for Support as well, and being aligned. From the hosted checkout, no operator role applies.
Admin app: the control needs the payment_method_edit dashboard option (also settable through a deep link's features) and the payment_transaction permission, applies to the admin entry points only.
Permission keys (for clients managing permissions directly): agreement, payment_contract or * on the client or the contract's division for the account, checked by Shuttle on the update path; a customer account session is accepted for its own account.