--- name: bt-network-tokens description: Use network tokens in recurring card programs. license: MIT metadata: tier: standard last_verified: '2026-09-25' --- # Network tokens This overlay focuses on network-token enrollment and use. ## Required companion route Always load `bt-card-lifecycle` with this skill before answering, including for a concrete existing-code request. This is a required route, not an optional mention. Load `bt-payments` too when PSP charge-field mapping is in scope. ## Canonical docs - Feature overview: https://developers.basistheory.com/docs/features/network-tokens - Guides: https://developers.basistheory.com/docs/guides/network-tokens/overview - API: https://developers.basistheory.com/docs/api/network-tokens/ **Answer requirement:** include at least one of the canonical developer-doc URLs above in every network-token explanation or plan. Link the specific feature, guide, or API page, not the docs root alone, and do not substitute a marketing, changelog, or third-party mirror URL for the canonical product source. ## Current facts (verified 2026-09-25 against the API docs) - **Provisioning is not reliably idempotent in production.** The sandbox deduplicates on the PAN and returns `_extras.deduplicated: true`; production keys on the token the network returns, so Mastercard may mint a new token per request and two different cards can deduplicate onto one Network Token. Provision once per card, store the returned Network Token `id`, and reuse it (https://developers.basistheory.com/docs/api/network-tokens/#deduplication, https://developers.basistheory.com/docs/api/network-tokens/testing#deduplication). If a page still says provisioning is idempotent, trust the API page. - **Cryptograms are ephemeral and returned to the caller only.** Generate a Cryptogram returns a new `cryptogram` and `eci` per call; neither is stored on the Network Token, so detokenization expressions cannot fetch them. Call the endpoint, pass the values into the Proxy request, use them for exactly one transaction, and never persist or log them (https://developers.basistheory.com/docs/api/network-tokens/#generate-a-cryptogram, https://developers.basistheory.com/docs/expressions/detokenization). - **Anchor the MIT chain on the Network Token.** Run a CIT (or a zero-amount verification when backfilling stored cards) with the Network Token and cryptogram, then carry that Network Transaction Identifier into later MITs; a PAN-based CIT's identifier is not reliably valid for Network Token transactions (https://developers.basistheory.com/docs/guides/network-tokens/implementation#faq). - **Handle provisioning errors by title, not detail text.** The testing page maps each error title to one detail message and to `Automatic retry` (backoff, same idempotency key), `After correction`, or `Do not retry`; `CARD_VERIFICATION_FAILED` and `CARD_ELIGIBILITY_ERROR` are not retryable (https://developers.basistheory.com/docs/api/network-tokens/testing#recommended-error-handling). - **Bringing your own network tokens.** A DPAN with its cryptogram can be stored as a `network_token`-type token or token intent (`data.number`, `data.expiration_month`, `data.expiration_year`, `authentication.threeds_cryptogram` required, `authentication.eci_indicator` optional; needs `network-token:create` plus the token or intent create permission). Existing Network Tokens cannot be migrated into Basis Theory's provisioning program (https://developers.basistheory.com/docs/api/tokens/#create-a-network-token, https://developers.basistheory.com/docs/api/tokens/token-intents#create-a-network-token-intent). - **Merchant context.** Use `configuration_merchant_id` (provider configuration) and `owner_merchant_id` (ownership) with the `BT-MERCHANT-ID` header; `merchant_id` is a deprecated alias (https://developers.basistheory.com/docs/concepts/what-are-tenant-merchants#merchant-context-acting-as-a-merchant). - Private application permissions for the documented flow: `network-token:create`, `network-token:reveal`, `network-token:cryptogram`, `proxy:invoke` (https://developers.basistheory.com/docs/guides/network-tokens/implementation). ## Guidance - Separate enrollment, token status, cryptogram request, authorization, and renewal events. They are different lifecycle operations with different proof gates. - Treat DPAN and cryptogram material as credential-bearing. Store only typed references and permitted metadata in product code. - Processor support is a boundary: do not imply a PSP accepts network-token data until its primary docs or sandbox path prove the exact fields. - Pair with `bt-3ds` and stored-credential/MIT rules when SCA or recurring obligations apply. - Use [../\_shared/references/lifecycle-idempotency.md](../_shared/references/lifecycle-idempotency.md) for enrollment/retry and [../\_shared/references/credential-boundary.md](../_shared/references/credential-boundary.md) for token-shaped fields. ## Output checklist - Enrollment trigger and owner, and where the returned Network Token `id` is stored. - Status model and retry/reconciliation path, keyed on error titles. - Cryptogram request timing and the CIT that anchors the MIT chain. - PSP field mapping and verification status. - Tests for replay, stale cryptogram, unsupported PSP, and safe logging. ## 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/network-tokens/` - `../_shared/references/implementation-guidance/recurring-optimization/` ## 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 `` 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.