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
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
| Item | What it is | Where it belongs |
|---|---|---|
| BT public key | Frontend-safe Basis Theory key | Partner frontend only |
| BT private key | Secret Basis Theory API key | SAVA only |
nonce | One-time session identifier | Created in partner frontend, forwarded through partner backend to SAVA |
sessionKey | Temporary session credential | Partner frontend only, never send to your backend |
token_id | Authorized token reference for card reveal | Returned by SAVA, forwarded through partner backend to partner frontend |
Session details
bt.sessions.create()returns both asessionKeyand anonce- The
nonceis a one-time use code. It authorizes the session and cannot be reused. - The
sessionKeystays 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
| Field | Type | Required | Description |
|---|---|---|---|
account_id | string | required | Account ID (UUID) |
card_id | string | required | Card ID (UUID) |
nonce | string | required | One-time session nonce returned by the Basis Theory session created in your frontend |
Response
| Field | Type | Description |
|---|---|---|
token_id | string | Authorized token reference (UUID). Forward it to your frontend to retrieve the token from Basis Theory |
What SAVA does
When SAVA receives this request, it:
- Verifies that the card belongs to the supplied account
- Verifies that the authenticated partner owns that account
- Verifies that the card is eligible for reveal
- Ensures the card has a Basis Theory token
- Authorizes the supplied session
noncefor 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:
| Platform | SDK Docs | Package |
|---|---|---|
| iOS | developers.basistheory.com/docs/sdks/mobile/ios | BasisTheoryElements |
| Android | developers.basistheory.com/docs/sdks/mobile/android | basis-theory-android |
| React Native | developers.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:
| Element | What it displays |
|---|---|
CardNumberElement | Full card number (PAN) |
CardExpirationDateElement | Expiry month and year |
CardVerificationCodeElement | CVC / 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.
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.
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.
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
- SAVA API Docs: SAVA BaaS API docs
- Basis Theory Docs: developers.basistheory.com
- BT Display Cards Guide: developers.basistheory.com/docs/card-issuing/display-cards
- BT iOS SDK: developers.basistheory.com/docs/sdks/mobile/ios
- BT Android SDK: developers.basistheory.com/docs/sdks/mobile/android
- BT React Native SDK: developers.basistheory.com/docs/sdks/mobile/react-native
- SAVA Support: Contact your SAVA integration engineer for environment access, JWT setup, and onboarding