Display cards with the Card SDK
Once a session is started, you can use the Card SDK to:
- List the customer's cards
- Display a card, with the card number, expiry date and CVV hidden or shown
- Use your own card art
- Lock or unlock a card
To show or change the PIN, see Manage the card PIN.
List cards
List the cards of the session's customer. This is normally the first call after a session starts: it's how you find out which cards the customer has. The session needs the CARD_LIST operation. The result contains no sensitive data.
- Android
- Web
import co.openfabric.securecard.Card
session.listCards(
status = null, // optional, e.g. "active"
cardProgramId = null, // optional
network = null, // optional, e.g. CardNetwork.VISA.wireValue
callback = object : SecureCardCallback<List<Card>> {
override fun onSuccess(result: List<Card>) {
// Show the cards in your UI
}
override fun onError(error: OpenFabricError) { /* ... */ }
},
)
const cards = await session.listCards({ status: 'active' }); // all filters optional
The status, cardProgramId and network filters are optional and can be combined. Leave them out to list all cards of the customer.
Card property | Description |
|---|---|
cardId | The card identifier used by the SDK. |
staticTokenId | The card's id in the card management APIs (the static_token_id), so you can match an SDK card to your own records. |
redactedNumber | The redacted card number, e.g. 512345******9708. |
network | The card network, e.g. visa or mastercard. |
status | The card status, e.g. active or inactive. |
formFactor | physical or virtual, the same values as form_factor in the lifecycle notifications. |
locked | true when the card is locked. A lock is not a status: a locked card keeps its status, e.g. active. |
cardProgramId | The Card Program of the card. |
expiryMonth, expiryYear | The card expiry date. |
cardArtRef | The URL of the card art configured for the Card Program, if any. |
Work with one card
To work with one card, get a SecureCard for it with session.forCard(). Pass the whole Card you received from listCards. This doesn't make a network call, so you can call it as often as you like, for example once per screen.
- Android
- Web
val card: SecureCard = session.forCard(theCard)
const card = session.forCard(cards[0]);
You use the same SecureCard to display the card, lock or unlock it, and manage its PIN.
If you only have a card ID, for example from a deep link, fetch the card first with session.getCard(cardId) (the session needs the CARD_GET operation), then pass the result to forCard(). To get the latest details of a card, for example after it was changed elsewhere, call card.get().
Display a card
SecureCardView shows a card with the card number, expiry date and CVV hidden. It has a built-in Show/Hide button that reveals the full details. The session needs the PAN_REVEAL operation.
The view and the data load separately. Create the view straight away, without a session, so your screen doesn't wait for the network. Then connect it to a card with card.reveal():
- Android
- Web
import co.openfabric.securecard.view.SecureCardView
// 1. Add the view to your layout right away. It doesn't need a session.
val secureCardView = SecureCardView(context)
container.addView(secureCardView)
// 2. Connect it to a card once the session is ready
card.reveal(
view = secureCardView,
includeCvv = true, // default
cardArtOverride = null, // default, see "Card art" below
callback = object : SecureCardCallback<Unit> {
override fun onSuccess(result: Unit) {
// The card is shown with hidden details.
// Show/Hide now reveals the full details.
}
override fun onError(error: OpenFabricError) { /* ... */ }
},
)
import { SecureCardView } from '@open-fabric/secure-card-sdk';
// 1. Create the view on an element of your page right away. It doesn't need a session.
const cardView = new SecureCardView(document.getElementById('card-panel')!);
// 2. Connect it to a card once the session is ready.
// Resolves when the card is shown with hidden details.
await card.reveal(cardView, {
includeCvv: true, // default
cardArtOverride: undefined, // default, see "Card art" below
});
The view places the Open Fabric iframe in the element you pass. cardView.clear() removes it. Closing the session clears every view it filled.
To show a different card in the same view, call reveal() again with the SecureCard of that card. The view then shows the new card, including its card art.
If you configured an authGate, it runs before the card details are fetched.
Show a card before a session starts
showCardArt() draws a card's art with the last four digits of its card number, without a session or a network call. Use it for a card list, or to show the card screen before the customer asks for the details. The next reveal() on the view replaces it.
- Android
- Web
secureCardView.showCardArt(theCard)
cardView.showCardArt(theCard);
Use your own Show/Hide button
To use your own button instead of the built-in one, hide the built-in button and call toggleReveal(). onRevealStateChanged tells you when the details are shown or hidden, for example to update your button label. It never receives the details.
- Android
- Web
secureCardView.showBuiltInToggleButton = false
myButton.setOnClickListener { secureCardView.toggleReveal() }
secureCardView.onRevealStateChanged = { isRevealed ->
// e.g. update your button label or flip a card animation
}
cardView.showBuiltInToggleButton = false;
myButton.addEventListener('click', () => cardView.toggleReveal());
cardView.onRevealStateChanged = (isRevealed) => {
// e.g. update your button label or flip a card animation
};
Copy the card number
Copy to clipboard is off by default. Only the card number can be copied, and only while it is shown. The CVV and PIN can't be copied.
- Android
- Web
Enable it, then call copyCardNumber() from your own UI, e.g. a copy icon. The SDK clears the clipboard after 30 seconds.
secureCardView.copyToClipboardEnabled = true
copyIcon.setOnClickListener { secureCardView.copyCardNumber() }
Enable it to show a copy button inside the card view. Browsers only let the frame that shows the number write it to the clipboard, so the button is part of the secure view and can't be your own.
cardView.copyToClipboardEnabled = true;
Card art
The card art is applied automatically when you call reveal() or showCardArt(). You decide which art is shown with a CardArtResolver, which you set once in cardArtResolver when you initialize the SDK. The resolver receives the Card being shown and returns a CardArtSelection.
If you don't set a resolver, CardArtResolver.Default is used. It shows the SDK's default art for the card network. To show the art configured on the card's Card Program, use its cardArtRef, as in the examples below. Card Program art is managed with the card art asset APIs:
- Android
- Web
import co.openfabric.securecard.view.CardArtBackground
import co.openfabric.securecard.view.CardArtResolver
import co.openfabric.securecard.view.CardArtSelection
val myCardArtResolver = CardArtResolver { card ->
val programArt = card.cardArtRef
when {
programArt != null -> CardArtSelection(background = CardArtBackground.Url(programArt))
card.network == "visa" -> CardArtSelection(background = CardArtBackground.Resource(R.drawable.my_visa_card_art))
else -> CardArtSelection()
}
}
CardArtBackground | Source |
|---|---|
Default | The SDK's default art for the card network. |
Url(url) | An image downloaded over HTTPS, e.g. the Card Program art in cardArtRef. |
Resource(resId) | A drawable resource in your app, including vector drawables. |
LocalFile(path) | An image file on the device. |
import { CardArtBackground, OfEnvironment, OfSecureCardSdk } from '@open-fabric/secure-card-sdk';
OfSecureCardSdk.init({
environment: OfEnvironment.Prod,
cardArtResolver: (card) => ({
background: card.cardArtRef
? CardArtBackground.Url(card.cardArtRef)
: CardArtBackground.Default,
}),
});
CardArtBackground | Source |
|---|---|
Default | The SDK's default art for the card network. |
Url(card.cardArtRef) | The Card Program art. |
Url(url) | Any other image URL. It is downloaded by your page, so it must be on your origin or a host that allows CORS. |
Image(blob) | A PNG, JPEG or WebP image of up to 1 MiB, e.g. one bundled with your app. |
The resolver runs in your page and only receives the redacted Card.
CardArtSelection property | Description |
|---|---|
background | The card art image. See the table above. Defaults to the SDK's default art. |
orientation | Horizontal (default) or vertical: CardOrientation.HORIZONTAL / VERTICAL on Android, 'horizontal' / 'vertical' on the web. |
panStyle, expiryStyle, cvvStyle | Optional text styles for the card number, expiry date and CVV. See Text style. |
To change one thing and keep the rest on Android, start from the default: CardArtResolver.Default.resolve(card).copy(orientation = CardOrientation.VERTICAL).
Card art never makes reveal() fail. If the art can't be loaded, or your resolver fails, the card is shown with the SDK's default art, and the onCardArtError listener you set in the SDK configuration is called with SDK_CUSTOM_CARD_ART_LOAD_FAILED.
Use different art for one view
The resolver applies to every card. To show a card differently in one place, for example vertically in a list and horizontally on a detail screen, pass a CardArtSelection as cardArtOverride to reveal() or showCardArt(). It's used instead of the resolver for that call only:
- Android
- Web
card.reveal(
view = secureCardView,
cardArtOverride = CardArtResolver.Default.resolve(theCard).copy(orientation = CardOrientation.VERTICAL),
callback = /* ... */,
)
await card.reveal(cardView, { cardArtOverride: { orientation: 'vertical' } });
Image requirements
| Requirement | Value |
|---|---|
| Aspect ratio | 428:270 for a horizontal card, 270:428 for a vertical card. On Android, images with a different ratio are stretched to fit. On the web, they are cropped. |
| Format | Android: any bitmap image (e.g. PNG or JPEG); vector images, including SVGs, only as a drawable resource (CardArtBackground.Resource). Web: PNG, JPEG or WebP. |
| Text position | The card number, expiry date and CVV are shown in a fixed position on the card. Leave that area clear in your design. |
Text style
To match your card design, set panStyle, expiryStyle and cvvStyle in the CardArtSelection. Each is a CustomCardArtStyle. cvvStyle defaults to expiryStyle. Leave a style out to keep the SDK's default look. Font sizes are kept within a readable range: 14–28 for the card number, 8–16 for the expiry date and CVV.
- Android
- Web
CardArtSelection(
background = CardArtBackground.Resource(R.drawable.my_card_art),
panStyle = CustomCardArtStyle(fontFamily = myTypeface, fontSizeSp = 20f, textColor = Color.WHITE),
expiryStyle = CustomCardArtStyle(fontFamily = myTypeface, fontSizeSp = 14f, textColor = Color.WHITE),
)
({
background: CardArtBackground.Default,
panStyle: { fontFamily: 'Inter', fontSizePx: 20, textColor: '#ffffff', fontSource: interWoff2 },
expiryStyle: { fontFamily: 'Inter', fontSizePx: 14, textColor: '#ffffff', fontSource: interWoff2 },
});
The secure view can't load fonts by URL. To use your own font, pass the font file (WOFF2, WOFF, TTF or OTF, up to 512 KiB) as fontSource.
Lock or unlock a card
Customers can lock a card themselves, e.g. when they have misplaced it. The session needs the CARD_UPDATE operation. A reason is required: use LockReason (CARD_LOST, CARD_STOLEN, SUSPECTED_FRAUD or OTHER) to lock and UnlockReason (CARD_FOUND, NOT_FRAUD or OTHER) to unlock. Both return the updated Card.
- Android
- Web
import co.openfabric.securecard.session.LockReason
import co.openfabric.securecard.session.UnlockReason
card.lock(
reason = LockReason.CARD_LOST,
callback = object : SecureCardCallback<Card> {
override fun onSuccess(result: Card) { /* result.locked is true */ }
override fun onError(error: OpenFabricError) { /* ... */ }
},
)
card.unlock(
reason = UnlockReason.CARD_FOUND,
callback = object : SecureCardCallback<Card> {
override fun onSuccess(result: Card) { /* result.locked is false */ }
override fun onError(error: OpenFabricError) { /* ... */ }
},
)
import { LockReason, UnlockReason } from '@open-fabric/secure-card-sdk';
const locked = await card.lock(LockReason.CARD_LOST); // locked.locked === true
const unlocked = await card.unlock(UnlockReason.CARD_FOUND); // unlocked.locked === false
This has the same effect as locking or unlocking the card with the Update card API. You receive the same lifecycle notifications, with the reason in status_reason_code.
Next: Manage the card PIN.