@vtex/faststore-plugin-buyer-portal 2.0.17 → 2.0.19

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.19] - 2026-08-04
+
+### Changed
+- Upgrade `@faststore/ui` dependency to 4.5.0
+- Upgrade `@faststore/core` dependency to 4.5.0
+
+## [2.0.18] - 2026-08-03
+
+### Changed
+
+- Credit card registration, listing, and deletion now call the new `saved-cards` microservice directly instead of the `buyer-portal-graphql` BFF (card tokenization is unchanged). Payment validators and the "set as default"/active-inactive toggle keep working against the BFF as before. Cards show their nickname when available, falling back to the masked card number otherwise — the same fallback the list already used
+
 ## [2.0.17] - 2026-07-30
 
 ### Fixed
@@ -809,7 +821,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add CHANGELOG file
 - Add README file
 
-[unreleased]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.17...HEAD
+[unreleased]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.19...HEAD
 [1.3.55]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.54...v1.3.55
 [1.3.54]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.53...v1.3.54
 [1.3.53]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v1.3.52...v1.3.53
@@ -907,6 +919,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [2.0.10]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.9...v2.0.10
 [2.0.9]: https://github.com/vtex/faststore-plugin-buyer-portal/releases/tag/2.0.9
 
+[2.0.19]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.18...v2.0.19
+[2.0.18]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.17...v2.0.18
 [2.0.17]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.16...v2.0.17
 [2.0.16]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.15...v2.0.16
 [2.0.15]: https://github.com/vtex/faststore-plugin-buyer-portal/compare/v2.0.14...v2.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vtex/faststore-plugin-buyer-portal",
