Cards (Web SDK)

When you retrieve a customer's card details from our API, sensitive fields are 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.. To show 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. field to the cardholder, mount the matching display component - the SDK detokenizesTokenize 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 value inside a sandboxed iframe so the raw value never reaches your app.

To set a new physical cardPhysical Card A payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use. 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 it in the secure input component and pass the resulting token to our API.

info

Learn how the security model works in the tokenization guide.

Prerequisites

Before mounting card components:

• Set up the SDK and initialize it with your UI keyUI key A public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key..
• Obtain a stepped-up user authentication token. All card components require step-up.
• Associate the token using OpcUxSecureClient.associate() before mounting display components.

Where each component fits in your app

The four secure components in our Web SDK each render one piece of sensitive card data inside 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. iframe. The card mockup below shows where they typically appear in your app - hover the numbered hotspots for the underlying API calls.

your app

4111 2222 3333 44441OpcUxSecureClient.span("cardNumber")Card numberRenders the full 16-digit card number inside a secure view that detokenises on demand.Jump to docs →

CardholderMARIA TAYLOR

Expires12/29

CVV•••2OpcUxSecureClient.span("cvv")CVVRenders the 3-digit security code inside a tokenised view. Build your own reveal toggle - defer detokenisation until the user taps it.Jump to docs →

Card PIN••••3OpcUxSecureClient.span("cardPin")Card PIN (view)Renders the existing 4-digit PIN inside a tokenised view. Build your own reveal toggle - defer detokenisation until the user taps it.Jump to docs →

Set new PIN4form.input("cardPin", "cardPin")Card PIN (set)Captures and tokenises a new 4-digit PIN. Requires a stepped-up auth token.Jump to docs →

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 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. - 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, 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 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. view.

note

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

---

Card number

Use it for: card details and virtual-card screens where the cardholder needs to read or copy their full 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)., typically behind a reveal toggle.

Use the Card number component to detokenize and show your customer's full 16-digit card number.

Get the tokenized card number

Fetch the managed cardManaged Card A payment card (virtual or physical) that can be created and managed through the Weavr platform. Cards can operate in prepaid mode (with their own balance) or debit mode (linked to a managed account). All cards must be assigned to a card assignee who is an Authorised User. from your server. With a stepped-up token, the response includes the tokenisedTokenize 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). as cardNumber: { value: "<token>" }; pass that token to the secure component in the next step. Without step-up, cardNumber is absent or null — see Card response fields and step-up for the full conditional schema.

Server-side only

You must perform this step on the server side of your app.

Step-up required

Your authentication token must be stepped-up before calling this component.

GET/managed_cards/${id}Try it

Response

{
  "id": "string",
  "profileId": "string",
  "externalHandle": "string",
  "tag": "string",
  "friendlyName": "string",
  "currency": "str",
  "state": {
    "state": "ACTIVE",
    "blockedReason": "USER",
    "destroyedReason": "SYSTEM"
  },
  "type": "VIRTUAL",
  "cardBrand": "MASTERCARD",
  "cardNumber": {
    "value": "string"
  },
  "cvv": {
    "value": "str"
  },
  "cardNumberFirstSix": "string",
  "cardNumberLastFour": "string",
  "nameOnCard": "string",
  "nameOnCardLine2": "string",
  "startMmyy": "stri",
  "expiryMmyy": "stri",
  "cardLevelClassification": "CONSUMER",
  "expiryPeriodMonths": 1,
  "renewalType": "RENEW",
  "renewalTimestamp": 0,
  "creationTimestamp": 0,
  "cardholderMobileNumber": "string",
  "billingAddress": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "postCode": "string",
    "state": "string",
    "country": "st"
  },
  "physicalCardDetails": {
    "bulkDelivery": true,
    "productReference": "string",
    "carrierType": "string",
    "pendingActivation": true,
    "pinBlocked": true,
    "manufacturingState": "REQUESTED",
    "replacement": {
      "replacementReason": "DAMAGED",
      "replacementId": "string"
    },
    "deliveryAddress": {
      "name": "string",
      "surname": "string",
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "postCode": "string",
      "state": "string",
      "country": "st",
      "contactNumber": "string"
    },
    "deliveryMethod": "STANDARD_DELIVERY",
    "deliveryTrackingCode": "string",
    "deliveryTrackingMethod": "string",
    "deliveryTrackingUrl": "string",
    "nameOnCardLine2": "string"
  },
  "digitalWallets": {
    "pushProvisioningEnabled": true,
    "walletsEnabled": true,
    "artworkReference": "string"
  },
  "authForwardingDefaultTimeoutDecision": "APPROVE",
  "threeDSecureAuthConfig": {
    "linkedUserId": "string",
    "primaryChannel": "OTP_SMS",
    "fallbackChannel": "OTP_SMS"
  },
  "mode": "string",
  "externalData": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "userId": "string",
  "replacement": {
    "id": "string",
    "reason": "DAMAGED"
  }
}

