Skip to main content

Set up the Card SDK

The Card SDK lets your customers see their cards, view or change their PIN, and lock or unlock a card, all inside your own app or website. Card data (card number, CVV and PIN) is decrypted and shown only inside the SDK's own secure views. Your app code and your backend never receive it, which keeps your PCI DSS scope small.

The Card SDK works for both physical and virtual cards. It is available for Android and Web. Both use the same names and the same steps, so you can integrate both platforms with one vocabulary.

How it works​

Every SDK journey starts with a session. Your backend creates it and receives a single-use session init token. Your app passes that token to the SDK, which uses it to start a short-lived session that is scoped to one customer.

On Android the SDK's views are native views. On the web, the secure views are an Open Fabric iframe that the SDK places in an element on your page: card data is decrypted inside that iframe, on the Open Fabric origin, and never reaches your page.

Get the SDK​

The SDK is published on GitHub Packages. Open Fabric provides the credentials (a GitHub username and a token with the read:packages scope) during onboarding.

settings.gradle.kts
dependencyResolutionManagement {
repositories {
google()
mavenCentral()
maven {
url = uri("https://maven.pkg.github.com/open-fabric/slice-secure-card-sdk")
credentials {
username = "<value provided by Open Fabric>"
password = "<value provided by Open Fabric>"
}
}
}
}
app/build.gradle.kts
dependencies {
implementation("co.openfabric:of-secure-card-sdk:0.0.7")
}

Minimum Android version: Android 8.0 Oreo (API level 26).

Versions​

Pin an explicit version. The SDK is pre-1.0 and versions can carry breaking API changes.

PlatformVersionNotes
Android0.0.7Current. Adds Card.formFactor (physical / virtual).
Android0.0.6Of* naming, OpenFabricError, the auth gate receives the Activity, sessions survive the app going to the background, Card.locked and Card.staticTokenId, onCardArtError.
Android0.0.5 and earlierPre-release. Not supported.
Web0.0.31Current. Same names and steps as Android 0.0.7, including Card.formFactor.
Web0.0.30Same names and steps as Android 0.0.6.
Web0.0.29 and earlierPre-release. Not supported.

Initialize the SDK​

Initialize the SDK once, before you start a session:

Call OfSecureCardSdk.init, typically from Application.onCreate:

MyApplication.kt
import co.openfabric.securecard.OfEnvironment
import co.openfabric.securecard.OfSecureCardSdk
import co.openfabric.securecard.SdkConfig

class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
OfSecureCardSdk.init(
SdkConfig(
environment = OfEnvironment.Prod,
authGate = MyAuthGate(), // optional
cardArtResolver = myCardArtResolver, // optional
),
)
}
}

OfSecureCardSdk.isInitialized() tells you whether init has already run. This is useful if you initialize the SDK later than Application.onCreate, for example when the first card screen opens.

SdkConfig propertyDescription
environmentWhich Open Fabric environment to talk to: OfEnvironment.Sandbox or OfEnvironment.Prod. Must match the environment of your backend credentials. See Environments.
authGateOptional. Your own user check (e.g. biometrics or a passkey) that runs before every sensitive action. See Authenticate the cardholder.
cardArtResolverOptional. Decides which card art is shown for each card. See Card art.
onCardArtErrorOptional. Called when the card art you chose can't be loaded and the SDK's default art is shown instead. See Card art.

Each environment includes its own Open Fabric endpoints and keys, so there are no URLs or keys to configure. The SDK verifies that it is talking to Open Fabric using a key built into the SDK for each environment.

Create a session from your backend​

info

For security reasons, sessions must be created from your backend (server-to-server) using your OAuth access token. Never call this API from your app or web page. The session_init_token is single-use and valid for 5 minutes, so create it when the customer opens the card screen, not in advance.

Call the Create Card SDK session API with the customer and the platform the session is for. This API uses our Issuer base URL (see Environments).

Sample request

