> ## Documentation Index
> Fetch the complete documentation index at: https://developer.hellgate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Commerce v2 Updates

> New releases and improvements of Commerce v2.

<Update label="July 31, 2026" tags={["Improvement"]}>
  ## Corrected Status Code for Token Sessions

  [Request a token session](/products/commerce/v2/api-reference/tokens_create/request-a-token-session)
  is now documented as returning **201 Created**. The endpoint has always
  responded 201 — the API reference said 200, which was wrong. Nothing about the
  endpoint changed, and the response body is the same `session_id` it always was.

  If your integration asserts on the status code, assert 201 here. The related
  [Refresh CVC2](/products/commerce/v2/api-reference/tokens_management/refresh-cvc2)
  endpoint returns a plain 200 and is unaffected.

  ## Card Art and Metadata Refresh Are Documented

  Three endpoints that Commerce v2 already served are now part of the API
  reference. Their behaviour is unchanged — only the documentation is new.

  * **[Get card art](/products/commerce/v2/api-reference/tokens_management/get-card-art)**
    returns the issuer's card art for a token as a base64-encoded image, in the
    same shape Guardian uses for network tokens.
  * **[Download card art](/products/commerce/v2/api-reference/tokens_management/download-card-art)**
    returns the image itself. This is what the `card_art_url` attribute on a token
    points at. It takes no API key, so the URL can be rendered directly by a
    browser. Use the URL as it is given to you: the ID in the path identifies the
    card art, not the token.
  * **[Refresh token metadata](/products/commerce/v2/api-reference/tokens_management/refresh-token-metadata)**
    re-runs the issuer inquiry for a token and returns the updated token, which
    can change `bank_name`, `segment`, `type`, `currency_code`, `country_code`,
    `issuer_identification_number` and `scheme`. This endpoint was announced in
    May but never had a reference page — it now does.

  `card_art_url` is also documented as nullable, which it always was — it is
  `null` when the issuer provides no card art.
</Update>

<Update label="July 15, 2026" tags={["New Release", "Improvement"]}>
  ## Raw Card Numbers Are Rejected Everywhere

  Commerce v2 is not a card data environment, and now enforces it: any API
  request body containing a raw card number (PAN) is rejected, on every
  endpoint. Card data belongs in your PCI-compliant tokenization flows — this
  guard keeps it from slipping into ordinary API calls by accident. Merchant
  identifier fields are exempt, since an acquirer-assigned ID can be
  indistinguishable from a card number.

  ## Improvements and bugfixes

  * Token responses handle a missing card art from Guardian gracefully instead
    of failing.
  * Accounts with the GPayments 3DS provider disabled now degrade gracefully
    instead of raising errors.
  * Updated dependencies to clear security advisories.
</Update>

<Update label="July 10, 2026" tags={["Improvement"]}>
  ## Improvements and bugfixes

  * Bulk card imports no longer emit duplicate `token.created` events.
  * Tokens created through PCI tokenization now pass their TTL through to
    Guardian, keeping token expiry consistent end to end.
  * Unexpected errors from the 3DS authentication provider now surface as
    readable failures instead of opaque errors.
  * Client headers are stripped before forwarding requests to Guardian,
    fixing intermittent `504` responses.
  * The Test tier network simulation now returns the dynamic CVV for American
    Express cards.
  * Request logs now mask API keys passed as query parameters.
</Update>

<Update label="June 29, 2026" tags={["Improvement"]}>
  ## Improvements and bugfixes

  * Network token forwarding is more resilient: Commerce now injects the
    destination URL from your KYC configuration when the client omits it.
  * Ephemeral session cards that are never saved no longer trigger network token
    creation, and an expired Guardian token is treated as already deleted when
    you tear a session down.
  * The 3DS admin path handles unexpected merchant responses gracefully instead
    of failing the request.
</Update>

<Update label="June 3, 2026" tags={["Maintenance"]}>
  ## PCI Control Adjustment

  Refined how merchant network token data is decrypted in composition with
  Guardian, keeping the data path aligned with our PCI DSS controls.
</Update>

<Update label="May 28, 2026" tags={["New Release", "Improvement"]}>
  ## Composing Commerce v2 with Guardian

  Advancing our [Composable Payment Architecture](/platform/cpa), Commerce v2 now
  composes natively with Guardian for network token data, cryptograms, and issuer
  metadata. Opt an account in with the new `guardian_cpa_mode` and
  `issuer_metadata_enabled` settings (alongside its `contract_id`): Commerce resolves
  cryptograms by reference through Guardian and surfaces each token's `expires_at`
  with the resolved token data. A new `POST /tokens/{id}/refresh-metadata` endpoint
  lets you refresh issuer metadata on demand instead of waiting for the next payment.

  ## User MFA Recovery

  A new endpoint revokes a user's multi-factor authentication, so you can reset
  MFA for a locked-out operator instead of escalating to support.

  ## Improvements and bugfixes

  * Token responses now include the `currency` field.
  * Clearer errors when retrieving payment data, plus a precise message when a
    `contract_id` exceeds the allowed length instead of an opaque bad request.
  * Unsupported network token creation now returns a readable error message.
  * 3DS requests now return a clean `502` when the upstream authentication
    provider's TLS handshake fails, instead of an ambiguous error.
  * Issuer metadata falls back to card scheme data when a lookup is disabled or
    unavailable, so scheme information is always populated.
  * Hardened data-request logging to never persist `x-api-key` or `authorization`
    headers, and restored a missing Content-Security-Policy header.
  * Updated dependencies to clear a security advisory.
