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.
- Android
- Web
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>"
}
}
}
}
dependencies {
implementation("co.openfabric:of-secure-card-sdk:0.0.7")
}
Minimum Android version: Android 8.0 Oreo (API level 26).
@open-fabric:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<value provided by Open Fabric>
npm install @open-fabric/secure-card-sdk@0.0.31
The package ships ES module and CommonJS builds with TypeScript types.
Versions
Pin an explicit version. The SDK is pre-1.0 and versions can carry breaking API changes.
| Platform | Version | Notes |
|---|---|---|
| Android | 0.0.7 | Current. Adds Card.formFactor (physical / virtual). |
| Android | 0.0.6 | Of* naming, OpenFabricError, the auth gate receives the Activity, sessions survive the app going to the background, Card.locked and Card.staticTokenId, onCardArtError. |
| Android | 0.0.5 and earlier | Pre-release. Not supported. |
| Web | 0.0.31 | Current. Same names and steps as Android 0.0.7, including Card.formFactor. |
| Web | 0.0.30 | Same names and steps as Android 0.0.6. |
| Web | 0.0.29 and earlier | Pre-release. Not supported. |
Initialize the SDK
Initialize the SDK once, before you start a session:
- Android
- Web
Call OfSecureCardSdk.init, typically from Application.onCreate:
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.
Call OfSecureCardSdk.init once, when your application starts:
import { OfEnvironment, OfSecureCardSdk } from '@open-fabric/secure-card-sdk';
OfSecureCardSdk.init({
environment: OfEnvironment.Prod,
authGate: myAuthGate, // optional
cardArtResolver: myCardArtResolver, // optional
});
SdkConfig property | Description |
|---|---|
environment | Which Open Fabric environment to talk to: OfEnvironment.Sandbox or OfEnvironment.Prod. Must match the environment of your backend credentials. See Environments. |
authGate | Optional. Your own user check (e.g. biometrics or a passkey) that runs before every sensitive action. See Authenticate the cardholder. |
cardArtResolver | Optional. Decides which card art is shown for each card. See Card art. |
onCardArtError | Optional. 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
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
}
| Field | Description |
|---|---|
customer_id | Required. 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. |
channel | Required. The platform the session is for: android or web. |
operations | Optional. 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_programs | Optional. Limits the session to cards in these Card Programs. |
ttl | Optional. How long the session lasts once started, in seconds (60 to 3600). Defaults to 900. |
allowed_origin | Required 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. |
| Operation | Allows | Required scope |
|---|---|---|
CARD_LIST | Listing the customer's cards. | cards.read |
CARD_GET | Getting a single card. | cards.read |
CARD_UPDATE | Locking and unlocking a card. | tokens.update |
PAN_REVEAL | Showing the full card number, expiry date and CVV. | cards.read |
PIN_REVEAL | Showing the card PIN. | pin.read |
PIN_CHANGE | Changing 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.
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.
- Android
- Web
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.
import { OfSecureCardSdk, OpenFabricError } from '@open-fabric/secure-card-sdk';
try {
const session = await OfSecureCardSdk.startSession(sessionInitTokenFromYourBackend);
// The session is active. You can now list and display cards.
} catch (error) {
// The session could not be started. See Error handling below.
}
The promise resolves only once the session is fully active. If starting the session fails, no session is created.
The session ends when the customer leaves the page, when you call await session.close(), or when its ttl runs out. When the page is hidden (another tab, the app switcher, a locked screen), 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.
The page that starts the session must be served from the allowed_origin of the session.
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.
- Android
- Web
Implement SecureCardAuthGate. The SDK passes the current Activity, so you can show a prompt on it. Always call either onAuthorized() or onDenied().
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())
}
}
Implement requestAuthentication, returning true (or a promise of true) when the cardholder is verified. Anything else, including false, a rejected promise or a thrown error, denies the request.
OfSecureCardSdk.init({
environment: OfEnvironment.Prod,
authGate: {
requestAuthentication: () => myApp.confirmWithPasskey(), // boolean or Promise<boolean>
},
});
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.
| Property | Description |
|---|---|
code | The error code, an OpenFabricErrorCode. See the table below. |
message | A description that is safe to show or log. It never contains card data. |
rawCode | The original error code from Open Fabric, for errors returned by the API. Empty for errors the SDK detected itself. |
httpStatus | The HTTP status, if the error came from an API response. For diagnostics only: branch on code. |
The most common codes:
code | Description |
|---|---|
SESSION_EXPIRED | The session has ended or expired. Create a new session from your backend. |
OPERATION_NOT_ALLOWED | The session wasn't created with the operation this call needs. |
CARD_NOT_FOUND | The card doesn't exist or doesn't belong to the session's customer. |
CARD_NOT_REGISTERED | The card is still being issued, so its PIN isn't available yet. Try again later. |
PIN_REVEAL_UNAVAILABLE | Showing the PIN isn't available for this card, for example because it isn't enabled on the Card Program. |
PIN_REVEAL_LIMIT_EXCEEDED | The PIN has been shown too many times. Try again later. |
PIN_VERIFICATION_FAILED | The current PIN entered during a PIN change is incorrect. |
PIN_RETRY_EXCEEDED | Too many incorrect PIN attempts. The PIN is locked. |
PIN_WEAK | The new PIN is too easy to guess. The PIN view asks for a new PIN. |
PIN_CHANGE_OUTCOME_UNKNOWN | It isn't known whether the PIN was changed. Ask the cardholder to try the new PIN first. |
SDK_UPGRADE_REQUIRED | This SDK version is no longer supported. Update the SDK. |
SDK_AUTHENTICATION_DENIED | Your authGate denied the request. |
SDK_OPERATION_FAILED | The call failed for another reason, for example a network error or (on the web) the secure view didn't load. |
UNKNOWN | An 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.
- Android
- Web
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")
}
}
import { OpenFabricError, OpenFabricErrorCode } from '@open-fabric/secure-card-sdk';
function handleError(error: unknown): void {
if (!(error instanceof OpenFabricError)) {
throw error;
}
switch (error.code) {
case OpenFabricErrorCode.PIN_RETRY_EXCEEDED:
showMessage('Too many attempts. Your PIN is locked.');
break;
case OpenFabricErrorCode.SESSION_EXPIRED:
showMessage('Your session expired. Please try again.');
break;
default:
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,PinRevealVieworPinInputView) is protected withFLAG_SECURE. The protection stays on for the lifetime of that window. To remove it once the last secure view is gone, callOfSecureCardSdk.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.
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.