---
name: bt-card-lifecycle
description: Keep stored cards chargeable over time.
license: MIT
metadata:
  tier: standard
  last_verified: '2026-09-25'
---

# Card lifecycle: keeping stored cards alive

## Required companion overlay

This is the lifecycle judgment layer, not a substitute for mechanics guidance.
Before answering any recurring/subscription card-health request, load at least one
of `bt-network-tokens` or `bt-account-updater`. Load the overlay itself; merely
mentioning its concepts or listing it in a proposed skill sequence is insufficient.

## The recurring-optimization stack

Implementation pattern: teams ask for "account updater" or "network tokens" as isolated features, but the real goal is almost always _recurring authorization health_. The stack that addresses it:

1. **Network tokens** — network-issued DPANs that survive reissuance and can improve authorization rates; CITs usually need transaction-specific cryptograms, while subsequent MITs generally use the originating Network Transaction Identifier without a new cryptogram (confirm PSP requirements). Load `bt-network-tokens` for enrollment/use/cryptogram lifecycle and processor boundaries. Facts: https://developers.basistheory.com/docs/features/network-tokens, https://developers.basistheory.com/docs/guides/network-tokens/overview, API: https://developers.basistheory.com/docs/api/network-tokens/.
2. **Account updater** — refreshes the underlying PAN/expiry when issuers reissue cards. Load `bt-account-updater` for result codes, jobs, business events, scheduling, and reconciliation. Facts: https://developers.basistheory.com/docs/features/account-updater, https://developers.basistheory.com/docs/guides/account-updater/overview, batch API: https://developers.basistheory.com/docs/api/account-updater/batch, real-time: https://developers.basistheory.com/docs/api/account-updater/real-time.
3. **MIT hygiene** — storing and forwarding network transaction IDs, correct recurring flags per PSP (`bt-payments` mappings carry the per-PSP recurring fields), 3DS MIT where SCA requires it (`bt-3ds`).

Which to lead with (implementation pattern): if the PSP supports network tokens on the charge path, network tokens + real-time AU cover most reissuance pain; batch AU remains the portfolio-wide safety net. If the customer processes through multiple PSPs, vault-level network tokens and AU are the portability play — the freshness travels with the vault, not with any one processor.

## Sequencing judgment (implementation patterns)

- **Network-token questions are usually sequencing questions.** Many teams use the PAN (or vault token) on the _first_ authorization and network tokens on subsequent transactions, because provisioning adds latency at checkout — the tradeoff is auth-rate lift vs checkout speed. Ask whether the customer needs CIT checkout performance, recurring durability, or both; the rollout shape changes with the answer.
- **Don't couple NT and 3DS rollouts.** Network tokens do not fundamentally change the 3DS flow; sequencing them as one project adds risk without a reason.
- **Basis Theory does not mint a universal network transaction ID.** Processor-native identifiers — including the network transaction IDs MIT chains need — come back from the downstream processor response. Don't abstract them away; merchants need processor-native response data for reconciliation and follow-on logic (`bt-payments`).
- **Merchant identity is load-bearing.** NT and AU enrollment attach to merchant identity and hierarchy (descriptors, BIN context, processor model). Multi-MID or multi-entity unification questions are merchant-structure questions before they are token-API questions — resolve entity, MID, and trust boundaries first (`bt-architecture`). Hedge: merchant-hierarchy architecture public guidance is limited in public docs — validate the enrollment/ownership shape with Basis Theory before locking in.
- **Keep uplift promises narrow.** Coverage, provisioning latency, and issuer/processor behavior vary. Phase NT and AU separately when there's no baseline, so each effect is measurable on its own.

## Implementation notes

