Skip to main content

Secure components model

Our four SDKs (Web, iOS, Android, React Native) all expose the same kind of building block: a secure component that captures or displays a sensitive value inside a sandboxed view your app cannot read. Card numbers, CVVs, card PINs, 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, and which components each SDK provides.

If you're integrating a specific SDK, read this page first, then jump into the per-SDK guide for code samples.

Why secure components exist​

Sensitive cardholder data is regulated. The moment your app touches a full card number, CVV, or PIN, 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, PANs, CVVs, or PINs.
  • 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 PIN 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. The component masks each character on entry — your app never sees the keystrokes, and the underlying view exposes no read API.
  3. You ask the SDK to tokenize. 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 PIN).

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

On capture inputs, 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 underlying value is unreadable.

Display flow​

Display components render a sensitive value the user is allowed to see — the full card number on a card details screen, the CVV behind a reveal toggle, an existing card PIN.

Display is more involved than capture, because de-tokenizing a value is a privileged operation:

  1. Your server fetches the tokenized value from our API (for example, GET /managed_cards/{id} returns a tokenized PAN, CVV, and PIN).
  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-tokenize 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 tokenized value.
  5. The component asks our backend to de-tokenize. 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, CVV, or PIN 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-tokenization happens until you ask for it.
  • On tap. Mount the secure component and trigger de-tokenization. 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-tokenization 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.

ComponentTypeWebiOSAndroidReact Native
PasswordCaptureyesyesyesyes
OTPCaptureyesyesyesyes
Passcode (numeric, Android)Captureyesno¹yes²Android-only
Card PIN — captureCaptureyesyesyesyes
Card number — displayDisplayyesyesyesyes
CVV — displayDisplayyesyesyesyes
Card PIN — displayDisplayyesyesyesyes
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.Verifyyesyesyesyes
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.Verifyyesnonono

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

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-SDK guides:

For the underlying API model: