Cards (Web SDK)

When you retrieve a customer's card details from our API, sensitive fields are tokenized. To show a tokenized field to the cardholder, mount the matching display component — the SDK detokenizes 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. PIN, 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 tokenized 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.

Build a reveal toggle

A common UX pattern is hiding the CVV or PIN behind a reveal toggle so the value only appears when the cardholder asks for it. Our SDK handles the secure rendering, but the toggle 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

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

Get the tokenized card number

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 card number

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

Get the tokenized CVV

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 CVV

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 CVV only renders when the cardholder requests it.

Show card PIN

Use the Show card PIN component to show the existing 4-digit PIN 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

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"
  }
}

The tokenized PIN is returned in the response body as the pin field on 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. resource.

Display the PIN

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 PIN only renders when the cardholder requests it.

Capture card PIN

Use the Capture card PIN component to let your customer choose a specific PIN 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 PIN, 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..

Capture the new PIN

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

Set the card's PIN

Pass the tokenized PIN 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.