Skip to main content

Viewing and managing cards

Cards are the most visible feature of most embedded finance apps. This page builds the card experience end to end: issuing a card, listing a customer's cards, showing sensitive details safely, and running the lifecycle - block, replace, remove.

Where this fits

This page assumes you've built authentication. Every call here carries the customer's api-key and a logged-in user's Auth Token, and showing card details requires a stepped-up token.

Here's the card screen you'll build. The safe-to-show fields are plain reads, while the 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. render inside secure components - each 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. shows which:

your app

Your card

Virtual · active

Marketing card£1,240.00
API · data sourceGET/managed_cards/{id}Card name and balanceThe safe-to-show fields - card name, state, and balance - come from a plain read on your backend.View docs →
Card number4111 2222 3333 4444
SDK componentOpcUxSecureClient.span("cardNumber")Card numberThe full PAN renders inside a sandboxed secure view that detokenizes on demand - your code never reads it.View docs →
CVV•••
SDK componentOpcUxSecureClient.span("cvv")CVVThe 3-digit security code renders in a tokenized view. Build your own reveal toggle to defer detokenization.View docs →
Freeze card
API · data sourcePOST/managed_cards/{id}/blockFreeze cardLifecycle transitions - freeze, unfreeze, report, remove - are each one call from your backend.View docs →
SDK component (renders the area)API endpoint (the data source)

Hover or focus a numbered pin to see which Weavr secure component renders the area, or which API endpoint supplies its data - then click to open the docs.

Prerequisites​

Before your app can issue a card, the customer needs:

  • A verified corporate or consumer.
  • A card profile configured in the Embedder PortalEmbedder Portal A web-based portal where embedders can access their Weavr account, manage API credentials, configure settings, view dashboards, and access documentation. The portal provides access to both sandbox and production environments, with separate credentials for each. - it sets the card type, mode, currencies, and 3D Secure behaviour.
  • A card user - every card must be linked to a user, so onboard an authorised user (the Card AssigneeCard Assignee The person that a card is assigned to and who will use the card. For consumers, the card owner and card assignee are the same person. For corporates, the card assignee and card owner are different entities - the corporate is the card owner and the person using the card is the card assignee. Card assignees must be created as Authorised Users. role is built for this).

Step 1: Issue a card​

Cards come in two types, and you choose per card profile:

  • Virtual cards - created instantly, ready for online purchases, and automatically enrolled in 3D Secure.
  • Physical cards - printed and shipped, always created as an upgrade from 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.. Customise the card stock to your brand.

Create 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. from your backend, passing the profileProfile A template defining the configuration for one type of object - corporate identity, consumer identity, managed account, managed card, transfer, or outgoing wire transfer. When you create one of these objects you reference its Profile ID, which tells Weavr which limits, currencies, supported countries, branding, and fees to apply. Your programme ships with one or more Profile IDs per supported object type. ID and the linked user's userId:

POST/managed_cardsTry it 
{
  "profileId": "string",
  "tag": "string",
  "friendlyName": "string",
  "nameOnCard": "string",
  "nameOnCardLine2": "string",
  "cardholderMobileNumber": "string",
  "billingAddress": {
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "postCode": "string",
    "state": "string",
    "country": "st"
  },
  "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"
    }
  ],
  "renewalType": "RENEW",
  "userId": "string"
}

To ship 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., upgrade the 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.:

POST/managed_cards/{id}/physicalTry it 
{
  "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
}
Cards need a fully set-up user

A card links to a user, and that user needs a name, verified email, an enrolled device, and a date of birth. Until those are in place the card stays in NOT_ENABLED and flips to ACTIVE automatically once complete. See create a virtual card for the full rules.

Step 2: List and view cards​

Your card screen lists the customer's cards and opens one for detail. Both are plain reads from your backend.

GET/managed_cardsTry it 
{
  "cards": [
    {
      "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"
      }
    }
  ],
  "count": 0,
  "responseCount": 0
}
GET/managed_cards/{id}Try it 
{
  "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"
  }
}

These responses carry the safe-to-show fields - card name, cardNumberFirstSix, cardNumberLastFour, state, balance. They do not carry the full card number or 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. unless your token is stepped up. That's the next step.

Step 3: Show the full card number, CVV, and PIN securely​

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)., 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. are PCI-sensitive, so they never travel to your app as plain values. Weavr's tokenization model keeps them off your servers entirely:

  1. Step up the user's token. Sensitive card fields are gated behind Strong Customer Authentication. Trigger a step-up and have the user clear the second factor.
  2. Re-fetch the card. With a 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., GET /managed_cards/{id} returns cardNumber and cvv as { "value": "<token>" } wrappers - a secure token, not the raw value.
  3. Render the token in a card component. Pass the token into the SDK card component, which displays the real value inside a sandboxed view that your code can't read.

Mount the card component on your platform:

  • Web - show 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..
  • iOS, Android, React Native - the same, plus push provisioning to add the card to Apple Pay or Google Pay.
Guard for the gated fields

Without step-up, cardNumber and cvv are absent, so read them defensively (response.cardNumber?.value). Triggering step-up and re-fetching returns 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. fields on the next response. See card response fields and step-up.

Step 4: Run the card lifecycle​

After a card is live, your app drives it through card lifecycle management. A card is always ACTIVE, BLOCKED, or DESTROYED, and each transition is one call from your backend.

User action in your appEndpointEffect
Freeze a cardPOST /managed_cards/{id}/blockBlocks the card; funds frozen.
Unfreeze a cardPOST /managed_cards/{id}/unblockUnblocks a user-blocked card.
Report a card lostPOST /managed_cards/{id}/physical/report_lostBlocks with reason LOST.
Report a card stolenPOST /managed_cards/{id}/physical/report_stolenDestroys the card immediately.
Replace a lost/stolen cardPOST /managed_cards/{id}/physical/replace_lost_stolenIssues a new card, moves the balance.
Activate 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.POST /managed_cards/{id}/physical/activateActivates a shipped card.
Remove a cardPOST /managed_cards/{id}/removeRemoves an empty card permanently.
Keep your UI in sync

Weavr also triggers some transitions itself - expiry, system blocks, compromise detection. Subscribe to card webhook events so your app reflects state changes it didn't initiate.

What you've built​

Your app can now issue virtual and 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., list and open them, reveal the sensitive details without ever holding them, and run the full lifecycle.

Next, let your customers spend and move that money: making payments.