Display the card number

Initialize the SDK with your UI keyUI key A public key that authorizes Weavr's Secure UI components - the inputs and displays in our Web, Android, iOS, and React Native SDKs that handle passwords, PINs, card details, and KYC/KYB flows. Unlike the API key, the UI key isn't an API credential; you don't call REST endpoints with it. It's safe to embed in client-side code, and Sandbox and Live each have their own UI key., associate the stepped-up auth token, then mount a cardNumber span on a placeholder element. The component requests 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. from inside its sandboxed iframe, so the full 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). renders without entering your page's JavaScript.

Card Number: <span id="cardNumber" />

<script type="text/javascript">
  window.OpcUxSecureClient.init("YOUR_UI_KEY");

  window.OpcUxSecureClient.associate(
    "Bearer YOUR_USER_AUTHENTICATION_TOKEN",
    function () {
      // Replace YOUR_CARDNUMBER_TOKEN with the tokenized card number from the server-side API call
      var span = window.OpcUxSecureClient.span(
        "cardNumber",
        "YOUR_CARDNUMBER_TOKEN"
      );
      span.mount(document.getElementById("cardNumber"));
    },
    function (e) {
      console.error("associate failed " + e);
    }
  );
</script>

---

CVV

Use it for: card details screens where the cardholder needs 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. for an online purchase, typically behind a reveal toggle.

Use 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. component to detokenize and show your customer's 3-digit 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..

Get the tokenized CVV

The same Get managed card call returns the tokenisedTokenize 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. 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. as cvv: { value: "<token>" } when your auth token is stepped up. Without step-up, cvv is absent or null — see Card response fields and step-up. Forward the token to the secure component in the next step.

Server-side only

You must perform this step on the server side of your app.

Step-up required

Your authentication token must be stepped-up before calling this component.

GET/managed_cards/${id}Try it

Response

{
  "id": "string",
  "profileId": "string",
  "externalHandle": "string",
  "tag": "string",
  "friendlyName": "string",
  "currency": "str",
  "state": {
    "state": "ACTIVE",
    "blockedReason": "USER",
    "destroyedReason": "SYSTEM"
  },
  "type": "VIRTUAL",
  "cardBrand": "MASTERCARD",
  "cardNumber": {
    "value": "string"
  },
  "cvv": {
    "value": "str"
  },
  "cardNumberFirstSix": "string",
  "cardNumberLastFour": "string",
  "nameOnCard": "string",
  "nameOnCardLine2": "string",
  "startMmyy": "stri",
  "expiryMmyy": "stri",
  "cardLevelClassification": "CONSUMER",
  "expiryPeriodMonths": 1,
  "renewalType": "RENEW",
  "renewalTimestamp": 0,
  "creationTimestamp": 0,
  "cardholderMobileNumber": "string",
  "billingAddress": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "postCode": "string",
    "state": "string",
    "country": "st"
  },
  "physicalCardDetails": {
    "bulkDelivery": true,
    "productReference": "string",
    "carrierType": "string",
    "pendingActivation": true,
    "pinBlocked": true,
    "manufacturingState": "REQUESTED",
    "replacement": {
      "replacementReason": "DAMAGED",
      "replacementId": "string"
    },
    "deliveryAddress": {
      "name": "string",
      "surname": "string",
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "postCode": "string",
      "state": "string",
      "country": "st",
      "contactNumber": "string"
    },
    "deliveryMethod": "STANDARD_DELIVERY",
    "deliveryTrackingCode": "string",
    "deliveryTrackingMethod": "string",
    "deliveryTrackingUrl": "string",
    "nameOnCardLine2": "string"
  },
  "digitalWallets": {
    "pushProvisioningEnabled": true,
    "walletsEnabled": true,
    "artworkReference": "string"
  },
  "authForwardingDefaultTimeoutDecision": "APPROVE",
  "threeDSecureAuthConfig": {
    "linkedUserId": "string",
    "primaryChannel": "OTP_SMS",
    "fallbackChannel": "OTP_SMS"
  },
  "mode": "string",
  "externalData": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "userId": "string",
  "replacement": {
    "id": "string",
    "reason": "DAMAGED"
  }
}

