Android Migrate Payment Method V6

android-migrate-payment-method-v6

Migrate a v5 payment method to the v6 architecture. This skill gives the order of work and the rules that are easy to miss. The shape of the code comes from the payment methods that are already migrated, which are always more current than any description here — read them rather than relying on this file for names or signatures.

Usage

Invoke this skill when migrating an existing v5 payment method (e.g. ideal, sepa, twint) to v6. The input is the payment method / module name. The skill is method-agnostic: every payment method differs, so treat the steps as a checklist to adapt, not a rigid template.

Throughout this skill, X stands for the payment method (e.g. Ideal), and x/module for its module.

Find your references

No single migrated method covers every capability, and the set of migrated methods keeps growing. Find them before planning: every v6 payment method registers its factory with PaymentMethodProvider.register from an initializer, so searching for that call lists them all.

For each capability your method needs — no input fields, input fields, a stored variant, a secondary screen, an external SDK handoff — pick the closest migrated method and read it end to end, tests included. Match what it does rather than inventing a second way of doing the same thing.

For methods with input fields, also read the form state ADR under ADR/. It records how forms are modelled and why; the migrated form components show how it is done today.

The v6 target architecture

Each v6 payment method is a small set of collaborators wired by a factory:

Before you start

1. Read AGENTS.md. This skill defers to it for the working agreement and testing rules, and to the skills it routes to: android-public-api-change (visibility, sealed vs abstract), android-ui-resources (styles and strings), and android-add-module (external SDK handling).
2. Create a plan document first. Per AGENTS.md, write <METHOD>_V6_MIGRATION_PLAN.md, get it approved, and do not start coding until then. Keep it updated as phases complete. Do not commit the plan file.
3. Inventory the v5 sources. List the existing v5 files (delegate, views, provider, configuration, tests) and map each onto the v6 collaborators above. Note what already exists — some methods are partially migrated — so you don't recreate it.
4. Flag method-specific concerns in the plan: external SDK handoff (compileOnly + runCompileOnly/checkCompileOnly + ProGuard dontwarn), availability pre-checks, action/redirect handling, and any events that originate outside composition and have to reach the UI. Also decide which optional capabilities apply: params/mapper, input fields, a stored variant, a secondary screen.
5. Invoke architecture-guardian when a phase introduces or changes public API, new abstractions, or module boundaries.
6. Agree the commit/PR cadence with the developer. Commits stay small (one per phase), but PRs need not map 1:1 to commits. Decide upfront whether to open a PR per phase or — the default — per cohesive group of phases (e.g. old/ move; state + view-state + view; component + factory + registration). Cadence is a reviewer preference, so confirm it during planning.

Working rhythm (applies to every step)

Follow this loop for each phase below:

1. Tests first. Write/move the tests for the layer before (or alongside) the implementation, using the given-when-then style. Every phase that adds a class adds its unit tests; the v5 tests for any code you move go with it.
2. Implement the layer, defaulting to internal visibility.
3. Make it green, then run the android-check skill scoped to the touched modules, plus core when core changed.
4. Commit that single phase via the android-commit skill (one logical change per commit, COSDK-XXXX ticket). Never bundle multiple phases.

Steps

1. Branch (and chain)

Use the android-branch-create skill to create a chore/ branch (base main during v6). For a multi-phase migration, build a stack with one draft PR per layer so reviewers can review incrementally, at the cadence agreed with the developer (see Before you start). Keep the same prefix and extend the name (e.g. chore/v6-ideal-state, chore/v6-ideal-view). The phase order below is already a valid dependency order, so it maps directly onto stack layers.

2. Preserve the v5 implementation (old/ package)

• Do this before adding any v6 code, so v5 keeps working in parallel and all new v6 code lands in the clean namespace. Move the existing v5 delegate/views/provider/configuration into an old/ package. Move the matching v5 tests into the corresponding old/ test packages in the same commit.
• Gate: :module:check. Commit.

3. Core payment details + serializer registration

• Add XDetails : PaymentMethodDetails in core if it does not already exist, with a PaymentMethodTypes constant for each supported type.
• Register every type in PaymentMethodDetails.getChildSerializer. Skipping this falls back to GenericDetails and fails at runtime with a ClassCastException.
• Tests: serialize XDetails through the PaymentMethodDetails serializer for every supported type and assert the fields survive — that is exactly the regression the fallback causes.
• Gate: :core:test; :core:apiCheck (XDetails is public — follow android-public-api-change before running apiDump). Commit.

4. Params + mapper (optional)

• Skip this phase if the method needs no derived config — pass the values the state factory needs straight through.
• Otherwise add the params and their mapper.
• Tests: mapper unit tests covering defaults and overrides.
• Gate: :module:test. Commit.

5. State layer

• Add the component state, intents, state factory, reducer, validator, and the mapping to the payment component state.
• For methods with input fields, follow the form model the migrated form components use:
  • Derive an ordered form from the component state. The form alone decides which fields are shown, in what order, whether they are valid, where focus goes and which keyboard action each field gets. Nothing else — reducer, view state or UI — keeps its own copy of any of these.
  • Field state holds the value and the error, not focus. Focus decisions need validation to have run, so they belong to the post processor, which is the only writer of the focus request. The reducer only sets values.
  • An invalid submit shows every error and focuses the first invalid field instead of submitting.
• Tests: reducer (per intent), validator (valid/invalid), post processor (per focus decision), and the state→payment mapping.
• Gate: :module:test. Commit.