{
"customer_id": "40095c2f-d391-4e06-94d9-cf0b3191c548",
"channel": "android",
"operations": ["CARD_LIST", "CARD_GET", "PAN_REVEAL", "PIN_REVEAL", "PIN_CHANGE"],
"ttl": 900
}
FieldDescription
customer_idRequired. The Open Fabric customer_id of the customer, as returned by the Provision API. The session can only see this customer's cards. You can only create sessions for your own customers.
channelRequired. The platform the session is for: android or web.
operationsOptional. The actions the session is allowed to perform. Leave it out to allow all operations your access token's scopes allow. See the table below.
card_programsOptional. Limits the session to cards in these Card Programs.
ttlOptional. How long the session lasts once started, in seconds (60 to 3600). Defaults to 900.
allowed_originRequired for web sessions, and must be left out for android sessions. The origin of the website that embeds the SDK, e.g. https://app.example.com. Must be one of your registered origins.
OperationAllowsRequired scope
CARD_LISTListing the customer's cards.cards.read
CARD_GETGetting a single card.cards.read
CARD_UPDATELocking and unlocking a card.tokens.update
PAN_REVEALShowing the full card number, expiry date and CVV.cards.read
PIN_REVEALShowing the card PIN.pin.read
PIN_CHANGEChanging the card PIN.pin.update

Your access token needs the scope of every operation you request, otherwise the API returns 403. See OAuth2 scopes for how to request scopes.

tip

Only grant the operations the screen needs. For example, a card list screen only needs CARD_LIST.

A new session returns 201 Created.

Sample response

{
"session_init_token": "Yk3vQ9tH2mXw8LpR4sNc7ZfJ1aUe6GdK0oBiTyVqWhE",
"expires_at": "2026-10-14T10:05:00Z"
}

Return the session_init_token to your app, for example in the response of the API call that opens the card screen. Treat it as an opaque value: its format can change.

Start the session​

Pass the session_init_token to the SDK in one call. OfSecureCardSdk.init must have run first.

CardActivity.kt
import co.openfabric.securecard.OfSecureCardSdk
import co.openfabric.securecard.callbacks.SecureCardCallback
import co.openfabric.securecard.errors.OpenFabricError
import co.openfabric.securecard.session.SecureCardSession

OfSecureCardSdk.startSession(
lifecycleOwner = this,
sessionInitToken = sessionInitTokenFromYourBackend,
callback = object : SecureCardCallback<SecureCardSession> {
override fun onSuccess(result: SecureCardSession) {
// The session is active. You can now list and display cards.
}

override fun onError(error: OpenFabricError) {
// The session could not be started. See Error handling below.
}
},
)

onSuccess is only called once the session is fully active. If starting the session fails, no session is created.

The session is tied to the lifecycleOwner you pass in (an Activity or Fragment) and ends when that screen is destroyed. It also ends when you call session.close() or when its ttl runs out. When the app goes to the background, the session stays open, but the secure views hide the card details and the PIN, and discard a PIN change that was not submitted yet.

A session_init_token can't be reused. To use the SDK again after a session has ended, create a new session from your backend and start it.

Run one session at a time. Starting a new session while another one is still open ends the open one, so close a session before you start the next.

Authenticate the cardholder​

We recommend checking that the cardholder is present before showing sensitive data. Pass your own check as authGate in the SDK configuration. The SDK calls it right before every card reveal and PIN reveal, and when the cardholder submits a PIN change, and waits for your result. If no authGate is set, the SDK does not perform its own check before sensitive actions.

Implement SecureCardAuthGate. The SDK passes the current Activity, so you can show a prompt on it. Always call either onAuthorized() or onDenied().

MyAuthGate.kt
import android.app.Activity
import android.os.Build
import androidx.biometric.BiometricManager.Authenticators.BIOMETRIC_STRONG
import androidx.biometric.BiometricManager.Authenticators.DEVICE_CREDENTIAL
import androidx.biometric.BiometricPrompt
import androidx.core.content.ContextCompat
import androidx.fragment.app.FragmentActivity
import co.openfabric.securecard.callbacks.SecureCardAuthCallback
import co.openfabric.securecard.callbacks.SecureCardAuthGate

class MyAuthGate : SecureCardAuthGate {
override fun requestAuthentication(activity: Activity, callback: SecureCardAuthCallback) {
val fragmentActivity = activity as? FragmentActivity ?: return callback.onDenied()
val prompt = BiometricPrompt(
fragmentActivity,
ContextCompat.getMainExecutor(fragmentActivity),
object : BiometricPrompt.AuthenticationCallback() {
override fun onAuthenticationSucceeded(result: BiometricPrompt.AuthenticationResult) {
callback.onAuthorized()
}

override fun onAuthenticationError(errorCode: Int, errString: CharSequence) {
callback.onDenied()
}
},
)
val promptInfo = BiometricPrompt.PromptInfo.Builder()
.setTitle("Verify it's you")
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
// Android 11+: biometrics, or the device PIN, pattern or password
promptInfo.setAllowedAuthenticators(BIOMETRIC_STRONG or DEVICE_CREDENTIAL)
} else {
// Android 8-10 can't combine strong biometrics with the device credential
promptInfo.setAllowedAuthenticators(BIOMETRIC_STRONG)
promptInfo.setNegativeButtonText("Cancel")
}
prompt.authenticate(promptInfo.build())
}
}