Display the CVV

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. component follows the same three calls as the card number - init, associate, then span("cvv", token) mounted on a placeholder. 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 entirely inside the iframe and the value is not exposed to your code.

Card CVV: <span id="cvv" />

<script type="text/javascript">
  window.OpcUxSecureClient.init("YOUR_UI_KEY");

  window.OpcUxSecureClient.associate(
    "Bearer YOUR_USER_AUTHENTICATION_TOKEN",
    function () {
      // Replace YOUR_CVV_TOKEN with the tokenized CVV from the server-side API call
      var span = window.OpcUxSecureClient.span("cvv", "YOUR_CVV_TOKEN");
      span.mount(document.getElementById("cvv"));
    },
    function (e) {
      console.error("associate failed " + e);
    }
  );
</script>

Pair this component with the reveal toggle pattern so 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. only renders when the cardholder requests it.

---

Show card PIN

Use it for: physical-card management screens where the cardholder needs to recover the existing 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., typically behind a reveal toggle.

Use the Show 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 to show the existing 4-digit 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. for a physical cardPhysical Card A payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use..

tip

Use this component only for physical cardsPhysical Card A payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use..

Get the tokenized PIN

Fetch the managed cardManaged Card A payment card (virtual or physical) that can be created and managed through the Weavr platform. Cards can operate in prepaid mode (with their own balance) or debit mode (linked to a managed account). All cards must be assigned to a card assignee who is an Authorised User. from your server. 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. 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. is returned as the pin field on the response; pass that token to the secure component in the next step.

caution

You must perform this step on the server side of your app.

warning

Your authentication token must be stepped-up before calling this component.

GET/managed_cards/${id}Try it

Response

{
  "id": "string",
  "profileId": "string",
  "externalHandle": "string",
  "tag": "string",
  "friendlyName": "string",
  "currency": "str",
  "state": {
    "state": "ACTIVE",
    "blockedReason": "USER",
    "destroyedReason": "SYSTEM"
  },
  "type": "VIRTUAL",
  "cardBrand": "MASTERCARD",
  "cardNumber": {
    "value": "string"
  },
  "cvv": {
    "value": "str"
  },
  "cardNumberFirstSix": "string",
  "cardNumberLastFour": "string",
  "nameOnCard": "string",
  "nameOnCardLine2": "string",
  "startMmyy": "stri",
  "expiryMmyy": "stri",
  "cardLevelClassification": "CONSUMER",
  "expiryPeriodMonths": 1,
  "renewalType": "RENEW",
  "renewalTimestamp": 0,
  "creationTimestamp": 0,
  "cardholderMobileNumber": "string",
  "billingAddress": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "postCode": "string",
    "state": "string",
    "country": "st"
  },
  "physicalCardDetails": {
    "bulkDelivery": true,
    "productReference": "string",
    "carrierType": "string",
    "pendingActivation": true,
    "pinBlocked": true,
    "manufacturingState": "REQUESTED",
    "replacement": {
      "replacementReason": "DAMAGED",
      "replacementId": "string"
    },
    "deliveryAddress": {
      "name": "string",
      "surname": "string",
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "postCode": "string",
      "state": "string",
      "country": "st",
      "contactNumber": "string"
    },
    "deliveryMethod": "STANDARD_DELIVERY",
    "deliveryTrackingCode": "string",
    "deliveryTrackingMethod": "string",
    "deliveryTrackingUrl": "string",
    "nameOnCardLine2": "string"
  },
  "digitalWallets": {
    "pushProvisioningEnabled": true,
    "walletsEnabled": true,
    "artworkReference": "string"
  },
  "authForwardingDefaultTimeoutDecision": "APPROVE",
  "threeDSecureAuthConfig": {
    "linkedUserId": "string",
    "primaryChannel": "OTP_SMS",
    "fallbackChannel": "OTP_SMS"
  },
  "mode": "string",
  "externalData": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "userId": "string",
  "replacement": {
    "id": "string",
    "reason": "DAMAGED"
  }
}

