API References

Card Reveal

Display card details in your UI through Basis Theory secure elements, without the raw card data ever touching your servers or application code.

Overview

The card reveal flow lets an end user view their card details (card number, expiry, and optionally CVC) directly in your UI without your backend ever receiving the raw card data as plaintext.

Sensitive cardholder data never touches your servers or application code, which significantly reduces your PCI DSS compliance scope. Basis Theory is PCI DSS Level 1 certified.

The flow relies on the SAVA BaaS API svc.card.{partner}.authorize_reveal endpoint and Basis Theory's secure elements. The Basis Theory public key will be shared with you securely during onboarding.

Your integration has two parts:

  • Frontend: Initialize Basis Theory, create a session, render secure card elements, and display the card data.
  • Backend: Authenticate with SAVA and authorize the reveal session.

Replaces get_details

Card reveal replaces the Get Card Details endpoint, which returns the PAN, expiry, and CVV as plaintext to your backend and puts that data inside your PCI scope. Use card reveal to show the same details to the end user without ever handling the plaintext yourself.

What is Basis Theory

Basis Theory is a third-party tokenization and secure data platform. In this integration, it plays a specific role:

  • SAVA stores card data in Basis Theory as tokens.
  • Basis Theory provides secure UI components called Elements that can display sensitive data without exposing it to your application code.
  • When a reveal is authorized, Basis Theory renders the card values inside its own secure views so that the actual card number, expiry, and CVC are never accessible to your code.

This means your frontend displays the card data to the end user, but your application never has access to the plaintext values.

How the systems interact

End UserPartner FrontendBT ElementsPartner Backendpartner JWTSAVA BaaS APIauthorize_revealBasis Theoryopen card detailsinitialize with public key, create sessionnonce + sessionKeynonce + account_id + card_idauthorize_revealauthorize session with reveal transformauthorization OKtoken_idtoken_idretrieve token with sessionKeysecure reveal referencescard rendered in secure elements

The frontend creates a Basis Theory session and hands the nonce to the backend, which calls SAVA's authorize_reveal. SAVA authorizes the session with Basis Theory and returns a token_id. The frontend retrieves the token with its sessionKey and Basis Theory renders the card values inside its secure elements, so the plaintext never touches partner code.

  • The partner frontend runs Basis Theory Elements in the client application. It creates sessions, renders card elements, and displays the revealed data to the end user.
  • The partner backend authenticates to SAVA using a partner JWT, calls authorize_reveal, and passes orchestration values back to the frontend.
  • SAVA BaaS API validates that the partner owns the account and card, authorizes the Basis Theory session, and returns the token_id.
  • Basis Theory stores the card token, manages the session authorization, and renders the sensitive card values inside secure elements.

Keys, tokens, and where they belong

ItemWhat it isWhere it belongs
BT public keyFrontend-safe Basis Theory keyPartner frontend only
BT private keySecret Basis Theory API keySAVA only
nonceOne-time session identifierCreated in partner frontend, forwarded through partner backend to SAVA
sessionKeyTemporary session credentialPartner frontend only, never send to your backend
token_idAuthorized token reference for card revealReturned by SAVA, forwarded through partner backend to partner frontend

Session details

  • bt.sessions.create() returns both a sessionKey and a nonce
  • The nonce is a one-time use code. It authorizes the session and cannot be reused.
  • The sessionKey stays in the frontend and is used to retrieve the token from Basis Theory

Practical guidance:

  • Create the session immediately before reveal
  • Use the nonce once
  • Treat the session authorization as expiring after 5 minutes
  • Complete the SAVA authorization and token retrieval right away

Creating a session for testing

Use the Basis Theory Postman collection and run the Sessions Create request (POST /sessions) to create a session for auth reveal testing. You can also use the Basis Theory Sessions API for the Create Session request.

Authorize Reveal

Authorize a Basis Theory session for card reveal. Call this after the frontend has created a Basis Theory session and obtained a nonce.

Subject: svc.card.{partner_id}.authorize_reveal

Request

