Secure components model (Android SDK)

Our SDKs all expose the same kind of building blocks: secure components that capture or display a sensitive value inside a sandboxed view your app cannot read. Card numbers, CVVsCVV Card Verification Value - the 3-digit security code printed on a payment card, used to authenticate card-not-present transactions. Weavr returns CVV in tokenized form on `GET /managed_cards/{id}` (with a stepped-up token); the value is only detokenized inside the SDK's secure CVV display component., card PINsPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component., passwords, passcodes, and OTP codes never travel through your code — only opaque tokens do.

This page explains the security model behind those components:

• why they exist
• how the capture and display flows work
• when a stepped-up auth token is required
• which components each SDK provides

Why secure components exist

Sensitive cardholder data is regulated. The moment your app touches a full card number, CVVCVV Card Verification Value - the 3-digit security code printed on a payment card, used to authenticate card-not-present transactions. Weavr returns CVV in tokenized form on `GET /managed_cards/{id}` (with a stepped-up token); the value is only detokenized inside the SDK's secure CVV display component., or PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component., you fall in scope for PCI DSS, and your authentication credentials carry similar exposure under PSD2/SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics)..

Our secure components let you skip that scope. Each component is a sandboxed view — an iframe on web, a platform-rendered view on mobile — that we own and ship. Sensitive values enter or leave that sandbox; your app code never reads them. In return:

• You qualify for the lightest PCI DSS Self-Assessment Questionnaire (SAQ-A on web).
• Your servers only ever see opaque, single-use tokens — never raw passwords, PANsPAN Primary Account Number - the long card number (typically 16 digits) printed or embossed on a payment card and used to identify the card on the payment network. Weavr never returns the raw PAN to your client; `GET /managed_cards/{id}` returns the PAN in tokenized form as `cardNumber`, and the value is only detokenized inside a Secure UI card-number component (a sandboxed iframe on the web, a secure native view on mobile)., CVVsCVV Card Verification Value - the 3-digit security code printed on a payment card, used to authenticate card-not-present transactions. Weavr returns CVV in tokenized form on `GET /managed_cards/{id}` (with a stepped-up token); the value is only detokenized inside the SDK's secure CVV display component., or PINsPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component..
• Compliance posture stays fixed even as you add features, because the secure component is the boundary.

A token is not the underlying value. It is a short-lived reference that our backend can resolve back to the real value when (and only when) the right component asks for it.

Capture flow

Capture components collect a sensitive value from the user. Examples include the password, passcode, OTP, and capture card PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. inputs.

The flow is the same on every SDK:

1. Your app mounts the input inside its own UI (a div, UITextField, EditText, or React Native view).
2. The user types. Your app never sees the keystrokes and the underlying view exposes no read API. Most capture components also visually mask each character as it is typed — see the Component coverage matrix for the one exception today.
3. You ask the SDK to tokenizeTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants.. The SDK encrypts the value, sends it directly to our backend, and hands you back an opaque token.
4. You forward the token to your server. Your server uses it in the API call that consumes the value (for example, creating a user with a password, or upgrading a card with a chosen PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component.).

The raw value never leaves the device unencrypted, and never enters your app's memory. That is the property that keeps you out of PCI scope and aligns with PSD2 requirements for handling authentication factors.

tip

For most capture inputs — password, passcode, OTP — visual masking happens character-by-character, not just on blur. A password field shows a dot the instant the user types each letter, even if your styling is overridden. The Web Capture card PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. component is the current exception: digits are visible while typing, although the underlying value is still inaccessible to your app. See Capture card PIN — Behaviour and UX guidance for the recommended pattern to use until masking ships.

Display flow

Display components render a sensitive value the user is allowed to see — the full card number on a card details screen, the CVVCVV Card Verification Value - the 3-digit security code printed on a payment card, used to authenticate card-not-present transactions. Weavr returns CVV in tokenized form on `GET /managed_cards/{id}` (with a stepped-up token); the value is only detokenized inside the SDK's secure CVV display component. behind a reveal toggle, an existing card PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component..

Display is more involved than capture, because de-tokenizingTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. a value is a privileged operation:

