## Problem Two surfaces tell a reader something the code stopped doing. ### The account form says the machine name is what a payment records `PaymentAccountForm`, on the machine name element an operator reads while creating an account: ```php '#description' => new TranslatableMarkup('Recorded on every payment this account takes, and fixed once saved.'), ``` A payment records `account_uuid`. `Payment::baseFieldDefinitions()` says so, and says why: "A uuid rather than the name the account was given, because a payment is read on the site that took it and on any site it was taken for, and only the uuid means the same thing on both." `PaymentWire::VERSION` moved to 3 for that change. `Entity\PaymentAccount::$id` carries the same sentence as a docblock: "The machine name, which is what a payment records." The reason the element is `'#disabled' => !$account->isNew()` is also not the one given: a config entity's id is fixed because it is a config entity's id. What a payment names, and therefore what must never be reused, is the uuid, which the form does not show at all — the accounts listing is where a uuid becomes a name again, and it is the only place. ### The bundled gateway types against the half the guide says not to use `docs/gateways.md` has a section for this, titled *Why the signatures say `Entity`*: > Every payment and movement a gateway is handed is typed `PaymentEntityInterface`, `ClaimEntityInterface`, `RefundEntityInterface` or `ReversalEntityInterface`, and that is deliberate rather than decoration. A gateway is handed a record so it can write to it. […] **Type against the `Entity` ones**, and a method a consumer would reach for is on the plain one. `ManualGateway` types all five of its methods against the plain ones: ```php public function createPaymentSession(PaymentInterface $payment): ?PaymentSession public function refund(PaymentInterface $payment, RefundInterface $refund): void public function authorize(PaymentInterface $payment): void public function capture(PaymentInterface $payment, ClaimInterface $claim): void public function cancel(PaymentInterface $payment, ReversalInterface $reversal): void ``` It compiles, because a parameter type may be widened. `SimulatorGateway`, the other bundled one, types against the `Entity` interfaces throughout. ## What it costs The first is an operator told, on the form where the decision is made, that the value they are typing is the one their payments will name. It is translated, so it is wrong in French too. The second is a gateway author. `docs/gateways.md` sends them to `ManualGateway` twice — for what NULL means from `createPaymentSession()`, and for claiming a capability deliberately — so it is the bundled implementation they read. Copying its signatures gives them a `$claim` they cannot call `setReference()` on, which is the one thing the guide says the `Entity` types are there for, and the error arrives later and somewhere else. ## Proposed - The form element says what is actually true of it, and the uuid is named as what a payment records. - `PaymentAccount::$id`'s docblock the same. - `ManualGateway` types against the `Entity` interfaces, as every other gateway here does. - A test holds every bundled gateway's signatures against the interfaces they implement, so the next one cannot drift the same way. Three stale sentences on the contract go with them, all left by the same rename: `PaymentClientInterface::create()` still says it refuses "a gateway this site does not have an enabled account at" and keys reuse on "the gateway, currency and amount"; `getAvailableAccounts()` says its keys are "the id to pass as `$account`", and there is no `$account` parameter; and `PaymentInterface::getMetadata()` says the values are "as given to create() **or set since**", while metadata is written once and never after. AI-Generated: Yes (Claude Code was used to help draft this issue summary and to write the change and its tests.)