AuthorizeRevealRequest
{
  "account_id": "8f5f4f2b-8d41-4b56-9a57-5a8739e21d11",  // Required: account ID (UUID)
  "card_id": "2c8ec0ab-4d8d-4f45-b6a8-3f2d9b5a6c77",     // Required: card ID (UUID)
  "nonce": "fresh-basis-theory-session-nonce"             // Required: fresh session nonce from the frontend
}
FieldTypeRequiredDescription
account_idstringrequiredAccount ID (UUID)
card_idstringrequiredCard ID (UUID)
noncestringrequiredOne-time session nonce returned by the Basis Theory session created in your frontend

Response

AuthorizeRevealResponse
{
  "token_id": "5a3e9b72-7f26-4f8a-91d3-6c4ab8e5f902"  // UUID of the authorized card token
}
FieldTypeDescription
token_idstringAuthorized token reference (UUID). Forward it to your frontend to retrieve the token from Basis Theory

What SAVA does

When SAVA receives this request, it:

  1. Verifies that the card belongs to the supplied account
  2. Verifies that the authenticated partner owns that account
  3. Verifies that the card is eligible for reveal
  4. Ensures the card has a Basis Theory token
  5. Authorizes the supplied session nonce for reading that token with a reveal transform

What the partner implements: frontend

This section covers what you need to build on the frontend to display card data using Basis Theory Elements.

Basis Theory provides platform-specific SDKs with secure UI elements for rendering sensitive card data. Your application code never has access to the plaintext values. Basis Theory renders them inside secure views.

Basis Theory SDK documentation

Refer to the official Basis Theory documentation for your platform for full setup, installation, element configuration, and styling:

PlatformSDK DocsPackage
iOSdevelopers.basistheory.com/docs/sdks/mobile/iosBasisTheoryElements
Androiddevelopers.basistheory.com/docs/sdks/mobile/androidbasis-theory-android
React Nativedevelopers.basistheory.com/docs/sdks/mobile/react-native@basis-theory/react-native-elements

The Basis Theory Display Cards guide walks through the full card reveal implementation for each platform.

Secure card elements

Basis Theory provides three secure UI elements for displaying card data:

ElementWhat it displays
CardNumberElementFull card number (PAN)
CardExpirationDateElementExpiry month and year
CardVerificationCodeElementCVC / CVV

All three should be set to read-only since they are for display only.

The reveal flow from the frontend

Regardless of platform, the steps are the same:

Initialize Basis Theory

Initialize the SDK with the public key provided during onboarding, and add the three card elements to your screen.

Create a session

Create a Basis Theory session, which returns a nonce and a sessionKey. The sessionKey stays in the frontend.

session = basisTheory.sessions.create()

Authorize the reveal through your backend

Send the nonce along with account_id and card_id to your backend. Your backend calls SAVA's authorize_reveal and returns the token_id.

token_id = yourBackend.authorizeReveal(
    nonce:      session.nonce,
    account_id: accountId,
    card_id:    cardId,
)

Retrieve the token and render

Use the token_id and sessionKey to retrieve the token from Basis Theory, then set the retrieved data into the card elements using setValue.

token = basisTheory.tokens.retrieve(
    token_id,
    sessionKey: session.sessionKey,
)
 
cardNumberElement.setValue(token.data.number)
cardExpirationDateElement.setValue(
    token.data.expiration_month,
    token.data.expiration_year,
)
cardVerificationCodeElement.setValue(token.data.cvc)

Secure references, not plain strings

The token retrieve call does not return plain strings. The data fields are secure references that only Basis Theory Elements can render. You pass them into the elements using setValue and Basis Theory handles the display.

How SAVA fits into the Basis Theory flow

The only SAVA-specific part in the frontend flow is step 3. After creating a Basis Theory session, your frontend sends the nonce, account_id, and card_id to your backend. Your backend calls SAVA's authorize_reveal and returns the token_id. From that point on, the rest follows the standard Basis Theory token retrieval and element display pattern documented in their SDK guides.

For the full implementation in your platform, follow the Basis Theory Display Cards guide linked above.

References