## Problem/Motivation Two problems in one surface, which is why they are one issue: the same column, the same getters and the same consumers are touched by both, and doing them separately means migrating `kessai_payment.gateway` twice and sweeping orchestra and yoyaku twice. ### It is called a gateway and it is an account A gateway is a plugin - a provider integration. A payment account is a contract at that provider, and it is what a payment is taken against, what a consumer names when it asks for one, and what `PaymentEngine::loadGateway()` loads. The word predates payment accounts existing. So `kessai_payment.gateway`, `PaymentInterface::getGateway()`, `PaymentRequest::$gateway`, `PaymentQuery::$gateway`, `getAvailableGateways()` and `isGatewayAvailable()` all say gateway and all mean account - while `PaymentGatewayInterface`, `PaymentGatewayBase` and `plugin.manager.kessai_payment_gateway` say gateway and mean it. One word, two meanings, and no way to tell which is meant without checking. Counted on 1.x: 113 references outside tests here, 10 test files, and the consuming projects carry their own in code and in stored configuration. ### It is named by a word that means something different on each site A consumer names an account when it asks for a payment: `create(new PaymentRequest(gateway: 'worldline', ...))`. On a site with an engine that word is a `kessai_payment_account` id. On a site taking its payments through a Kessai elsewhere it is a `kessai_client` remote id. The same stored configuration works on both only if a person gave the two things the same machine name. Nothing enforces that and nothing notices when it drifts, so an orchestra workflow or a yoyaku policy exported from one site to another can silently name an account that does not exist, or one that does and is the wrong contract at the provider. The account already has an identifier that means the same thing on both sides. `kessai_payment_account` is a config entity, so it has a uuid, and `kessai_client`'s remote records that uuid when it shakes hands. It is simply not what anything stores. ## Proposed resolution **Call it an account, and name it by uuid.** `getAvailableAccounts()` keeps the shape `getAvailableGateways()` had, `array<string, string>`, and changes what the key means: the uuid rather than the id. The value stays the label, and comes from whichever side answers - the payment account's label on a site with an engine, the remote's label on a site with a client. A select goes on showing a name a person recognizes and goes on storing one value; that value now means the same thing wherever the configuration is used. `PaymentRequest::$account` carries the uuid, and both implementations resolve it: the engine loads the account by uuid, the client finds the remote whose recorded account uuid matches. Resolving a uuid is an indexed lookup rather than a scan - `ConfigEntityType` appends `uuid` to its lookup keys and `Query::loadRecords()` resolves an `=` or `IN` condition on one through the key store. A listing still wants the accounts preloaded once and keyed by uuid in PHP, because a query per row is a query per row, but the reference itself costs a key-value read and a cached config load. ## What shipped - The reading contract answers `getAccountUuid()`, and the values it takes are `$accountUuid` on `PaymentRequest` and `PaymentQuery` and `$account_uuid` on the two token doors. Anything that hands you the uuid, or holds it, says uuid; what is the account rather than its identifier keeps the plain word, so `getAvailableAccounts()` still answers accounts and the consumer's `kessai_account` field still names one. - `getAvailableGateways()` and `isGatewayAvailable()` are `getAvailableAccounts()` and `isAccountAvailable()`, both keyed by and taking a uuid. - `PaymentAccountStorage::loadByUuid()` is the way back from a uuid, answered from the config key store rather than by a scan. - `PaymentEngine::loadGateway()` is `loadAccountGateway()`: it resolves a payment's account and hands back that account's gateway plugin, and the old name invited the guess. The gateway plugin type keeps its name throughout, being the one thing here that really is a gateway. - `AccountOptions` is the one rule for what an account select offers: the accounts on offer plus the one that form already stored, because an account is retired by being disabled and a select posts what it displayed. - The accounts listing carries the uuid beside the machine name, because the uuid is what a payment, a log line and a retired step's option all name an account by, and this is the only place it becomes a name again. - A refusal names the account the way its owner named it wherever the account is in hand; where it has gone, the uuid is all there is. - The handshake refuses a consumer whose account has been retired, which is what that door is for. - `PaymentWire::VERSION` is 3. `account` is gone from the wire and `account_uuid` carries it: the two were the same value once the column held a uuid, and a removal moves the version. ## User interface changes A select that showed labels and stored machine names shows the same labels and stores uuids, so nothing an operator chooses looks different. Two screens do change. The payment accounts listing gains a **Uuid** column, which is what makes a uuid anybody meets traceable back to an account. On a site running `kessai_server`, the account a consumer is pointed at is chosen from a list rather than typed, because a uuid is not a value to copy by hand. ## API changes Renamed on `@api` surfaces, all pre-1.0 and all named here because every consumer is affected: `PaymentInterface::getGateway()` to `getAccountUuid()`; `PaymentRequest::$gateway` and `PaymentQuery::$gateway` to `$accountUuid`; `getAvailableGateways()` and `isGatewayAvailable()` to `getAvailableAccounts()` and `isAccountAvailable()`; and the third argument of `authorizeToken()` and `chargeToken()` to `$account_uuid`, which matters because a named argument binds to it. What those answer and take changes with the name: an account is addressed by uuid throughout, so `getAvailableAccounts()` is keyed by one. `Drupal\kessai\AccountOptions` is new and `@api`. ## Data model changes `kessai_payment.gateway` becomes `kessai_payment.account_uuid` and holds the uuid of a payment account rather than the name a site gave it. No migration, and none is wanted: kessai is pre-1.0 alpha, so a site reinstalls rather than carrying an upgrade path that will never be used again. The stored configuration that names an account moves with it, in the merge requests of the projects that own it: orchestra [#3623411](https://www.drupal.org/project/orchestra/issues/3623411) and yoyaku [#3623412](https://www.drupal.org/project/yoyaku/issues/3623412). All three land in the same deploy, because the renamed methods are deleted rather than aliased. AI-Generated: Yes (Claude Code was used to help draft this issue summary.)