--- name: bt-issuing description: Display issued-card data safely. license: MIT metadata: tier: standard last_verified: '2026-09-25' --- # Card issuing: vault, display, PIN ## The shape of the issuing integration Fact: the issuing pattern is — pull the issued card from the issuer processor into the vault via the Proxy (so the PAN never transits your servers), then reveal it to the right person through Elements with session-scoped access (https://developers.basistheory.com/docs/card-issuing/, https://developers.basistheory.com/docs/blueprints/cards/issue-and-display-cards). The three documented flows: 1. **Issue / vault the card** — proxy the issuer-processor "get card" call, tokenize the response in flight: https://developers.basistheory.com/docs/card-issuing/issue-cards. 2. **Display the card** — reveal PAN/CVC to the cardholder in web or mobile UI using Elements + sessions, so plaintext renders only inside Basis Theory-controlled components: https://developers.basistheory.com/docs/card-issuing/display-cards. 3. **Set PIN** — collect a PIN with Elements and deliver it to the issuer processor without your systems seeing it: https://developers.basistheory.com/docs/card-issuing/set-card-pin. ## The access-control half of the problem Displaying issued cards is as much an authorization problem as a rendering problem. Implementation pattern: the design that holds up is per-reveal, short-lived **sessions** authorizing exactly one cardholder's token (sessions mechanics: https://developers.basistheory.com/docs/guides/govern/sessions, access rules: https://developers.basistheory.com/docs/concepts/access-controls — guidance in `bt-architecture`), plus an audit trail of who revealed what (`bt-pii` covers audit patterns). Never mint a broad-scope reveal capability into a frontend. Disambiguation: revealing _stored third-party_ cards (not your issued program) is `bt-pii` reveal-pattern territory; call-center masked display is https://developers.basistheory.com/docs/guides/share/display-masked-data. This skill is for cards the customer's program issues. ## Existing-code mode 1. Identify the issuer processor and its card-detail API; wire the vault step as a pre-configured proxy route (`bt-proxy` mechanics) so the integration is centrally managed. 2. Backend: an endpoint that authenticates the cardholder, then creates a Basis Theory session scoped to that cardholder's card token only. 3. Frontend: Elements reveal components bound to the session — card number, expiry, CVC as separate elements matching the customer's card-art design. On Web Elements v3 the `cardDisplay` element covers the common case (Fact, verified 2026-09-25): it loads a `card` token by `tokenId`, renders each field as `masked`, `visible`, or `hidden` with an optional reveal toggle and clipboard copy, and obtains its session through a `sessionAuthorizationUrl` endpoint that the customer's backend authorizes with a Private key, so the session key never reaches the page. Scope the `reveal` access rule to the single token, authenticate the caller and derive the token from identity, and keep the endpoint same-origin with CSRF protection (https://developers.basistheory.com/docs/sdks/web/web-elements/v3/components#carddisplay). 4. Set-PIN flows follow the same session pattern with the PIN element posting through to the issuer processor. 5. Tests: session scoping (cardholder A cannot reveal cardholder B's card — this is the test that matters), reveal renders with a test token, proxy route failure surfaces cleanly. 6. Final report: issuer-processor specifics are Custom work (their API shapes, their auth) — label them; the Basis Theory-side pattern is the reusable part. Sandbox note: issuer processors have their own sandboxes with test cards; run the full vault → display → PIN loop against issuer sandbox + Basis Theory test tenant before any production discussion. ## 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/card-issuing-fintech/` - `../_shared/references/implementation-guidance/sessions/` ## 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.