Display the PIN

Mount a cardPin span on a placeholder once the user is associated with a stepped-up token. The component de-tokenizesTokenize 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 4-digit 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. inside the iframe; your code never receives a copy of the value.

Card PIN: <span id="pin"></span>

<script type="text/javascript">
  window.OpcUxSecureClient.init("YOUR_UI_KEY");

  window.OpcUxSecureClient.associate(
    "Bearer YOUR_USER_AUTHENTICATION_TOKEN",
    function () {
      // Replace YOUR_PIN_TOKEN with the tokenized PIN from the server-side API call
      var span = window.OpcUxSecureClient.span("cardPin", "YOUR_PIN_TOKEN");
      span.mount(document.getElementById("pin"));
    },
    function (e) {
      console.error("associate failed " + e);
    }
  );
</script>

Pair this component with the reveal toggle pattern so the 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. only renders when the cardholder requests it.

Capture card PIN

Use it for: the physical-card upgrade or activation screen, when you let the cardholder choose their own 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..

Use the 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 to let your customer choose a specific 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. when upgrading a virtual cardVirtual Card A payment card that is created instantly and can be used for e-commerce and online purchases. Virtual cards are issued through the Mastercard network and are automatically enrolled in the 3D Secure program for increased security and limited fraud risk. They can be created in prepaid or debit mode. to physical. If you don't capture a 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 system assigns a random one.

tip

Use this component only when issuing physical cardsPhysical Card A payment card that is printed or embedded in wearables and sent to customers directly. Physical cards are created by first creating a virtual card and then upgrading it to a physical card. They are sent in an inactive state and must be activated by the card assignee before first use..

Input behaviour to plan around

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 has two limitations to plan around:

• It renders the four digits in cleartext while the customer types - there is no built-in character mask.
• It captures a single entry with no built-in confirmation field.

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. still happens inside the sandboxed iframe, so the digits never reach your code; these are rendering and flow constraints, not security ones. Neither is fully fixable from the integration side. See Behaviour and UX guidance for the mitigations that are available - and for why a second cardPin input can't stand in as a confirmation step.

Capture the new PIN

Create a form with OpcUxSecureClient.form(), mount a cardPin input inside a placeholder, and call form.tokenize() from your submit handler to exchange the entry for an opaque token. The component accepts only numeric input and fires a submit event once four digits have been entered.

<form onSubmit="onSubmit(); return false;">
  Card Pin:
  <div id="cardpin"></div>
  <br />
  <input type="submit" value="Update Card PIN" />
</form>

<script type="text/javascript">
  window.OpcUxSecureClient.init("YOUR_UI_KEY");

  var form = window.OpcUxSecureClient.form();

  window.OpcUxSecureClient.associate(
    "Bearer YOUR_USER_AUTHENTICATION_TOKEN",
    function () {
      var input = form.input("cardPin", "cardPin");
      input.mount(document.getElementById("cardpin"));

      input.on("submit", () => {
        console.log("submit cardPin input");
      });
    }
  );

  function onSubmit() {
    form.tokenize(function (tokens) {
      console.log(tokens);
    });
  }
</script>

Behaviour and UX guidance

The constraints called out preceding the code sample - cleartext rendering during entry and no built-in confirmation - are limitations of the Web component as it ships today. The equivalent component on our iOS, Android, and React Native SDKs uses native secure text fields and masks each digit on entry. We're considering both masked entry and an optional confirmation field as enhancements to the Web component; if either is a blocker for your integration, raise it with our support team so we can prioritize based on demand.

Until those enhancements ship, the following pattern keeps the flow safe and clear for the customer.

