Skip to main content

Display cards with the Card SDK

Once a session is started, you can use the Card SDK to:

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.

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) { /* ... */ }
},
)

The status, cardProgramId and network filters are optional and can be combined. Leave them out to list all cards of the customer.

Card propertyDescription
cardIdThe card identifier used by the SDK.
staticTokenIdThe card's id in the card management APIs (the static_token_id), so you can match an SDK card to your own records.
redactedNumberThe redacted card number, e.g. 512345******9708.
networkThe card network, e.g. visa or mastercard.
statusThe card status, e.g. active or inactive.
formFactorphysical or virtual, the same values as form_factor in the lifecycle notifications.
lockedtrue when the card is locked. A lock is not a status: a locked card keeps its status, e.g. active.
cardProgramIdThe Card Program of the card.
expiryMonth, expiryYearThe card expiry date.
cardArtRefThe 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.

val card: SecureCard = session.forCard(theCard)

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():

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) { /* ... */ }
},
)

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.

secureCardView.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.

secureCardView.showBuiltInToggleButton = false

myButton.setOnClickListener { secureCardView.toggleReveal() }

secureCardView.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.

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() }

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:

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()
}
}
CardArtBackgroundSource
DefaultThe 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.
CardArtSelection propertyDescription
backgroundThe card art image. See the table above. Defaults to the SDK's default art.
orientationHorizontal (default) or vertical: CardOrientation.HORIZONTAL / VERTICAL on Android, 'horizontal' / 'vertical' on the web.
panStyle, expiryStyle, cvvStyleOptional 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:

card.reveal(
view = secureCardView,
cardArtOverride = CardArtResolver.Default.resolve(theCard).copy(orientation = CardOrientation.VERTICAL),
callback = /* ... */,
)

Image requirements​

RequirementValue
Aspect ratio428: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.
FormatAndroid: 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 positionThe 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.

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),
)

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.

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) { /* ... */ }
},
)

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.