Cards (React Native SDK)

Prerequisites

Before implementing card components, ensure you have:

Initialized our SDK
Valid API credentials
A stepped-up user authentication token. All card components require step-up under PSD2 strong customer authentication. Set the token via setUserToken(token) before mounting any card component.

Security guarantees

Every secure card component in this guide is PCI DSS compliant. Sensitive values are tokenised end-to-end, are never exposed to your app, and are never held in memory once rendered.

Where each component fits in your app

The four secure components in our React Native SDK each render one piece of sensitive card data inside a tokenised view. The card mockup below shows where they typically appear in your app - hover the numbered hotspots for the underlying class names.

your app

4111 2222 3333 4444

CardholderMARIA TAYLOR

Expires12/29

CVV•••

Card PIN••••

Set new PIN

Hover or focus a numbered hotspot to see which secure component is responsible for the area - click to jump to its docs.

Mask card details with a reveal toggle

A common UX pattern is masking the CVV or PIN - hiding it behind a reveal toggle so the value only appears when the cardholder asks for it. Our SDK handles the secure rendering, but the mask/reveal UI is your responsibility - the SDK never returns the raw value to your app, so you can't show and hide it yourself.

Wire it up like this:

Hidden state: render your own placeholder (for example, a row of dots) with a reveal button next to it. Don't mount the secure component yet - no detokenisation happens until you ask for it.
On tap: mount the secure component and trigger detokenisation. The SDK renders the real value inside its sandboxed view; your app never sees it.
Hide again: unmount or remove the secure component and restore your placeholder.

Use the same approach for any display component - card number, CVV, or card PIN view.

note

Stepped-up auth tokens are short-lived. Deferring detokenisation until the user taps reveal also keeps that window narrow.

Card number - `SecureCardNumberLabel`

Use it for: card details and virtual-card screens where the cardholder needs to read or copy their full PAN, typically behind a reveal toggle.

The card number component shows the full 16-digit card number to your customers.

Render SecureCardNumberLabel with the tokenized PAN as toDetokenize and hold a ref to it. Call labelRef.deTokenize() when you want the value to appear - for example, when the user taps a reveal toggle. The de-tokenized PAN renders inside the secure view; your code never receives the raw value.

import { SecureCardNumberLabel } from "@weavr-io/secure-components-react-native";
const labelRef = useRef<any>();
<SecureCardNumberLabel
  style={styles.labelBox}
  textColor="#ff0000"
  textSize="16"
  isVertical={true} //used to show the card number in vertical alignment
  toDetokenize={CARD_NUMBER} //provide the tokenized card number
  onDeTokenize={(resp: any) => {
    if (resp.value != null && resp.value != undefined)
      Toast.show("" + resp.value);
    else Toast.show("" + resp);
  }}
  ref={labelRef}
/>;
//deTokenize action, you can use deTokenize() to detokenize and render secure data on the Label
labelRef.deTokenize();

Vertical card number display

Pass isVertical={true} to render the card number on four lines instead of one - useful for tall card-detail layouts.

isVertical = true;

The 16-digit PAN then renders as:

CVV - `SecureCardCVVLabel`

Use it for: card details screens where the cardholder needs the CVV for an online purchase, typically behind a reveal toggle.

The CVV component shows the 3-digit number your customers need to make online purchases.

Render SecureCardCVVLabel the same way as the card number - pass the tokenized CVV as toDetokenize, hold a ref, and call labelRef.deTokenize() when you want the value to appear. The de-tokenized CVV renders inside the secure view.

import { SecureCardCVVLabel } from "@weavr-io/secure-components-react-native";
const labelRef = useRef<any>();
<SecureCardCVVLabel
  style={styles.labelBox}
  fontStyle={{ fontFamily: "Lobster-Regular" }} //optional, used to set font
  textColor="#ff0000"
  textSize="16"
  toDetokenize={CARD_CVV} //provide the tokenized card cvv
  onDeTokenize={(resp: any) => {
    if (resp.value != null && resp.value != undefined)
      Toast.show("" + resp.value);
    else Toast.show("" + resp);
  }}
  ref={labelRef}
/>;
//deTokenize action, you can use deTokenize() to detokenize and render secure data on the Label
labelRef.deTokenize();