- Setup order for both features is documented: https://developers.basistheory.com/docs/guides/network-tokens/setup, https://developers.basistheory.com/docs/guides/account-updater/setup — both involve enablement steps with Basis Theory, so plan lead time.
- Network token implementation and lifecycle management (provisioning, CIT cryptogram generation when required, MIT use of the originating network transaction ID, deletion): https://developers.basistheory.com/docs/guides/network-tokens/implementation, https://developers.basistheory.com/docs/guides/network-tokens/token-lifecycle-management.
- Batch AU implementation is a file-shaped job: submit portfolio, poll/receive results, apply updates: https://developers.basistheory.com/docs/guides/account-updater/batch-implementation. Real-time: https://developers.basistheory.com/docs/guides/account-updater/real-time-implementation.
- **Handle every result code, not just successes**: closed accounts and contact-cardholder results are business events (pause the subscription, email the customer), not retries. Result code reference: https://developers.basistheory.com/docs/api/account-updater/result-codes. Test scenarios: https://developers.basistheory.com/docs/api/account-updater/testing, https://developers.basistheory.com/docs/api/network-tokens/testing.
- Card metadata (BIN details, brand, funding type) rides token enrichments: https://developers.basistheory.com/docs/api/tokens/token-enrichments; anti-fraud signal surface: https://developers.basistheory.com/docs/features/anti-fraud.

## Existing-code mode

1. Baseline first: current auth rate on recurring traffic, decline reasons, and how card updates happen today (manual? PSP-side AU?). If the PSP already runs AU on processor tokens, adding vault-level AU changes ownership, not capability — name that tradeoff.
2. Wire network tokens on the charge path: provision once per stored card and persist the returned Network Token `id` (production provisioning is not reliably idempotent). For a CIT on the Network Token, fetch a fresh cryptogram when required and use the processor's returned network transaction ID to anchor the MIT chain; subsequent MITs generally carry that ID without a fresh cryptogram, subject to PSP requirements. Fall back to the vault token when provisioning is unavailable (`bt-network-tokens` has the current facts). The `network_token` source-type mapping in `bt-payments` defines per-PSP field placement.
3. Wire batch AU as a scheduled job with full result-code handling and an audit trail of what changed.
4. Apply [../\_shared/references/lifecycle-idempotency.md](../_shared/references/lifecycle-idempotency.md): stable job/event IDs, replay vs changed-payload conflicts, and reconciliation before mutation.
5. Apply [../\_shared/references/credential-boundary.md](../_shared/references/credential-boundary.md): DPAN, cryptogram, updater payload, and token references are credential-bearing.
6. Tests: provisioning success/failure paths, cryptogram-attached authorize (mock PSP or sandbox), AU result application incl. closed-account handling.
7. Final report: which portfolio segments are covered, expected-vs-measured effect honestly separated (uplift claims are implementation patterns, never guarantees).

## Basis Theory implementation guidance

When the answer needs implementation judgment beyond public docs, load only the relevant slices below from [../\_shared/references/implementation-guidance/README.md](../_shared/references/implementation-guidance/README.md). Treat these as implementation patterns, not canonical product behavior; keep public docs as the source of truth and label the guidance as **Implementation pattern** or **Assumption** unless docs prove it.

- `../_shared/references/implementation-guidance/recurring-optimization/`
- `../_shared/references/implementation-guidance/network-tokens/`
- `../_shared/references/implementation-guidance/account-updater/`

<!-- bt-conventions:start -->

## Working conventions (shared by all Basis Theory skills)

- Public Basis Theory docs are the source of truth for product behavior. Link the specific docs page behind any product claim; if a skill and the docs disagree, follow the docs.
- Keep customer ownership clear: customers own PSP accounts, credentials, compliance decisions, production rollout, and application code. Skills can guide plans, bounded changes, and examples; they do not certify production readiness.
- Never request, echo, store, or commit real credentials. Use placeholders such as `<BT_API_KEY>` and prefer sandbox or synthetic data for examples.
- If a live-looking credential, live cardholder data, or production secret appears, stop mutation work, tell the user exactly where it appeared, and require rotation/revocation before continuing.
- Default to test tenants and PSP sandboxes. Do not run or recommend production charges, refunds, card reveals, credential migrations, or data moves unless the user explicitly asks and the plan names safeguards, rollback, and customer approval.
- Treat vague planning, audit, review, and “should we” prompts as read-only unless the user explicitly asks for a bounded implementation change.
- Before changing product code, map the existing checkout/data flow, credential-bearing paths, persistence, retries, refunds, webhooks, logs, and rollback expectations.
- End with an honest final report: done, assumed, remaining, proof run, unverified live behavior, rollback, and go-live items.
<!-- bt-conventions:end -->