-  "version": "2.0.17",
+  "version": "2.0.19",
   "description": "A plugin for faststore with buyer portal",
   "main": "index.js",
   "scripts": {
@@ -22,8 +22,8 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.29.0",
-    "@faststore/core": "https://pkg.csb.dev/vtex/faststore/commit/6d41d338/@faststore/core",
-    "@faststore/ui": "https://pkg.csb.dev/vtex/faststore/commit/6d41d338/@faststore/ui",
+    "@faststore/core": "4.5.0",
+    "@faststore/ui": "4.5.0",
     "@release-it/bumper": "^4.0.0",
     "@release-it/keep-a-changelog": "^3.0.0",
     "@types/react": "^18.2.42",

package/specs/credit-card-saved-cards-migration.md

@@ -0,0 +1,296 @@
+# Credit Card Registration — Migrate BFF Calls to the Saved-Cards Service
+
+> **Status**: Approved (implementation in this PR is incomplete — see Decision 7; `register`/`delete` are confirmed non-functional as written, pending a CORS fix)
+> **Created**: 2026-07-27
+> **Jira**: [B2BTEAM-3418](https://vtex-dev.atlassian.net/browse/B2BTEAM-3418) — "[Organization Account] Alterar o fluxo de cadastro de cartão para usar a nova api"
+> **Scope note**: The Jira ticket's literal wording ("card-registration flow") is expanded here to cover every credit-card operation the new backend actually supports today — session, register, list, delete — confirmed with the assignee. Operations the new backend does **not** expose (validators, default/active toggling) stay on the BFF; see [Out of Scope](#out-of-scope).
+> **Backend distinction**: an earlier candidate backend, `vtex/personal-cards-service` (.NET), was investigated and found decommissioned — deprecated in its catalog entry, CI/CD disabled, no controllers beyond a healthcheck. The live backend is **`vtex/saved-cards`** (Postman collection `43115468-febaf668-f6e8-4275-9991-8199bddb47e9`, contract at `.vtex/definitions/*.tsp`, confirmed 2026-07-27 by reading the service's source, tests, and TypeSpec contract directly). Do not wire against `personal-cards-service`.
+
+## 1. Business Context
+
+### Problem Statement
+
+Today, `faststore-plugin-buyer-portal`'s credit-card feature (`src/features/credit-cards`) talks to the `buyer-portal-graphql` BFF for everything except card tokenization: getting a payment session, listing cards, registering a card, and deleting a card all go through `CreditCardClient` → the BFF. VTEX has since built a dedicated microservice for this, `saved-cards`, which owns the card-registration business logic (charge orchestration, 3DS, Profile persistence) that used to live in the BFF/legacy stack. Card data must keep flowing through the same PCI-compliant path — tokenization stays in the Organization Account, calling `vtexpayments.com.br` directly — but everything downstream of tokenization should call the new service instead of the BFF.
+
+### Goals
+
+- Every card operation the `saved-cards` service supports today (session, register, list, delete) is served by `saved-cards`, not the BFF.
+- The PCI tokenization step is untouched — no card PAN/CVV data is newly introduced into any call to `saved-cards`.
+- No functional regression for the buyer: register/list/delete continue to work exactly as observed today. Card nicknames (`cardLabel`) render whenever `saved-cards` provides the field, falling back to the masked card number otherwise.
+- Operations `saved-cards` does not expose yet (validators, default/active toggling) keep working unchanged on the BFF — this migration does not remove or break them.
+
+### User Stories
+
+#### US-1: Buyer registers a new credit card
+
+- **Story**: As a B2B buyer, I want to register a credit card for my organization, so that I can use it for future purchases.
+- **Acceptance Criteria**:
+  - **Given** a buyer fills out the card form and confirms, **when** the app requests a payment session, **then** it calls `GET /api/saved-cards/payments/session` (not the BFF) and receives a session id.
+  - **Given** a valid payment session and a successfully tokenized card, **when** the app submits the card, **then** it calls `POST /api/saved-cards/credit-card` (not the BFF) with `{ token: { creditCardToken, paymentSystem }, recaptchaV3Token }`.
+  - **Given** the register call succeeds, **when** the response returns, **then** the buyer sees the same success toast and page reload as today (the response body is not otherwise consumed by the UI).
+  - **Given** the register call fails with any mapped error (`400`, `422`, `500`, `502`), **when** the failure occurs, **then** the buyer sees the existing generic "couldn't save card" error toast — no new per-error-code UI is introduced by this change.
+
+#### US-2: Buyer sees their registered cards
+
+- **Story**: As a B2B buyer, I want to see the list of cards registered to my organizational unit, so that I can manage them.
+- **Acceptance Criteria**:
+  - **Given** a buyer opens the credit cards page, **when** the list loads, **then** it calls `GET /api/saved-cards/credit-card` (not the BFF).
+  - **Given** a card has a nickname, **when** it renders in the list, **then** the nickname is shown; **given** a card was saved without one, **then** it falls back to the masked card number, exactly as the existing `creditCard.cardLabel ?? creditCard.cardNumber` fallback already does today.
+  - **Given** the buyer has no Organizational Unit association, **when** the list loads, **then** `isDefault`/`isActive` still resolve correctly (the service treats unit as optional).
+
+#### US-3: Buyer deletes a card
+
+- **Story**: As a B2B buyer, I want to delete a card I no longer use, so that it stops appearing as an option.
+- **Acceptance Criteria**:
+  - **Given** a buyer confirms card deletion, **when** the app submits the deletion, **then** it calls `DELETE /api/saved-cards/credit-card/{tokenId}` (not the BFF), using the card's `accountId` as `tokenId` — the same identifier the UI already passes today.
+  - **Given** the deletion succeeds, **when** the response returns (`204`), **then** the buyer sees the existing success toast and page reload.
+  - **Given** the card no longer exists, **when** the deletion is attempted, **then** the service returns `404` and the buyer sees the existing generic error toast.
+
+#### US-4: Saved-cards is unavailable or rejects the request
+
+- **Story**: As a buyer, if the saved-cards backend is down or rejects my request, I want the same clear error behavior the app already has, so a broken migration doesn't produce a worse experience than today.
+- **Acceptance Criteria**:
+  - **Given** `saved-cards` returns `502` (`DownstreamError`) on any of the four operations, **when** the call fails, **then** the existing error-handling path (`onError` on the corresponding hook) fires the same generic error toast used today.
+  - **Given** the register call is missing the required session header, **when** `saved-cards` returns `400 SESSION_REQUIRED`, **then** the failure is treated as a register error like any other (generic toast) — this is a signal for us to check header wiring, not a new buyer-facing state.
+
+### Key Scenarios
+
+| Scenario | Pre-conditions | Steps | Expected Result |
+|---|---|---|---|
+| Happy path — register a card | Buyer has a valid session, address, and tokenized card | Fill form → confirm → tokenize → register | Card is saved via `saved-cards`; success toast; list reflects the new card on next load |
+| Error case — saved-cards down | `saved-cards` returns `502` on register | Buyer confirms the form | Existing generic error toast; loading state cleared; no partial/duplicate submission |
+| Edge case — buyer with no Organizational Unit | Buyer account has no unit association | Buyer opens the cards list | List loads successfully; `isDefault`/`isActive` computed without unit-scoped data, matching current BFF behavior for unaffiliated buyers |
+| Edge case — card has no label | Card was saved without a nickname (field omitted by `saved-cards`) | Buyer opens the cards list | Card renders using the masked card number fallback (no crash, no blank label) |
+
+### Functional Requirements
+
+- **FR-1**: `getPaymentSessionService` calls `GET /api/saved-cards/payments/session?an={account}` instead of the BFF equivalent.
+- **FR-2**: `saveCreditCardService` (register) calls `POST /api/saved-cards/credit-card?an={account}` instead of the BFF equivalent, with the request body unchanged (`{ token: { creditCardToken, paymentSystem }, recaptchaV3Token }`).
+- **FR-3**: `getCreditCardsListService` calls `GET /api/saved-cards/credit-card?an={account}` instead of the BFF equivalent.
+- **FR-4**: `deleteCreditCardService` calls `DELETE /api/saved-cards/credit-card/{tokenId}?an={account}` instead of the BFF equivalent, sending the identifier as a path parameter instead of a request body.
+- **FR-5**: The tokenization call (`TokenClient` → `vtexpayments.com.br`) is unchanged — this migration does not touch how or where card data is tokenized.
+- **FR-6**: Requests to `saved-cards` carry the buyer's `VtexIdclientAutCookie` cookie (as today) plus a dedicated `Vtex_session` HTTP header carrying the raw `vtex_session` cookie value — required specifically because the register endpoint (`POST /credit-card`) rejects requests missing it (`400 SESSION_REQUIRED`).
+- **FR-7**: `getPaymentValidators` (validators) and `setDefaultCreditCard`/`removeDefaultCreditCard` (default/active toggling) keep calling the BFF unchanged — see [Out of Scope](#out-of-scope).
+- **FR-8**: No new per-error-code UI is introduced; all four migrated operations keep using their existing generic success/error toast handling.
+
+### Non-Functional Requirements
+
+- **No card data (PAN, CVV, expiry) is ever sent to `saved-cards`** — only the opaque token produced by tokenization, matching the existing PCI boundary.
+- **No PII or auth material (cookies, tokens, `Vtex_session` values) is written to logs**, consistent with the project's existing safety guardrails.
+- **Card nicknames (`cardLabel`) are handled as an optional field**: the UI renders the nickname when `saved-cards` returns it and falls back to the masked card number when it doesn't, so the frontend is correct either way. An earlier revision of this spec documented losing `cardLabel` as an accepted regression, based on the service contract at the time; `saved-cards` is reported to have since added the field, so the frontend was made forward-compatible with it. **Not yet observable**: as of 2026-07-30 the field is absent from every card returned by both `vtexcommercebeta` (`saved-cards-v0.0.8-stg-126`) and `vtexcommercestable` (`saved-cards-v0.0.7-prd-005`) for account `b2bfaststoredev` — verify against a deployment that actually returns it before treating nickname display as confirmed. The separate "rename card" drawer (`EditCreditCardDrawer`) still doesn't persist to any backend — already true before this migration, unchanged by it.
+- The `Vtex_session` header change (FR-6) must be scoped to the new `saved-cards`-facing client only — the shared cookie utility (`getCookieWithoutSessionObjects`) that strips `vtex_session` for other calls must not be changed globally, to avoid affecting BFF calls that still expect that stripping behavior.
+
+### Out of Scope
+
+- **Payment validators** (`getPaymentValidators` — card brand regex/mask rules). `saved-cards` does not expose this endpoint today: it is present in the team's Postman collection but absent from the service's TypeSpec contract, controllers, and tests. This call stays on the BFF until (and unless) the endpoint is actually implemented server-side; migrating it is a separate, backend-first piece of work.
+- **Default/active card toggling** (`DefaultValuesClient.setDefaultCreditCard` / `removeDefaultCreditCard`, used by the "set as default" and active/inactive toggle in `CreditCardLayout`). `saved-cards` only uses this data internally (via its own MasterData client) to compute the `isDefault`/`isActive` fields it returns from `list` — it does not expose a public endpoint to change them. Stays on the BFF.
+- **Card rename / label editing.** Already a no-op today (the `EditCreditCardDrawer` doesn't call any persistence API); not something this migration needs to preserve or recreate.
+- **Shared/organization-level card visibility** (a "Shared" or org-wide cards view). Out of scope for Organization Account entirely — that concept is being built as a separate My Account feature in `vtex/faststore` (Jira B2BTEAM-3636/3634), against the same `saved-cards` backend but in a different repo and PR.
+- **Any UI/visual redesign** of the credit-card screens. This is a backend-integration swap, not a UX change.
+
+---
+
+## 2. Arch Decisions
+
+### Proposed Solution
+
+Introduce a new client (working name: `SavedCardsClient`) in `src/features/credit-cards/clients/`, alongside the existing `TokenClient` (untouched) and `CreditCardClient`. The four service functions currently backed by `CreditCardClient` (`getPaymentSessionService`, `saveCreditCardService`, `getCreditCardsListService`, `deleteCreditCardService`) are repointed to the new client; `getCreditCardValidatorsService` and the default-value services keep using `CreditCardClient`/`DefaultValuesClient` against the BFF, unchanged. Hooks, components, and types keep their existing shapes wherever possible — the main type-level change is that `CreditCardData` (from `list`) treats `cardLabel` as optional, which the UI already tolerates via its existing fallback.
+
+Authentication for the new client forwards the existing `VtexIdclientAutCookie` cookie (as today) plus a new, narrowly-scoped `Vtex_session` header sourced from the raw `vtex_session` browser cookie — read explicitly for this client, not through the shared `getCookieWithoutSessionObjects` utility (which strips it for other purposes and must keep doing so for BFF calls).
+
+The base URL (`https://{account}.vtexcommercestable.com.br/api/saved-cards`) and the `Authorization: Bearer` question (not required) were both verified empirically against the live production service — see Decisions 4 and 5.
+
+### Architecture Overview
+
+```mermaid
+sequenceDiagram
+    participant Buyer
+    participant UI as CreateCreditCardDrawer
+    participant SavedCards as saved-cards service
+    participant VtexPayments as vtexpayments.com.br (tokenization, PCI)
+    participant BFF as buyer-portal-graphql (BFF)
+
+    Buyer->>UI: Fill card form, confirm
+    UI->>SavedCards: GET /api/saved-cards/payments/session
+    SavedCards-->>UI: { id, name, expiresAt }
+    UI->>VtexPayments: POST {session}/tokens (card data — unchanged, PCI boundary)
+    VtexPayments-->>UI: { token, bin, lastDigits, ... }
+    UI->>SavedCards: POST /api/saved-cards/credit-card { token, recaptchaV3Token }
+    SavedCards-->>UI: 200 AddCardResponse / 4xx-5xx typed error
+    UI-->>Buyer: success toast + reload, or generic error toast
+
+    Note over UI,BFF: Validators and default/active toggling still call the BFF (out of scope)
+```
+
+### Alternatives Considered
+
+| Alternative | Pros | Cons | Verdict |
+|---|---|---|---|
+| Migrate only `registerCreditCard`, leave session/list/delete on the BFF | Smallest possible change; matches the Jira ticket's literal wording | Leaves the feature split across two backends for operations that already have a working `saved-cards` endpoint; more total migration work later | Rejected — the requester explicitly asked to migrate every route the new service already supports |
+| Migrate everything including validators and default-value toggling | One clean cutover for the whole feature area | **Not technically possible today** — those endpoints don't exist in `saved-cards` (confirmed by reading its TypeSpec contract, controllers, and tests) | Rejected — would require inventing behavior against a nonexistent API |
+| Repoint the existing `CreditCardClient` in place (same class, new base URL) instead of adding a new client | Fewer new files | Conflates two different backends/auth models (path-based `customerId`/`unitId` for the BFF vs auth-derived identity + `Vtex_session` header for `saved-cards`) behind one class, increasing the chance of leaking BFF-only assumptions into `saved-cards` calls (and vice versa) | Rejected — a dedicated client keeps the two backends' auth/URL conventions from bleeding into each other |
+
+### Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|---|---|---|---|
+| **`saved-cards` sends no CORS headers, so every client-side (browser) call to it fails in every environment — this is not a hypothetical, it was reproduced live.** `register` and `delete` are both wired as direct browser-side calls (`CreateCreditCardDrawer`/`DeleteCreditCardDrawer` handlers) and both are confirmed broken (see Decision 7). Unit tests don't catch this because they mock `fetch` and never exercise real CORS enforcement | **Critical** — two of the four migrated operations don't work end-to-end as currently implemented, in production exactly as much as locally | **Confirmed** (not a probability — already reproduced) | Do not ship this PR until Decision 7 is resolved: either get CORS support added to `saved-cards`, or move `register`/`delete` to a same-origin server-side proxy route in this plugin. Re-verify both operations live afterward — a passing unit test suite is not sufficient evidence (see Decision 6) |
+| `register` (add card) has never been exercised to a real charge outcome (`200`/`400`/`422`) — blocked first by the explicit choice to avoid a real Gateway/3DS attempt, and now by the CORS issue above regardless | Medium (an edge case specific to the charge/3DS/Profile-persistence path could still surface only in `register`, on top of the CORS fix) | Low-Medium | Re-attempt after Decision 7's fix lands, with a real buyer session |
+| `UseAdHocCard` permission enforcement is ambiguous — the TypeSpec contract sets `skipAuthorization: true` (skips the generic License-Manager-based check), but service docs describe automatic permission enforcement via the same decorator | Medium (a buyer without the role could be wrongly allowed or wrongly blocked) | Low-Medium | Verify behavior in staging with a buyer account that lacks `UseAdHocCard` before rollout; do not assume either behavior from the docs alone |
+| Scoping the new `Vtex_session` header narrowly to the new client, but implemented carelessly, could leak into or break other BFF calls sharing `cookie.ts` | Medium | Low | Keep the header-sourcing logic local to the new client; do not modify `getCookieWithoutSessionObjects`'s existing stripping behavior |
+
+### Key Decisions
+
+#### Decision 1: Tokenization stays on `vtexpayments.com.br`, untouched
+
+- **Status**: Accepted
+- **Context**: PCI compliance requires card data tokenization to happen in a scope that already meets those requirements; the Jira ticket is explicit that only "the BFF call onward" moves.
+- **Decision**: `TokenClient` and its call to `vtexpayments.com.br` are not modified by this work.
+- **Consequences**: `saved-cards` never receives raw card data — only the token, `paymentSystem`, and `recaptchaV3Token` it already expects.
+
+#### Decision 2: Migrate only the four operations `saved-cards` already implements
+
+- **Status**: Accepted
+- **Context**: `saved-cards`'s real, live contract (TypeSpec + controllers + tests) exposes exactly four operations: payment session, add card, list cards, delete card. Validators and default-value management are not implemented server-side.
+- **Decision**: Migrate session/register/list/delete; leave validators and default-value toggling on the BFF.
+- **Consequences**: The credit-card feature area temporarily calls two backends (BFF for validators/defaults, `saved-cards` for the rest) until those remaining endpoints exist server-side — at which point a follow-up migration can finish the cutover.
+
+#### Decision 3: Add a dedicated `Vtex_session` header, scoped to the new client only
+
+- **Status**: Accepted
+- **Context**: `saved-cards`'s register endpoint reads `Vtex_session` as its own HTTP header and 400s without it; the plugin's shared cookie utility currently strips `vtex_session` from every outbound call.
+- **Decision**: The new client reads the raw `vtex_session` cookie value and sends it as a `Vtex_session` header on its own requests, without altering the shared utility's behavior for other (BFF) calls.
+- **Consequences**: One extra, explicit piece of session plumbing lives in the new client; no behavior change for any existing BFF call.
+
+#### Decision 4: `Authorization: Bearer` is not required — the cookie alone authenticates
+
+- **Status**: Accepted
+- **Context**: `saved-cards`'s own integration tests always send `Authorization: Bearer <token>` alongside `VtexIdclientAutCookie`, which left it ambiguous whether Bearer was mandatory in the real (non-test-double) auth path. Resolved empirically against the live production service (`https://b2bfaststoredev.vtexcommercestable.com.br/api/saved-cards/credit-card`, `x-vtex-janus-router-backend-app: saved-cards-v0.0.7-prd-005`), using a real authenticated VTEX ID session, on the read-only `list` endpoint (no side effects):
+  - Cookie only, no `Authorization` header → `500` (past authentication; failed downstream because the test identity — an admin/CLI session — carries no buyer `customerId` claim, which a real storefront buyer's cookie does carry).
+  - `Authorization: Bearer` only, no cookie → `401 Unauthorized`.
+  - Cookie + `Authorization: Bearer` together → `500`, identical to cookie-only.
+  - Adding the Bearer header changed nothing; omitting the cookie broke auth. This conclusively shows the `VtexIdclientAutCookie` cookie is the credential that matters, and `Authorization: Bearer` is not required in addition to it.
+- **Decision**: The plugin does not need to add an `Authorization: Bearer` header. Continue forwarding `VtexIdclientAutCookie` exactly as it does today.
+- **Consequences**: No new auth-header plumbing is needed beyond Decision 3's `Vtex_session` header. Removes what was the single largest implementation risk in this migration.
+- **Scope of this evidence**: this isolates the auth *layer* only (via `401` vs. non-`401`, which doesn't require a `200` to be conclusive). See Decision 6 for end-to-end confirmation with a real buyer session.
+
+#### Decision 6 (superseded by Decision 7 — see below): initial claim that `list` and `delete` were verified end-to-end
+
+- **Status**: Superseded — partially correct, partially wrong. Kept here (rather than deleted) so the record shows how the mistake was found and corrected.
+- **What was originally claimed**: linking this branch into a local `faststore dev` server and exercising `list`/`delete` in-browser with a real buyer session showed `list` rendering 10 real cards, and `delete` producing the app's existing success toast on two different cards — taken as end-to-end confirmation of both.
+- **What was actually true (found afterward, see Decision 7)**: `list`'s success was real — it runs via the page's server-side `loader` function (Node `fetch`, not subject to browser CORS). But `delete` runs client-side via `useMutation`, invoked directly from the drawer's `onClick` handler — a genuine cross-origin browser `fetch()` to `saved-cards`. `useMutation` (`src/features/shared/hooks/useMutation.ts`) catches any error from `mutationFn` internally and never rethrows it (`catch (err) { setError(error); options?.onError?.(error); } ... return null;`); `DeleteCreditCardDrawer.handleConfirmClick` calls `await deleteCreditCard(...)` and then unconditionally shows the success toast and reloads, without checking the mutation's error state. So the "success" toast proves nothing about whether the request actually reached the server — see Decision 7 for what was actually happening underneath.
+- **Consequences**: This is a caution for future verification work in this codebase: a passing UI success state (toast, no visible error) is not reliable evidence a `useMutation`-based call succeeded, because errors are swallowed silently unless the caller explicitly checks the returned `error`/`data`. Prefer instrumenting the actual network call (or checking server response state directly) over trusting UI feedback for any operation wired this way.
+
+#### Decision 7: `saved-cards` sends no CORS headers — every client-side (browser) call to it is broken, in every environment
+
+- **Status**: Accepted (as a finding — the fix itself is not yet decided, see Risks & Mitigations)
+- **Context**: Attempting the `register` flow live (Decision 6's follow-up) surfaced a Next.js runtime error: `ClientError: Failed to fetch` from `Client.ts`, thrown from inside `CreateCreditCardDrawer.handleConfirmClick`, which calls `getPaymentSessionService` directly from a browser click handler. Reproduced directly via `fetch()` executed in the browser's own JS context against `https://b2bfaststoredev.vtexcommercestable.com.br/api/saved-cards/payments/session` (and separately against the `credit-card/{tokenId}` DELETE route) — both throw `TypeError: Failed to fetch` from the browser, with and without `credentials: "include"`. Confirmed via `curl` from the same machine (which is not subject to browser CORS) that this is specifically a CORS gap, not a connectivity problem: an `OPTIONS` preflight to the same route returns `405 Method Not Allowed` (`allow: GET` only — no CORS preflight handling at all), and a plain `GET` sent with an `Origin: http://localhost:3006` header gets back **zero** `Access-Control-Allow-*` headers of any kind.
+- **Why this isn't a `localhost`-specific artifact**: CORS is enforced by the browser based on the *response's* headers, not anything about the calling origin being "known" or "unknown" ahead of time. Since the server returns no `Access-Control-Allow-Origin` header for *any* origin (confirmed by explicitly sending one and getting nothing back), this would block a browser call from the real production storefront domain exactly the same way it blocks `localhost:3006`. This is not something a follow-up "just allow-list the real domain" fix on the client side can work around — the server has to opt in.
+- **What this actually breaks**: any call to `SavedCardsClient` triggered from a browser event handler (not a server-rendered `loader`/`getServerSideProps`-style function) fails outright with a swallowed or visible network error, in every environment, not just local dev. Concretely, as implemented in this PR:
+  - `register` (`CreateCreditCardDrawer.handleConfirmClick` → `getPaymentSessionService`/`saveCreditCardService`) — **broken**, confirmed via a real (aborted) attempt in-browser.
+  - `delete` (`DeleteCreditCardDrawer.handleConfirmClick` → `useDeleteCreditCard`/`useMutation` → `deleteCreditCardService`) — **broken**, confirmed via a direct `fetch()` reproduction; previously miscredited as working (see Decision 6).
+  - `list`'s *initial* page load is unaffected (server-side `loader`), but `useGetCreditCards`/`useQuery`-based client-side refetches of the list (if triggered anywhere client-side) would hit the same wall.
+- **Decision**: Escalated to the `saved-cards` team (`team-b2b`) to add proper CORS support (`Access-Control-Allow-Origin` matching real storefront domains, plus an `OPTIONS` preflight handler). This is a backend-owned fix — the frontend code in this PR is correct as written against the documented contract; it's the service that's missing a required capability for browser-direct callers. The same-origin-proxy alternative (routing calls through a Next.js API route in this plugin) was considered and explicitly rejected for now: it would work around the gap rather than fix it, and would duplicate auth-header plumbing (Decisions 3/4) into a new proxy layer for what is a backend defect, not a frontend design flaw.
+- **Consequences**: This PR (`feat/credit-card-saved-cards-migration`) is intentionally left unchanged — `register`/`delete` will start working once `saved-cards` ships CORS support, with no frontend code changes required. Re-verify both operations live once that lands (do not trust unit tests or UI toasts alone — see Decision 6).
+
+#### Decision 5: Production base host is `https://{account}.vtexcommercestable.com.br/api/saved-cards`
+
+- **Status**: Accepted
+- **Context**: The only host information in the team's Postman collection was `localhost:5001` (local dev). Resolved empirically: `GET https://qastore.vtexcommercestable.com.br/api/saved-cards/credit-card` returns a clean `401` with `x-vtex-janus-router-backend-app: saved-cards-v0.0.7-prd-005` and an RFC 9110 `ProblemDetails` body matching the service's own `AddProblemDetails()` wiring — i.e., the request reaches the real, live `saved-cards` production app through the standard account-scoped commerce host. (`.../meta/healthcheck` on the same host hits an unrelated legacy VTEX Portal redirect quirk and returns a misleading `400` from a different, older subsystem — not evidence against this host; the `credit-card` route is the reliable probe.)
+- **Decision**: Use `https://{account}.vtexcommercestable.com.br/api/saved-cards` as the base URL, with `{account}` resolved the same way the plugin already resolves `storeConfig.api.storeId` for its other clients.
+- **Consequences**: No infra/team confirmation needed before implementation; the base URL can be added to `src/features/shared/utils/api.ts` following the existing `getApiUrl`/`getTokenizationUrl` pattern.
+
+### Implementation Plan
+
+1. **Add `SavedCardsClient`** (session/add/list/delete), forwarding `VtexIdclientAutCookie` (as today) plus the new `Vtex_session` header (Decision 3); no `Authorization: Bearer` needed (Decision 4); base URL per Decision 5.
+3. **Repoint the four service functions** (`getPaymentSessionService`, `saveCreditCardService`, `getCreditCardsListService`, `deleteCreditCardService`) to the new client; leave `getCreditCardValidatorsService` and default-value services untouched.
+4. **Treat `cardLabel` as optional** in `CreditCardData` (the existing fallback covers cards saved without a nickname; verify no code path assumes the field is always present).
+5. **Resolve Decision 7 (CORS) before anything else ships** — `register` and `delete` are confirmed non-functional as implemented. Choose and implement either a `saved-cards`-side CORS fix or a same-origin proxy route in this plugin.
+6. **Re-validate `register` and `delete` live** with a real buyer session after Decision 7 lands — do not trust unit tests or UI toasts alone (see Decision 6); confirm the actual network call reaches `saved-cards` and returns a real response.
+7. Also confirm behavior for a buyer without `UseAdHocCard` and a forced `saved-cards` 502.
+6. **Add a `CHANGELOG.md` entry** under `[Unreleased]` describing the backend swap (merchant-visible only insofar as error behavior or the missing card label could surface — otherwise mark as internal-only per repo convention).
+
+---
+
+## 3. Technical Contract
+
+### Data Models
+
+From the `saved-cards` TypeSpec contract (`.vtex/definitions/models/*.tsp`):
+
+```
+PaymentSession {
+  id: string
+  name: string
+  expiresAt: utcDateTime
+}
+
+PaymentTokenRequest {
+  creditCardToken: string
+  paymentSystem: string
+}
+
+AddCardRequest {
+  token: PaymentTokenRequest
+  recaptchaV3Token: string
+}
+
+PaymentFieldResponse {
+  name: string
+  value: string
+}
+
+AddCardResponse {
+  status: string
+  paymentSystemId?: string
+  accountId?: string
+  transactionId?: string
+  paymentField?: PaymentFieldResponse[]
+}
+
+CreditCard {
+  accountId: string (uuid)
+  bin: string (max 6 chars)
+  cardNumber: string
+  cardLabel?: string
+  paymentSystem: string
+  paymentSystemName: string
+  isDefault: boolean
+  isActive: boolean
+}
+```
+
+Note: `cardLabel` is optional — `saved-cards` omits it for cards saved without a nickname. See [Non-Functional Requirements](#non-functional-requirements).
+
+### Interfaces
+
+All four operations are rooted at `/api/saved-cards` and require the auth described in [Integration Points](#integration-points).
+
+| Operation | Method & Path | Query | Request Body | Success Response | Typed Errors |
+|---|---|---|---|---|---|
+| Get payment session | `GET /payments/session` | `?an={account}` | — | `200 PaymentSession` | `502 DownstreamError` |
+| Add credit card | `POST /credit-card` | `?an={account}` | `AddCardRequest` | `200 AddCardResponse` | `400 PaymentTokenRequiredError`, `400 SessionRequiredError`, `422 TransactionDeniedError`, `500 CardSaveFailedError`, `502 DownstreamError` |
+| List credit cards | `GET /credit-card` | `?an={account}` | — | `200 CreditCard[]` | `502 DownstreamError` |
+| Delete credit card | `DELETE /credit-card/{tokenId}` | `?an={account}` | — | `204 No Content` | `404 CardNotFoundError`, `502 DownstreamError` |
+
+All four operations also return `401 Unauthorized` when authentication is missing/invalid (verified directly against the service's integration tests).
+
+### Integration Points
+
+- **Base URL**: `https://{account}.vtexcommercestable.com.br/api/saved-cards` — confirmed empirically against the live production service (Decision 5). The Postman collection's `http://localhost:5001` remains valid for local dev only.
+- **Account resolution**: `?an={account}` query parameter, using the same `storeConfig.api.storeId` value the plugin already resolves today (`getApiUrl`/`getTokenizationUrl` pattern in `src/features/shared/utils/api.ts`).
+- **Identity resolution**: `customerId` and `unitId` are **no longer passed explicitly** by the client — `saved-cards` derives them from the authenticated identity (decoded from the auth cookie/token) via its own `RequestContextResolver`. The client only needs to ensure the auth headers below are present and correct; it does not need to know or forward `customerId`/`unitId` for these four calls.
+- **Required headers**:
+  - `Cookie: VtexIdclientAutCookie=<token>` — already sent by the plugin today via `getAuthFromCookie`; confirmed (Decision 4) to be sufficient on its own for authentication.
+  - `Vtex_session: <token>` — **new**, sourced from the raw `vtex_session` browser cookie; required specifically by the add-card operation (`400 SESSION_REQUIRED` if missing, confirmed from source), sent on all four calls for consistency.
+  - `Authorization: Bearer` — **not required** (Decision 4); no change needed here.
+- **Downstream trust boundary**: `saved-cards` never forwards the buyer's inbound `Authorization`/`VtexIdclientAutCookie` to its own downstream calls (Checkout, Gateway, Profile, MasterData) — it uses its own service credentials. This is internal to `saved-cards` and requires no action from the plugin.
+- **Tokenization boundary (unchanged)**: `TokenClient` continues to call `https://{account}.vtexpayments.com.br/api/pub/sessions/{paymentSession}/tokens` directly — this is not part of the `saved-cards` integration.
+- **BFF boundary (unchanged)**: validators (`GET .../credit-cards/validators`) and default-value management (`POST`/`DELETE .../default-values`) continue to call `buyer-portal-graphql` via the existing `CreditCardClient`/`DefaultValuesClient`.
+
+### Invariants & Constraints
+
+- No card PAN, CVV, or expiration date is ever included in any request to `saved-cards` — only the opaque `creditCardToken` produced by the existing tokenization step.
+- The `Vtex_session` header value is never logged, and the shared `getCookieWithoutSessionObjects` utility's existing stripping behavior for other (BFF) calls is not altered by this change.
+- This migration touches exactly the four operations listed in [Interfaces](#interfaces); validators and default-value management are explicitly out of scope and must keep functioning against the BFF unchanged.
+- The identifier passed as `tokenId` on delete is the same `accountId` value the UI already uses today (from the list response) — no new identifier concept is introduced.

package/src/features/credit-cards/clients/SavedCardsClient.ts

@@ -0,0 +1,78 @@
+import { Client } from "../../shared/clients/Client";
+import { getAccountName, getSavedCardsUrl } from "../../shared/utils";
+import { getVtexSessionFromCookie } from "../utils";
+
+import type {
+  AddCardRequest,
+  AddCardResponse,
+  CreditCardData,
+  PaymentSession,
+} from "../types";
+
+type SavedCardsContext = {
+  cookie: string;
+};
+
+/**
+ * Client for the `saved-cards` microservice (see
+ * specs/credit-card-saved-cards-migration.md). Covers the four operations
+ * `saved-cards` implements today: payment session, add card, list cards,
+ * delete card. Validators and default-value toggling stay on the BFF via
+ * `CreditCardClient`/`DefaultValuesClient` — this client does not cover them.
+ *
+ * Auth: forwards `VtexIdclientAutCookie` as today, plus a dedicated
+ * `Vtex_session` header sourced from the raw `vtex_session` cookie value
+ * (Decision 3) — required by the add-card endpoint. No `Authorization:
+ * Bearer` header is sent (Decision 4, verified empirically against the live
+ * service).
+ */
+export default class SavedCardsClient extends Client {
+  constructor() {
+    super(getSavedCardsUrl());
+  }
+
+  private buildHeaders(cookie: string) {
+    return {
+      Cookie: cookie,
+      Vtex_session: getVtexSessionFromCookie(cookie),
+    };
+  }
+
+  private buildParams() {
+    return { an: getAccountName() };
+  }
+
+  getPaymentSession({ cookie }: SavedCardsContext) {
+    return this.get<PaymentSession>("/payments/session", {
+      headers: this.buildHeaders(cookie),
+      params: this.buildParams(),
+    });
+  }
+
+  addCreditCard(data: AddCardRequest, { cookie }: SavedCardsContext) {
+    return this.post<AddCardResponse, AddCardRequest>("/credit-card", data, {
+      headers: this.buildHeaders(cookie),
+      params: this.buildParams(),
+    });
+  }
+
+  listCreditCards({ cookie }: SavedCardsContext) {
+    return this.get<CreditCardData[]>("/credit-card", {
+      headers: this.buildHeaders(cookie),
+      params: this.buildParams(),
+    });
+  }
+
+  deleteCreditCard(tokenId: string, { cookie }: SavedCardsContext) {
+    return this.request<void, never>({
+      url: `/credit-card/${tokenId}`,
+      method: "DELETE",
+      headers: this.buildHeaders(cookie),
+      params: this.buildParams(),
+    });
+  }
+}
+
+const savedCardsClient = new SavedCardsClient();
+
+export { savedCardsClient };

package/src/features/credit-cards/clients/__tests__/SavedCardsClient.test.ts

@@ -0,0 +1,120 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("discovery.config", () => ({
+  default: {
+    api: { storeId: "test-store" },
+    secureSubdomain: "https://test.vtex.com",
+  },
+}));
+
+// The shared/utils barrel re-exports React components — mock it to avoid
+// loading React in the Node test environment.
+vi.mock("../../../shared/utils", () => ({
+  getSavedCardsUrl: () =>
+    "https://test-store.vtexcommercestable.com.br/api/saved-cards",
+  getAccountName: () => "test-store",
+}));
+
+import { savedCardsClient } from "../SavedCardsClient";
+
+const mockCookie =
+  "VtexIdclientAutCookie_test-store=auth-token;vtex_session=session-token-xyz";
+
+function makeFetchMock(body: unknown, status = 200) {
+  return vi.fn().mockResolvedValue({
+    ok: status >= 200 && status < 300,
+    status,
+    statusText: status >= 200 && status < 300 ? "OK" : "Error",
+    headers: { get: () => "application/json" },
+    json: () => Promise.resolve(body),
+  });
+}
+
+describe("SavedCardsClient", () => {
+  beforeEach(() => {
+    vi.stubGlobal("fetch", makeFetchMock({}));
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  describe("getPaymentSession", () => {
+    it("calls GET /payments/session with ?an={account} against the saved-cards host", async () => {
+      const mockSession = {
+        id: "session-1",
+        name: "sess",
+        expiresAt: "2026-07-27T00:00:00Z",
+      };
+      vi.stubGlobal("fetch", makeFetchMock(mockSession));
+
+      const result = await savedCardsClient.getPaymentSession({
+        cookie: mockCookie,
+      });
+
+      const [url] = (fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(url).toBe(
+        "https://test-store.vtexcommercestable.com.br/api/saved-cards/payments/session?an=test-store"
+      );
+      expect(result).toEqual(mockSession);
+    });
+
+    it("sends the VtexIdclientAutCookie cookie and a Vtex_session header sourced from the raw vtex_session cookie", async () => {
+      vi.stubGlobal("fetch", makeFetchMock({}));
+
+      await savedCardsClient.getPaymentSession({ cookie: mockCookie });
+
+      const [, config] = (fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(config.headers?.Vtex_session).toBe("session-token-xyz");
+      expect(config.headers?.Cookie).toBe(mockCookie);
+    });
+
+    it("does not send an Authorization header", async () => {
+      vi.stubGlobal("fetch", makeFetchMock({}));
+
+      await savedCardsClient.getPaymentSession({ cookie: mockCookie });
+
+      const [, config] = (fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(config.headers?.Authorization).toBeUndefined();
+    });
+  });
+
+  describe("addCreditCard", () => {
+    it("POSTs to /credit-card with ?an={account} and the AddCardRequest body", async () => {
+      const mockResponse = { status: "APPROVED", accountId: "card-1" };
+      vi.stubGlobal("fetch", makeFetchMock(mockResponse));
+
+      const requestBody = {
+        token: { creditCardToken: "tok-123", paymentSystem: "visa" },
+        recaptchaV3Token: "recaptcha-abc",
+      };
+
+      const result = await savedCardsClient.addCreditCard(requestBody, {
+        cookie: mockCookie,
+      });
+
+      const [url, config] = (fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(url).toBe(
+        "https://test-store.vtexcommercestable.com.br/api/saved-cards/credit-card?an=test-store"
+      );
+      expect(config.method).toBe("POST");
+      expect(JSON.parse(config.body as string)).toEqual(requestBody);
+      expect(result).toEqual(mockResponse);
+    });
+
+    it("sends the Vtex_session header on register too", async () => {
+      vi.stubGlobal("fetch", makeFetchMock({}));
+
+      await savedCardsClient.addCreditCard(
+        {
+          token: { creditCardToken: "tok", paymentSystem: "visa" },
+          recaptchaV3Token: "r",
+        },
+        { cookie: mockCookie }
+      );
+
+      const [, config] = (fetch as ReturnType<typeof vi.fn>).mock.calls[0];
+      expect(config.headers?.Vtex_session).toBe("session-token-xyz");
+    });
+  });
+});

package/src/features/credit-cards/components/CreditCardDropdownMenu/CreditCardDropdownMenu.tsx

@@ -8,6 +8,7 @@ import { useDrawerProps } from "../../../shared/hooks";
 import { useLocalization } from "../../../shared/localization/LocalizationContext";
 import { useSetDefaultCreditCard } from "../../hooks/useSetDefaultsCreditCard";
 import { useUnsetDefaultCreditCard } from "../../hooks/useUnsetDefaultsCreditCard";
+import { getCreditCardDisplayName } from "../../utils";
 
 import type { CreditCardData } from "../../types";
 
@@ -158,7 +159,7 @@ export const CreditCardDropdownMenu = ({
       {isOpenDeleteDrawer && (
         <DeleteCreditCardDrawer
           readonly
-          cardName={currentCreditCard.cardLabel}
+          cardName={getCreditCardDisplayName(currentCreditCard)}
           cardId={currentCreditCard.accountId}
           isOpen={isOpenDeleteDrawer}
           {...deleteDrawerProps}

package/src/features/credit-cards/layouts/CreditCardsLayout/CreditCardLayout.tsx

@@ -23,6 +23,7 @@ import {
 import { CreditCardSettingsDrawer } from "../../components/CreditCardSettingsDrawer/CreditCardSettingsDrawer";
 import { useChangeCardScope } from "../../hooks";
 import { useGetCreditCards } from "../../hooks/useGetCreditCards";
+import { getCreditCardDisplayName } from "../../utils";
 
 import type { CreditCardData } from "../../types";
 
@@ -164,7 +165,7 @@ export const CreditCardLayout = ({ data }: CreditCardsLayoutProps) => {
                     <Table.Row
                       iconName="CreditCard"
                       iconSize={24}
-                      title={creditCard.cardLabel ?? creditCard.cardNumber}
+                      title={getCreditCardDisplayName(creditCard)}
                       actionIcons={renderRowActions(creditCard)}
                       dropdownMenu={
                         <CreditCardDropdownMenu