</Update>

<Update label="March 11, 2026" tags={["New Release", "Maintenance"]}>
  ## Allowed Card Schemes per Account

  You can now restrict which card schemes are accepted on a given account or
  session. A new endpoint lets you configure the allow-list, sessions pick it up
  automatically, and the Web SDK validates it client-side before the cardholder
  even hits submit. Great for merchants with acquirer- or region-specific
  scheme constraints.

  ## Improvements and bugfixes

  * Sub-merchants can now only see their own payment data — tightened scoping
    across reads.
  * Hardened against several `500` paths: invalid UUIDs in API-logs queries,
    missing required fields on authentication installments, Guardian
    authentication-failed responses, and oversized AOC document links.
  * Network token decline reports and scheme-percentage views render
    consistently for accounts with allowed-schemes configured.
</Update>

<Update label="February 27, 2026" tags={["New Release", "Maintenance"]}>
  ## Network Token Statistics and Details

  You now have deeper visibility into your network tokenization activity. New reporting
  endpoints let you export BIN statistics as CSV, review declined network tokenizations,
  and access a token activity summary — giving you the data you need to monitor
  performance and troubleshoot issues.

  Token filtering has also been extended to support lookup by token ID or last four digits,
  making it easier to find specific tokens.

  ## Improvements and bugfixes

  * Webhooks no longer fire when there are no changes to a token.
  * Fixed a date format issue in 3DS session context.
  * Ecosystem accounts and sub-merchants can now execute proxy forwards.
  * Improved error handling for Guardian serialization errors and unknown tokens.
</Update>

<Update label="January 29, 2026" tags={["New Release", "Maintenance"]}>
  ## Introduction of Generic Tokens

  With the rollout of TMS support on Guardian, Commerce v2 now supports this tokenization backend as well.

  ## Bugfix

  * Improved the SDK session protocol against unexpected data and up-stream errors.
</Update>

<Update label="December 19, 2025" tags={["Maintenance"]}>
  ## Bugfixes

  * Improved session error handling on CDE import.
  * Handle card-art corner cases for some issuers.
  * Handle BIN data gracefully when missing some attributes.
</Update>

<Update label="October 6, 2025" tags={["New Release", "Maintenance"]}>
  ## Deterministic TPANs

  We added support for deterministic TPANs (Token PAN) on the Network Token Sandbox. This is a great help for developers to test
  their integration with consistent data.

  ## Payment Splits are generally available

  We rolled out payment splits for all our customers on the platform operating model.
  This allows you to split the payment amount between multiple accounts.

  ## Improvements and bugfixes

  * Better error messages on invalid payloads for session completion (specifically encrypted CHD payloads)
  * Wider support of metadata in requests.
  * Fixed issuer metadata retrieval for cards without default currency.
  * Support more exotic cardart data from issuers.
</Update>

<Update label="August 29, 2025" tags={["New Release", "Maintenance"]}>
  ## Templating

  * We added a new filter last(n) to the forwarding templates.

  ## Improvements and bugfixes

  * We optimized the performance of our authentication subsystem, which makes literally every API interaction just faster.
  * Apply correct scoping of sub-merchant level API keys.
  * Fix issues with certain compliance proxy forwards.
</Update>

<Update label="August 8, 2025" tags={["New Release", "Maintenance"]}>
  ## Bring your own Guardian

  Mix and match - Use your own dedicated Guardian in Commerce setups.

  ## Bugfix

  * Fixed the replenishment of encryption keys for account owners on eco-system operating model.
</Update>

<Update label="July 7, 2025" tags={["New Release"]}>
  ## Hello CPA 👋

  July has been nothing short of monumental for the Hellgate® engineering team – and we’re beyond thrilled to finally unveil what we’ve been building behind the scenes.

  Say hello to the next generation of payment innovation: [The Composable Payment Architecture](/platform/cpa).

  ### Built for Seamless Integration

  With CPA, we’re rewriting the rules of payment technology. Hellgate® is no longer just a powerful platform – it’s a composable,
  integratable powerhouse. We're opening up our legendary "secret sauce" to empower developers, partners, and innovators everywhere.

  Think modular. Think agile. Think tailor-made payments infrastructure.

  We're rolling out these new services step by step – purpose-built for scalability, flexibility, and collaboration. It's everything you
  love about Hellgate, now available piece by piece for maximum integration and innovation.

  ### Hellgate Evolves: Introducing Hellgate Commerce

  We’re all-in on the orchestration journey.

  Say hello to Commerce – your full-stack command center for modern payments. We’re pushing the limits of productivity, control, and
  performance in every update. The name is new, but our commitment to excellence remains stronger than ever.

  ### Meet Guardian CPA: Power Meets Privacy

  Kicking off our Early Access Program is Guardian – the cornerstone of CPA. Guardian delivers a fully managed PCI DSS-compliant cardholder
  data vault, so you can store sensitive data with confidence and speed.

  Need more control? We’ve got you covered with private Guardian deployments, bringing top-tier data privacy and security directly to your
  Commerce environment.
</Update>