Card Issuing
Card Reveal
Overview
Cardholders may need their full card details to use a card: to pay online before a physical card arrives, to add a card to a wallet or a merchant account by hand, or to remember a forgotten PIN at an ATM. Card reveal lets Column partners show those details to their cardholders inside the partner's own web or mobile app: the full card number, CVV2, expiration date and cardholder name, and, for programs that enable it, the card's PIN.
Partners add card reveal with Column's SDKs: @column-na/card-reveal for web pages and
@column-na/card-reveal-react-native for React Native and Expo apps. The card data goes straight from Column to the
SDK and is displayed in components Column controls, so it never passes through the partner's servers, code or logs.
Showing card details this way doesn't bring the partner's systems into PCI scope. The partner stays in control of
who can see which card, and of how the details look in their app.
How It Works
A reveal involves three parties: the SDK running in the partner's page or app, the partner's server, and Column.
- The cardholder asks to see their card. The SDK prepares the reveal by generating a one-time encryption key
(
prepareReveal()). The private half of the key never leaves the SDK; the partner's app only gets the key's thumbprint, a short fingerprint that isn't secret. - The app asks the partner's server for permission. It sends the card ID and the key's thumbprint to an endpoint on the partner's server.
- The partner's server approves the reveal. It checks that the signed-in user may see the card, then uses the partner's API key to create a reveal token with Column, bound to the thumbprint. It returns only the token's ID to the app.
- The SDK requests the card details from Column. It sends the token and its public key directly to Column. Column checks that the token is valid, unused, unexpired, for this card, and bound to this key.
- Column returns the details, encrypted, and the SDK displays them. Column encrypts the card details end to end to
the SDK's one-time key, so nothing in between can read them. The SDK decrypts and displays them: on the web, each
value in its own iFrame served by Column from
https://reveal.column.com; in React Native, in the SDK's own text component. Either way, the partner's code can't read the values. - Column records the reveal. It notes which details were shown, never their values, and sends the partner an
issuing.card_reveal_token.consumedwebhook. See Audit Reveals.
Because each token is bound to the SDK's key, a token that leaks from the partner's logs or page is useless to anyone else: Column rejects any reveal that sends a different key.
Enable Card Reveal
- Install the SDK. Add the web SDK or the React Native SDK, pinned to an exact version. On the web, allow Column's reveal frame in the partner's Content Security Policy.
- Turn on PIN reveal, if needed. PIN reveal is off by default. Partners ask their Column representative to enable it for a card program. See Reveal a PIN.
- Add a server endpoint that creates reveal tokens. See Create a Reveal Token.
- Show the card in the app. Prepare the reveal, get a token from that endpoint, and display the chosen details. See Web or React Native.
- Test in sandbox, then go live. Create the SDK client with
environment: 'sandbox'and reveal a sandbox card, created with Card Sandbox Simulation. When the flow works, switch the client toenvironment: 'live'and create tokens with the partner's live API key. - Monitor reveals (optional). Subscribe to the
issuing.card_reveal_token.consumedevent, or use list card reveals.
Reveal Tokens
A reveal token is the partner's approval for one reveal. Each token:
- is created by the partner's server with its API key, never by the browser or app;
- works once, for one card, and expires one minute after it's created;
- is bound to the SDK's one-time key through
reveal_key_thumbprint, so only that reveal can use it.
Create a new token, after a new prepareReveal(), for every reveal. Only a successful reveal uses up the token: if a
reveal fails for any reason, the token still works until it expires.
Column doesn't check the card's status when it creates a token or reveals a card, so a paused or deactivated card
can still be revealed. If that matters, partners should check the card's status on their server before creating the
token.
The SDK's client.reveal() still accepts a token created without reveal_key_thumbprint, but Column will require
reveal_key_thumbprint on every reveal token. Use prepareReveal() for new integrations.
How It Works
- The SDK generates a one-time key for the reveal with
prepareReveal()and gives you itskeyThumbprint, a hash of the public key. Send it to your server. - Your server creates a single-use reveal token for the card with
create card reveal token, using your API key and that thumbprint, and sends
only the token's
idto the browser or app. The token works only with that key. - The SDK reveals the card with that token and calls Column's API directly. Column encrypts the card details end
to end to the one-time key, so nothing between Column and the SDK can read them.
- On the web, each value renders inside its own iframe, served by Column from
https://reveal.column.com. Your page's JavaScript can't read it. - In React Native, each value renders inside the SDK's own text component. No callback, ref or return value exposes it.
- On the web, each value renders inside its own iframe, served by Column from
A reveal token is valid for one minute and works once, for one card, with one SDK key. Create a new token for every reveal.
- Receive the card ID and
keyThumbprintfrom the app. The thumbprint is the 43-character valueprepareReveal()returned. - Authenticate and authorize the user. Confirm the signed-in user may see this card. For a PIN, also verify the cardholder again, for example with a one-time code or a biometric check.
- Create the token with create card reveal token, passing the thumbprint
as
reveal_key_thumbprint. - Return only the token's
idto the app.
Create the token right before you show the card, and only after you've checked that the signed-in user may see it.
Pass the keyThumbprint the SDK's prepareReveal() returned as reveal_key_thumbprint. It's required: a request
without it is rejected with invalid_field_value.
curl 'https://api.column.com/issuing/cards/<card_id>/reveal-tokens' \
-XPOST \
-u :<YOUR API KEY> \
-H 'Content-Type: application/json' \
-d '{"reveal_key_thumbprint": "<keyThumbprint>"}'{
"id": "crtk_2Z1qT1aB2cD3eF4gH5iJ6kL7mN8",
"card_id": "card_2Z1qT0kM6yX9wB3nV5cR8sL4pA7",
"expires_at": "2026-10-23T18:01:00Z",
"reveal_key_thumbprint": "NzbLsXh8uDCcd-6MNwXF4W_7noWXFZAfHkxZsRGC9Xs"
}The token works only for a reveal from the SDK that made that key. If someone else gets hold of the token, a reveal with any other key is rejected and the token stays usable for the cardholder. Pass the thumbprint through as the SDK gave it; your server doesn't need to check it.
Send the token id and the card ID to the browser or app. Don't call GET /issuing/cards/:card_id/reveal yourself.
The route is built for Column's SDKs: a reveal has to send the one-time public key whose thumbprint the token was
created with, and the response comes back encrypted to that key, so only the SDK that made the key can read it. The
SDK version each request carries lets Column retire old SDK versions; it isn't what protects the card data, the
key-bound token is. Fetching card details on your servers would put them in PCI scope.
Web
Install
Install from npm, pinned to an exact version:
npm install --save-exact @column-na/card-reveal@0.13.0Or load the hosted script, pinned to an exact version with
Subresource Integrity↗. The hosted
script won't create a client unless its <script> tag has an integrity attribute with a sha256-, sha384- or
sha512- hash, and it can't be loaded as a module script (type="module"). Each version is published once and never
changes.
<script
src="https://reveal.column.com/0.13.0/card-reveal.js"
integrity="sha384-Vm8MImzzB/4VZsRhJtm1A3fnKGCkEiAVaOf8Hn3cZqraami2IkslF9y2UJRbQVYw"
crossorigin="anonymous"
></script>0.13.0https://reveal.column.com/0.13.0/card-reveal.jssha384-Vm8MImzzB/4VZsRhJtm1A3fnKGCkEiAVaOf8Hn3cZqraami2IkslF9y2UJRbQVYwReveal a Card
import { createCardRevealClient, CardRevealError } from '@column-na/card-reveal';
// Hosted script: const { createCardRevealClient, CardRevealError } = window.ColumnCardReveal;
// Create one client and reuse it.
const client = createCardRevealClient({ environment: 'live' }); // or 'sandbox'
// Make the reveal's one-time key, then have your server create a reveal token bound to it.
const cardId = 'card_2Z1qT0kM6yX9wB3nV5cR8sL4pA7';
const prepared = await client.prepareReveal();
const revealToken = await myServer.createRevealToken(cardId, prepared.keyThumbprint); // 'crtk_...'
const { ready, unmount } = prepared.reveal({
cardId,
revealToken,
fields: {
pan: '#card-number',
cvv2: '#cvv2',
cardholder_name: '#name',
expiration_month: '#exp-month',
expiration_year: '#exp-year',
},
style: { color: '#fff', 'font-family': 'ui-monospace, monospace', 'font-size': '15px' },
fieldStyles: { pan: { 'font-size': '19px' } },
format: { pan: 'spaced', expirationYear: 'YY' },
});
try {
await ready;
} catch (error) {
if (CardRevealError.is(error)) showMessage(error.code);
}
// When the cardholder hides the card, or the page or component goes away:
unmount();Each field renders as an iframe that fills its container, so give each container a width and height. In React, use the React bindings, which handle the effect and its cleanup.
Every reveal needs a new prepareReveal() and a new token: a prepared key works for one reveal, and a token works
once. Until the reveal, prepareReveal() keeps the key in a hidden, zero-size frame from https://reveal.column.com
at the end of <body>; the key can't be read or exported, and only its thumbprint reaches your page. If the reveal
won't happen, for example because your server couldn't create the token, call prepared.discard() to drop the key and
remove its frame.
ready resolves once every field shows its value. If any field fails, or timeoutMs passes, ready rejects and
every field is removed: a reveal shows all of its fields or none of them. unmount() removes every field, and rejects
a pending ready with unmounted. Each prepared reveal works once; call prepareReveal() again for the next reveal.
React
@column-na/card-reveal/react runs the whole sequence for you: prepareReveal(), your server's token, the reveal,
and unmount on cleanup. It needs React 18 or later.
import { CardRevealProvider, CardRevealSlot } from '@column-na/card-reveal/react';
<CardRevealProvider
client={client}
cardId={cardId}
mintToken={({ cardId, keyThumbprint }) => myServer.createRevealToken(cardId, keyThumbprint)}
>
<CardRevealSlot field="pan" style={{ width: 280, height: 30 }} />
<CardRevealSlot field="cvv2" style={{ width: 60, height: 30 }} />
</CardRevealProvider>;mintToken({ cardId, keyThumbprint })asks your server for a token bound to the reveal's key and resolves with itsid. It's called once per reveal.<CardRevealSlot field="...">is an empty<div>that one field's frame fills, so give it a width and height.<CardRevealProvider>also takes the reveal optionsstyle,fieldStyles,formatandtimeoutMs, andenabled(defaulttrue;falseholds off the reveal, or removes a shown card).- Inside the provider,
useCardRevealState()returns{ status, error, retry }.statusis'idle','preparing','minting','revealing','ready'or'error'.retry()starts over with a new key and token. - Changing the card, slots or styles reveals again with a new key and token. Unmounting the provider unmounts the reveal and discards an unused key, including under Strict Mode's double mount.
useCardReveal({ client, cardId, mintToken, fields })does the same as a hook, withfieldsmapping each field to a CSS selector, if you'd rather manage the containers yourself.
Reveal Options
The web and React Native SDKs take the same options.
cardIdcard_...).revealTokencrtk_...) from the partner's server.fieldspan, cvv2, cardholder_name, expiration_month, expiration_year and pin to where it renders: a CSS selector on the web, a CardRevealText ref in React Native. Include only the fields to show. See Reveal a PIN for pin. Version 0.7.0 renamed cvv to cvv2; cvv now fails with invalid_options.style'&:hover', @media and @font-face blocks. In React Native, text styles.fieldStylesstyle. On the web, some styles are bounded; see Web styles.format.pan'spaced' (default, 4111 1111 1111 1111) or 'plain'.format.expirationYear'YYYY' (default) or 'YY'.timeoutMsready waits before it rejects with timeout. Default 15000, maximum 120000.hiddentrue reveals the fields masked (••••) until you call show(). Default false.autoHideMsready resolves, from 1 to 3600000.onAutoHideautoHideMs unmounts the reveal.copyabletrue, or per field ({ pan: true }), makes the field a copy button inside Column's frame. See Hide, Show and Copy. React Native throws invalid_options.onCopy{ field, copied } after each copy, where copied says whether the browser accepted it. Never the value. React Native throws invalid_options.Hide, Show and Copy
const reveal = prepared.reveal({
cardId,
revealToken,
fields: { pan: '#card-number', cvv2: '#cvv2' },
copyable: { pan: true },
onCopy: ({ field, copied }) => showToast(copied ? 'Card number copied' : "Couldn't copy"),
autoHideMs: 60_000,
onAutoHide: () => showRevealButton(),
});
hideButton.onclick = () => reveal.hide();
showButton.onclick = () => reveal.show();hide()andshow()mask every field in place (each character but spaces shows as•, so the layout stays) and show it again, without a new token or request. Both do nothing afterunmount()or a failure.hidden: truestarts the reveal masked.autoHideMsremoves the fields that long afterready, asunmount()does, and callsonAutoHideonce. Showing the card again needs a newprepareReveal()and token. Usehide()if the cardholder should be able to show it again.- Copy (web). A copyable field is a button inside Column's frame. A click, Enter or Space copies the value from
inside the frame, so it never passes through your page; you get only
onCopy({ field, copied }), and show your own confirmation. A card number is copied without spaces, and a hidden field doesn't copy. The control has the classcopyable, so a style can target it, for example'&.copyable:hover'or'&:focus-visible'. - Copy (React Native). The SDK has no native code, so it has no copy button:
copyableandonCopythrowinvalid_options. SetselectableonCardRevealTextto let the cardholder copy with the system text selection. A maskedCardRevealTextisn't selectable.
Web Styles
Styles apply inside Column's frame. A style can't be allowed to reveal anything about the values it displays, through the fonts the frame loads or how long a value takes to paint, so some styles are bounded. A style outside these bounds is dropped silently, and the reveal still succeeds.
Fonts. An @font-face src must either embed the font as a base64 data: URL, as
url(data:font/ttf;base64,...) format("truetype"), or name an installed font with local(...). A src that points
at a URL is dropped, and the frame never fetches it. An embedded font must be:
- plain TrueType (
.ttf); WOFF, WOFF2, OpenType CFF (.otf) and font collections are dropped; - unhinted, with no layout (
GSUB,GPOS,GDEF), colour or variation tables; - made of simple glyphs, with no composite glyphs, each drawn within its em box, with at most 600 points and 30 contours;
- at most 64 KB. A whole style, including its fonts, may be at most 256 KB.
A font that doesn't pass is dropped, and the text falls back to the next font in your font-family list, so always
list a fallback. The frame never synthesizes bold or oblique faces: declare a bold or italic @font-face if you want
one. ::first-letter and ::first-line blocks are refused.
To prepare a brand font, start from a static, monochrome TrueType (.ttf) and export a copy without hinting, layout,
colour or variation tables, limited to the characters you show. If your brand font is a variable font, first pin it to
one instance, for example fonttools varLib.instancer brand-variable.ttf wght=400 -o brand.ttf. Then, with
fontTools↗:
pyftsubset brand.ttf --flavor= --no-hinting --layout-features='' \
--drop-tables+=GSUB,GPOS,GDEF,DSIG,kern,COLR,CPAL,SVG,CBDT,CBLC,sbix,fvar,gvar,avar,cvar,HVAR,VVAR,MVAR,STAT \
--unicodes=U+0020-007E --output-file=brand-reveal.ttfThen decompose any composite glyphs the subset keeps, check the file is at most 64 KB, and embed it.
Other bounds:
font-sizeis clamped to 96px. Thefontshorthand,zoom,font-size-adjust,text-size-adjustandsize-adjustare refused.text-shadowandbox-shadowkeep at most two shadows, each with a blur of at most 8px; a value with more, a larger blur, or avar()orcalc()in it is dropped.filter,backdrop-filter,transformand its related properties (translate,rotate,scale,perspective),-webkit-text-stroke,text-emphasis,mask,paint-order,will-change,-webkit-box-reflect,font-synthesis,text-decoration-skip-inkandbackground-clip: textare refused. A vendor-prefixed spelling, such as-webkit-transform, is treated like the property it aliases.!importantis ignored: the value applies, without the priority.
Errors
Both SDKs report every error as a CardRevealError with a stable code. Check with CardRevealError.is(error).
field, the HTTP status and Column's API error code apiCode are set when known. Messages never contain the token
or card data, and the SDKs never log either.
invalid_optionsintegrity_required<script> tag has no integrity attribute with a sha256-, sha384- or sha512- hash, or it was loaded as a module script.script_load_failedreveal() retries.container_not_foundreveal_failed401 status means the token is missing, invalid, already used, expired, for a different card, or bound to a different reveal key. A 403 with apiCode card_reveal_sdk_upgrade_required means this SDK version is no longer supported; upgrade it. A 400 is a PIN error, or invalid_entity_type when the card's authorized user isn't a person.timeouttimeoutMs passed before every field showed its value.unmountedunmount() was called before the reveal finished.React Native
The React Native SDK is pure JavaScript with no native module. It works in Expo Go, Expo development builds and bare React Native, and needs React 19.1 and React Native 0.81 or later. It takes the same options and reports the same errors as the web SDK.
Install
npx expo install @column-na/card-reveal-react-native@0.13.0 react-native-get-random-valuesCheck that package.json lists "@column-na/card-reveal-react-native": "0.13.0" with no ^ or ~, or install with
npm install --save-exact @column-na/card-reveal-react-native@0.13.0 react-native-get-random-values.
Each reveal generates a one-time key, which needs a secure random source. Import the polyfill once, at the top of the app's entry file, before anything else:
import 'react-native-get-random-values';Without it, prepareReveal() rejects with invalid_options.
The polyfill is part of the reveal's trust boundary: the one-time key is only as unpredictable as the random bytes it
provides. Use react-native-get-random-values, which draws from the operating system's secure random source, and
never replace crypto.getRandomValues with a shim or test stub in a build that reveals real cards.
The SDK refuses obviously broken output (all zeros, repeating bytes, a degenerate key) with reveal_failed, but it
can't tell a sound source from one an attacker can reproduce.
Reveal a Card
import { useEffect, useMemo, useRef } from 'react';
import { View } from 'react-native';
import {
CardRevealError,
CardRevealText,
createCardRevealClient,
type CardRevealTextHandle,
} from '@column-na/card-reveal-react-native';
export function CardDetails({ cardId }: { cardId: string }) {
const client = useMemo(() => createCardRevealClient({ environment: 'live' }), []); // or 'sandbox'
const pan = useRef<CardRevealTextHandle>(null);
const cvv2 = useRef<CardRevealTextHandle>(null);
useEffect(() => {
let cancelled = false;
let unmount: (() => void) | undefined;
(async () => {
// Make the reveal's one-time key, then have your server create a reveal token bound to it.
const prepared = await client.prepareReveal();
const revealToken = await myServer.createRevealToken(cardId, prepared.keyThumbprint);
if (cancelled) return;
const reveal = prepared.reveal({
cardId,
revealToken,
fields: { pan, cvv2 },
style: { color: '#fff', fontFamily: 'Menlo' },
format: { pan: 'spaced' },
});
unmount = reveal.unmount;
await reveal.ready;
})().catch((error) => {
if (CardRevealError.is(error)) console.warn('Card reveal failed:', error.code);
});
return () => {
cancelled = true;
unmount?.();
};
}, [client, cardId]);
return (
<View>
<CardRevealText ref={pan} placeholder="•••• •••• •••• ••••" />
<CardRevealText ref={cvv2} placeholder="•••" />
</View>
);
}The one-time key stays in the SDK's memory and is forgotten once the reveal finishes or is unmounted. If the reveal
won't happen, call prepared.discard() to forget it straight away.
CardRevealText shows its placeholder before the reveal and after unmount. Set selectable to let the cardholder
select and copy the value. React Native Web isn't supported for live reveals; use the web SDK instead.
React Bindings
CardRevealProvider, CardRevealSlot, useCardReveal() and useCardRevealState() are exported from
@column-na/card-reveal-react-native and work as they do on the web. Each <CardRevealSlot field="..."> is
a CardRevealText for that field and takes its props, and useCardReveal() maps each field to a CardRevealText ref.
import { CardRevealProvider, CardRevealSlot } from '@column-na/card-reveal-react-native';
<CardRevealProvider
client={client}
cardId={cardId}
mintToken={({ cardId, keyThumbprint }) => myServer.createRevealToken(cardId, keyThumbprint)}
>
<CardRevealSlot field="pan" placeholder="•••• •••• •••• ••••" selectable />
<CardRevealSlot field="cvv2" placeholder="•••" />
</CardRevealProvider>;Reveal a PIN
The SDKs can also show a card's PIN, for example to a cardholder who forgot it or whose PIN Column chose.
Enable PIN Reveal
PIN reveal is off by default. Partners contact their Column representative to enable it for a card program. Once it's enabled, no reveal returns a PIN unless the SDK asks for it.
Show the PIN
Add pin to fields. The SDKs ask Column only for the fields being rendered, so the PIN is returned only when
fields includes pin, and a PIN-only reveal doesn't return the card number or CVV2. The partner's server creates
reveal tokens the same way either way. The pin field is available from version 0.7.0 of the SDKs; earlier versions
reject it with invalid_options.
const prepared = await client.prepareReveal();
const revealToken = await myServer.createRevealToken(cardId, prepared.keyThumbprint);
const { ready, unmount } = prepared.reveal({ cardId, revealToken, fields: { pin: '#pin' } });In React Native, pass a CardRevealText ref, as for any other field: fields: { pin }.
Verify the cardholder before revealing their PIN, for example with a fresh login, a one-time code or a biometric check. Anyone who sees the PIN can use the card at an ATM or a PIN pad. Create the reveal token only after that check passes.
Reveal pin on its own, not with the card number or CVV2. If the PIN can't be revealed, the whole reveal fails, so
asking for it with other fields would hide those too.
Which PINs Can Be Revealed
A card's PIN can be revealed if it was set after PIN reveal became available: passed in encrypted_pin when the card
was created, renewed or replaced, set with update card PIN, chosen by Column with
generate_pin, or carried over on renewal or replacement from a card whose PIN could be revealed. A blocked PIN can
still be revealed.
PINs set before PIN reveal became available can't be revealed, and a reveal with pin fails with
pin_not_revealable. To make one revealable, have the cardholder choose a PIN and
update the card's PIN, or create a new PIN with generate_pin on a PIN update, renewal
or replacement.
Let Column Choose the PIN
On a program with PIN reveal enabled, create, renew or
replace a card, or update its PIN, with
"generate_pin": true to have Column set a random 4-digit PIN. The card's pin_status is set. Column never returns
the PIN in an API response; the cardholder sees it only through PIN reveal. generate_pin can't be combined with
encrypted_pin, and fails if PIN reveal isn't enabled for the program.
On a PIN update, generate_pin unblocks a blocked PIN and sends the same events as setting encrypted_pin, and works
with current_encrypted_pin. Each request sets a different PIN, so retrying an update that may have succeeded sets
another one.
PIN Errors
When a reveal with pin fails because of the PIN, ready rejects with reveal_failed, status 400, and Column's
error code in apiCode:
apiCodepin_not_revealablefeature_not_enabledinvalid_field_valueThese checks run before the reveal token is used, so the same token still works for a reveal without pin.
Audit Reveals
Every reveal records which card details it returned, by name: any of pan, cvv2, expiration_date,
cardholder_name and pin. The record never contains the details themselves. The SDK's expiration_month and
expiration_year fields are both recorded as expiration_date.
- As it happens: the
issuing.card_reveal_token.consumedevent lists them inrevealed_fields. - Later: list card reveals returns a card's reveals, newest first, each with its
revealed_fieldsandconsumed_at.
curl 'https://api.column.com/issuing/cards/<card_id>/reveals?limit=10' \
-u :<YOUR API KEY>Only reveal tokens that were used appear. A reveal token that was never used isn't listed. revealed_fields is null
for reveals during the rollout of this record on October 26, 2026, when which fields a reveal returned wasn't recorded.
Versions
The web and React Native SDKs follow semantic versioning and release together at the same version. Pin an exact
version. Each request tells Column which SDK and version made it, and Column may require a minimum version to keep
revealing cards. Column requires version 0.7.0 or later, the first with prepareReveal(); earlier versions no longer
reveal cards. Version 0.7.0 also renamed the cvv field to cvv2, so fields: { cvv } and fieldStyles: { cvv }
throw invalid_options.