Skip to main content

Virtual cards

Virtual cardsVirtual 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. are created instantly and can be used for e-commerce, online purchases, and provisioning to digital wallets. Every 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. starts as 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.; 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. are created as an upgrade from a virtual one.

Prerequisites​

  • An onboarded corporate or consumer identity that's 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.- or 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.-approved. This identity is the card owner.
  • An authenticated end-user token for a user that belongs to the card ownerCard Owner The individual or business entity that owns the cards and the funds available to be spent via card purchases. Before cards can be issued, the card owner must be onboarded on Weavr, including completing a KYB process for business card owners or a KYC process for individual card owners..
  • A card profileId from the Weavr Portal > API Credentials. See card profiles and card modes for how profilesProfile 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. work.
  • (For an immediately active card) A card user with all mandatory information, and a stepped-up token - required to return sensitive card details in the response.

Create a virtual card​

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

The userId you pass links the card to a card user. The state of the card on creation depends on whether the linked user is fully set up:

Linked userIdCard state on create
Not providedNOT_ENABLED
Provided, but the linked user has incomplete informationNOT_ENABLED
Provided, and all mandatory information is presentACTIVE

A NOT_ENABLED card transitions to ACTIVE automatically (and a webhook is sent) once all the mandatory user information is provided. Until then, sensitive card details aren't accessible and the card can't be provisioned to a wallet or upgraded to physical.

Why is nameOnCard separate?

Cards accommodate fewer characters than the Authorized UserAuthorized User An individual that has been invited by the root user to manage an identity's instruments and transactions. They are not the legal owner of the identity but can be granted access to perform operations on behalf of the identity. For corporates, card assignees are created as Authorized Users. US-English variant of _Authorised User_. name fields allow. Wherever possible, nameOnCard should match the card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds.'s name; otherwise use a shortened version. This is the name the card userCard User The person that a card is assigned to and who will use the card for purchases. Weavr does not support anonymous cards, and therefore all cards must be linked to a card user before a card can be used. For consumers, the card owner and the card user is typically the same person. For corporates, the card users are employees or individuals authorised to spend the corporate's funds. quotes when an online merchant asks for the "card holder" name.

Retrieve a card​

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

The fields returned depend on the caller, the token, and the card state. Sensitive details (cardNumber and cvv) are returned only when all of the following are true:

  • The caller is the linked user or a user with the Admin role.
  • The token is stepped-up.
  • The card is ACTIVE, or has previously been ACTIVE (so BLOCKED and DESTROYED cards that were active also return sensitive details).

Otherwise, only non-sensitive details are returned.

CallerTokenCard stateResponse
Linked userStepped-upACTIVESensitive/all details
Linked userStepped-upNOT_ENABLEDNon-sensitive details only
Linked userNot stepped-upACTIVENon-sensitive details only
Admin (own card)Stepped-upACTIVESensitive/all details
Admin (other's card)Stepped-upACTIVESensitive/all details
Cards Management Role (other's card)Stepped-upACTIVENon-sensitive details only

Sensitive card data is 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. in the response. See tokenisation for how to handle it.

Next steps​