1. Your server fetches the tokenizedTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. value from our API (for example, GET /managed_cards/{id} returns a tokenizedTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. PANPAN Primary Account Number - the long card number (typically 16 digits) printed or embossed on a payment card and used to identify the card on the payment network. Weavr never returns the raw PAN to your client; `GET /managed_cards/{id}` returns the PAN in tokenized form as `cardNumber`, and the value is only detokenized inside a Secure UI card-number component (a sandboxed iframe on the web, a secure native view on mobile)., CVVCVV Card Verification Value - the 3-digit security code printed on a payment card, used to authenticate card-not-present transactions. Weavr returns CVV in tokenized form on `GET /managed_cards/{id}` (with a stepped-up token); the value is only detokenized inside the SDK's secure CVV display component., and PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component.).
2. The user steps up. Display components require a stepped-up user authentication token. Step-up is our PSD2/SCASCA Strong Customer Authentication - a two-factor authentication solution required by PSD2 regulations for when end-users are accessing their payment account sensitive information or initiating transactions. SCA requires at least two of the following: something you know (password), something you have (device), or something you are (biometrics).-aligned reauthentication step: the user proves a second factor (typically OTP) within a short window before sensitive data can be revealed. Without step-up, the de-tokenizeTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. call returns 401.
3. Your client associates the stepped-up tokenStepped-up token An access token that has been elevated to a higher authentication level by successfully completing a step-up challenge (typically an OTP via SMS or a biometric prompt). A stepped-up token is required to perform sensitive operations such as creating a user, managing authentication factors, or confirming high-value transactions. See the [step-up authentication guide](/apis/authentication/stepup/) for how to issue and complete a challenge. with the SDK (OpcUxSecureClient.associate() on web; equivalent SDK methods on mobile).
4. Your app mounts the display component with the tokenizedTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. value.
5. The component asks our backend to de-tokenizeTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants.. The real value is rendered inside the secure component's sandboxed view. Your code never receives it. You cannot read it from the DOM, the view hierarchy, or memory inspection.

If you see a 401 on a display component, the most common cause is that the user's auth token is no longer stepped-up — step-up windows are short by design.

Reveal pattern

Most apps don't show the full card number, CVVCVV Card Verification Value - the 3-digit security code printed on a payment card, used to authenticate card-not-present transactions. Weavr returns CVV in tokenized form on `GET /managed_cards/{id}` (with a stepped-up token); the value is only detokenized inside the SDK's secure CVV display component., or PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. on screen all the time. The standard UX is a placeholder (for example, a row of dots) with a reveal toggle the cardholder taps when they need the value.

Because the SDK never returns the raw value to your code, you cannot implement reveal as a "show/hide" of a string you already have. Instead:

• Hidden state. Render your own placeholder. Don't mount the secure component yet — no de-tokenizationTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. happens until you ask for it.
• On tap. Mount the secure component and trigger de-tokenizationTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants.. The SDK renders the real value inside its sandboxed view.
• Hide again. Unmount or remove the secure component and restore your placeholder.

This pattern works identically on Web, iOS, Android, and React Native — only the mount/unmount API changes.

note

Stepped-up auth tokens are short-lived. Deferring de-tokenizationTokenize Replace a card's primary account number (PAN) with a unique digital token that stands in for the real card during a transaction. When a cardholder adds a card to Apple Pay or Google Pay via push provisioning, the wallet provider stores a device-specific token rather than the underlying PAN, so the real card number isn't exposed on the device or shared with merchants. until the user taps reveal also keeps that exposure window narrow.

Component coverage matrix

The same model is implemented across our SDKs, but not every SDK exposes every component. Use the following table to plan an integration.

Component	Type	Web	iOS	Android	React Native
Password	Capture	yes	yes	yes	yes
OTP	Capture	yes	yes	yes	yes
Passcode (numeric, Android)	Capture	yes	no¹	yes²	Android-only
Card PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. — capture	Capture	yes³	yes	yes	yes
Card number — display	Display	yes	yes	yes	yes
CVVCVV Card Verification Value - the 3-digit security code printed on a payment card, used to authenticate card-not-present transactions. Weavr returns CVV in tokenized form on `GET /managed_cards/{id}` (with a stepped-up token); the value is only detokenized inside the SDK's secure CVV display component. — display	Display	yes	yes	yes	yes
Card PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. — display	Display	yes	yes	yes	yes
KYCKYC Know Your Customer - the identity verification process for consumer identities. This process allows you to seamlessly and securely verify your user's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers.	Verify	yes	yes	yes	yes
KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers.	Verify	yes	no	no	no

¹ Apple does not permit numeric passcodes as an authentication method on iOS — see Apple's Human Interface Guidelines. Use password as the biometric fallback on iOS.

² Passcode is being deprecated in favour of password for biometric login. New integrations should prefer password; passcode remains supported for existing apps.

³ The Web Capture card PINPIN Personal Identification Number - the numeric code a cardholder enters to authorize chip-and-PIN purchases and ATM withdrawals. PIN is only present on physical managed cards. Weavr returns it tokenized on `GET /managed_cards/{id}` (with a stepped-up token), and the SDK detokenizes it inside a secure PIN display component. component renders digits in cleartext during entry and accepts a single entry with no built-in confirmation field. The mobile equivalents mask each digit as it is typed. See Behaviour and UX guidance for the recommended pattern.

KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. (business verification) is currently web-only. Mobile apps that need to onboard businesses should hand off to a web flow for the KYBKYB Know Your Business - the identity verification process for corporate identities. This process allows you to seamlessly and securely verify your business customer's identity. Weavr will ask users to submit the necessary information and documentation so that they can get approved by financial providers. step.

Cross-references

For implementation detail, see the per-component guides:

• Cards
• Login
• KYC

For the underlying API model:

• Tokenization — the API-side view of the same security model.
• Stepped-up authentication — when and how to step a user up before mounting a display component.