• Set expectations on the page. Add a short instruction next to the input - for example, "We'll show the digits as you type, so make sure no one is looking over your shoulder." This turns the cleartext rendering into intentional behaviour rather than a surprise.
• Encourage a visual review before submission. Because the customer can read what they typed, prompt them to verify the four digits before continuing. This compensates, in part, for the missing confirmation field.
• Auto-advance on the fourth digit. The component fires a submit event as soon as four digits have been entered. Use that event to either 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. immediately or to focus an explicit "Confirm 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." button, so the digits don't sit on screen any longer than necessary.
• Don't try to build a confirmation step using a second cardPin input. Each input is 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. independently, and the resulting tokens are not comparable in your app. A "re-enter 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." field cannot be matched client-side and would only widen the on-screen exposure of the digits.
• Unmount the input as soon as tokenize() returns. The iframe serves no further purpose once you have the token, and removing it clears the digits from the page.

The token-comparability point is worth re-emphasizing. 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. is a one-way step: the same 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. typed twice does not produce the same token, and your code never sees either underlying value, so a custom confirmation step on top of two cardPin inputs cannot work. A confirmation field has to live inside the secure component for matching to be possible, which is why it requires a product-side change rather than an integration pattern.

Set the card's PIN

Pass 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. 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. to the upgrade endpoint from your server.

caution

You must perform this step on the server side of your app.

POST/managed_cards/${id}/physicalTry it

Request

{
  "productReference": "string",
  "carrierType": "string",
  "deliveryMethod": "STANDARD_DELIVERY",
  "deliveryAddress": {
    "name": "string",
    "surname": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "postCode": "string",
    "state": "string",
    "country": "st",
    "contactNumber": "string"
  },
  "activationCode": "string",
  "pin": {
    "value": "string"
  },
  "nameOnCardLine2": "string",
  "bulkDelivery": true
}

Response

{
  "id": "string",
  "profileId": "string",
  "externalHandle": "string",
  "tag": "string",
  "friendlyName": "string",
  "currency": "str",
  "state": {
    "state": "ACTIVE",
    "blockedReason": "USER",
    "destroyedReason": "SYSTEM"
  },
  "type": "VIRTUAL",
  "cardBrand": "MASTERCARD",
  "cardNumber": {
    "value": "string"
  },
  "cvv": {
    "value": "str"
  },
  "cardNumberFirstSix": "string",
  "cardNumberLastFour": "string",
  "nameOnCard": "string",
  "nameOnCardLine2": "string",
  "startMmyy": "stri",
  "expiryMmyy": "stri",
  "cardLevelClassification": "CONSUMER",
  "expiryPeriodMonths": 1,
  "renewalType": "RENEW",
  "renewalTimestamp": 0,
  "creationTimestamp": 0,
  "cardholderMobileNumber": "string",
  "billingAddress": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "postCode": "string",
    "state": "string",
    "country": "st"
  },
  "physicalCardDetails": {
    "bulkDelivery": true,
    "productReference": "string",
    "carrierType": "string",
    "pendingActivation": true,
    "pinBlocked": true,
    "manufacturingState": "REQUESTED",
    "replacement": {
      "replacementReason": "DAMAGED",
      "replacementId": "string"
    },
    "deliveryAddress": {
      "name": "string",
      "surname": "string",
      "addressLine1": "string",
      "addressLine2": "string",
      "city": "string",
      "postCode": "string",
      "state": "string",
      "country": "st",
      "contactNumber": "string"
    },
    "deliveryMethod": "STANDARD_DELIVERY",
    "deliveryTrackingCode": "string",
    "deliveryTrackingMethod": "string",
    "deliveryTrackingUrl": "string",
    "nameOnCardLine2": "string"
  },
  "digitalWallets": {
    "pushProvisioningEnabled": true,
    "walletsEnabled": true,
    "artworkReference": "string"
  },
  "authForwardingDefaultTimeoutDecision": "APPROVE",
  "threeDSecureAuthConfig": {
    "linkedUserId": "string",
    "primaryChannel": "OTP_SMS",
    "fallbackChannel": "OTP_SMS"
  },
  "mode": "string",
  "externalData": [
    {
      "name": "string",
      "value": "string"
    }
  ],
  "userId": "string",
  "replacement": {
    "id": "string",
    "reason": "DAMAGED"
  }
}

info

For more information on upgrading virtual cards to physical, see the linked guide.