A denied check fails the action with SDK_AUTHENTICATION_DENIED.

Error handling​

Every failed SDK call reports an OpenFabricError. On Android it is passed to onError; on the web the promise rejects with it.

PropertyDescription
codeThe error code, an OpenFabricErrorCode. See the table below.
messageA description that is safe to show or log. It never contains card data.
rawCodeThe original error code from Open Fabric, for errors returned by the API. Empty for errors the SDK detected itself.
httpStatusThe HTTP status, if the error came from an API response. For diagnostics only: branch on code.

The most common codes:

codeDescription
SESSION_EXPIREDThe session has ended or expired. Create a new session from your backend.
OPERATION_NOT_ALLOWEDThe session wasn't created with the operation this call needs.
CARD_NOT_FOUNDThe card doesn't exist or doesn't belong to the session's customer.
CARD_NOT_REGISTEREDThe card is still being issued, so its PIN isn't available yet. Try again later.
PIN_REVEAL_UNAVAILABLEShowing the PIN isn't available for this card, for example because it isn't enabled on the Card Program.
PIN_REVEAL_LIMIT_EXCEEDEDThe PIN has been shown too many times. Try again later.
PIN_VERIFICATION_FAILEDThe current PIN entered during a PIN change is incorrect.
PIN_RETRY_EXCEEDEDToo many incorrect PIN attempts. The PIN is locked.
PIN_WEAKThe new PIN is too easy to guess. The PIN view asks for a new PIN.
PIN_CHANGE_OUTCOME_UNKNOWNIt isn't known whether the PIN was changed. Ask the cardholder to try the new PIN first.
SDK_UPGRADE_REQUIREDThis SDK version is no longer supported. Update the SDK.
SDK_AUTHENTICATION_DENIEDYour authGate denied the request.
SDK_OPERATION_FAILEDThe call failed for another reason, for example a network error or (on the web) the secure view didn't load.
UNKNOWNAn error code from Open Fabric that this SDK version doesn't recognize. Check rawCode.

Codes starting with SDK_ are detected by the SDK itself, except SDK_UPGRADE_REQUIRED, which comes from the API.

override fun onError(error: OpenFabricError) {
when (error.code) {
OpenFabricErrorCode.PIN_VERIFICATION_FAILED -> showMessage("That current PIN isn't correct")
OpenFabricErrorCode.PIN_RETRY_EXCEEDED -> showMessage("Too many attempts. Your PIN is locked.")
OpenFabricErrorCode.CARD_NOT_FOUND -> showMessage("Card not found")
OpenFabricErrorCode.SESSION_EXPIRED -> showMessage("Your session expired. Please try again.")
OpenFabricErrorCode.SDK_AUTHENTICATION_DENIED -> showMessage("Authentication was declined")
else -> showMessage("Something went wrong")
}
}

Security behaviour​

The SDK applies the following protections automatically:

  • No card data in your code: callbacks and promises only report success or failure, never card numbers, CVVs or PINs.
  • No storage: nothing is written to disk or browser storage. Card data and keys are kept in memory only, and are cleared when a view is removed or the session ends.
  • Secure PIN entry: PINs are entered on the SDK's own keypad or inputs, never through the system keyboard on Android, and never in your page on the web.
  • Hidden in the background: card details and the PIN are hidden when the app or page goes to the background.
  • Screenshot protection (Android): a window that shows a secure SDK view (SecureCardView, PinRevealView or PinInputView) is protected with FLAG_SECURE. The protection stays on for the lifetime of that window. To remove it once the last secure view is gone, call OfSecureCardSdk.setClearFlagSecureOnLastDetach(true).
  • Isolated views (Web): the secure views run in an Open Fabric iframe that only accepts your session's allowed_origin.

Reference app​

Open Fabric provides reference apps for Android and Web that demonstrate every step on this page. Contact your Open Fabric representative to get access during onboarding.

warning

The reference apps create sessions directly from the app, using a demo secret, so that they can run without a backend. Don't copy this into your own app. Always create sessions from your backend.

Next: Display cards with the Card SDK.