Card PIN view - `SecureCardPinLabel`

Use it for: physical-card management screens where the cardholder needs to recover the existing PIN, typically behind a reveal toggle.

The card PIN component shows the 4-digit PIN your customers need for in-person purchases. Use it only if you are issuing physical cards.

Render SecureCardPinLabel with the tokenized PIN as toDetokenize. The 4-digit PIN renders inside the secure view once you call labelRef.deTokenize(); your code never receives a copy of the value.

import { SecureCardPinLabel } from "@weavr-io/secure-components-react-native";
const labelRef = useRef<any>();
<SecureCardPinLabel
  style={styles.labelBox}
  fontStyle={{ fontFamily: "Lobster-Regular" }} //optional, used to set font
  textColor="#ff0000"
  textSize="16"
  toDetokenize={CARD_PIN} //provide the tokenize card number
  onDeTokenize={(resp: any) => {
    if (resp.value != null && resp.value != undefined)
      Toast.show("" + resp.value);
    else Toast.show("" + resp);
  }}
  ref={labelRef}
/>;
//deTokenize action, you can use deTokenize() to detokenize and render secure data on the Label
labelRef.deTokenize();

Card PIN set - `SecureCardPinTextField`

Use it for: the physical-card upgrade or activation screen, when you let the cardholder choose their own PIN.

The capture card PIN component collects a new 4-digit PIN that your customer chooses for their physical card.

PIN input rules

The component only accepts numeric input, masks each digit as the customer types it, and only produces a token once exactly 4 digits have been entered.

note

Due to strong customer authentication requirements, your authentication token must be stepped-up before calling this component.

Set user token in SDK

Forward the user's stepped-up auth token into the SDK before mounting the input. This is the React Native equivalent of OpcUxSecureClient.associate() on Web.

import { setUserToken } from "@weavr-io/secure-components-react-native";
setUserToken(token).then((res: any) => {
  console.log(res);
});

Check if an association exists with the SDK

Optionally check that the SDK still has a valid association before mounting the input. Useful if the user might have left the app between authenticating and reaching the PIN-capture screen - if isAssociated() resolves false, send them back through step-up.

import { isAssociated } from "@weavr-io/secure-components-react-native";
isAssociated().then((res) => {
  if (res) {
    //do your stuff
  } else {
    console.log("You must login to continue!");
  }
});

Create a TextField component

Render SecureCardPinTextField with a placeholder and a ref. The field accepts only numeric input. Wire onCreateToken to receive the token once you call createToken() on the ref in the next step.

import { SecureCardPinTextField } from "@weavr-io/secure-components-react-native";
const textFieldRef = useRef<any>();
//tag is only required for group actions
const [tagPass1, setTagPass1] = React.useState<string | undefined>();
<SecureCardPinTextField
  placeholder="Enter Card Pin"
  style={styles.fieldBox} //only define sizing
  textSize="16"
  background={true} //here default behaviour is system default
  onCreateToken={onPassToken}
  onGetTag={(resp: any) => {
    console.log(resp);
    setTagPass1(resp.value);
  }}
  onTextChanges={(resp) => {
    console.log(resp);
  }}
  onFocus={(resp) => {
    console.log(resp);
  }}
  onBlur={(resp) => {
    console.log(resp);
  }}
  ref={textFieldRef}
  placeholderTextColor="#000000"
/>;

Create a token from a TextField component

Call createToken() on the ref from your form's submit handler. The component fires the onCreateToken prop with an opaque token; forward that token to your server to call the physical card upgrade endpoint.

textFieldRef.current.createToken();
//it receives the tokenized password
const onPassToken = (resp: any) => {
  console.log(resp);
  setPassword(resp.value);
  Toast.show(resp.value);
};

Prerequisites​

Where each component fits in your app​

Mask card details with a reveal toggle​

Card number - SecureCardNumberLabel​

Vertical card number display​

CVV - SecureCardCVVLabel​

Card PIN view - SecureCardPinLabel​

Card PIN set - SecureCardPinTextField​

Set user token in SDK​

Check if an association exists with the SDK​

Create a TextField component​

Create a token from a TextField component​