Manage Virtual Cards

Provides a virtual credit card that a user can use to make purchases.

Virtual cards are a core component of the Virtual Cards SDK. Virtual cards are used as a proxy between a user's personal Funding Source and online merchants.

In order to provision and use a virtual card, a Sudo and Funding Source are required.

Virtual cards make an important distinction between two subtypes: ProvisionalVirtualCard and VirtualCard.

A ProvisionalVirtualCard is a card that is currently being provisioned. This will typically exist in 3 different states: PROVISIONING, COMPLETED, and FAILED. It also contains a property card which contains the provisioned card, when it has COMPLETED. This type is transitory and should only be used for determining whether a card is provisioning, or has failed provisioning. Accessing provisioned cards should be done using methods that return Card types.

A VirtualCard is a card that has successfully finished provisioning. This is the card type that represents virtual cards.

Closed Cards

Cards will be closed and set to a CLOSED state under the following circumstances:

  • The card has expired; this occurs when your card reaches its expiry date.

  • The card has been closed via the cancel card API.

  • The Sudo owning the card has been deleted.

While provisional card records are transient, a card record is not. Cards will always be available for access via access methods even when closed. It is important to maintain a record of closed cards so that users can still examine the transaction history and also see any refunds that may still occur against the closed card from merchants where the card was used before the card was closed.

Orphan Cards

When a Sudo is deleted, any virtual cards owned by that Sudo will be closed and the entry for the Sudo in the owners property of any virtual cards owned by that Sudo will be removed. Such cards are called orphan cards and can be identified by looking for cards with no Sudo owner in the owners property. Sudo owners are identified as owners with issuer of value sudoplatform.sudoservice.

Provisioning a Virtual Card

A virtual card is provisioned by calling the provisionVirtualCard method.

An ownershipProofToken is required as part of the input. This ties together the Sudo and virtual card such that the Sudo becomes the owner of the virtual card. Use the getOwnershipProof method on the SudoProfilesClient in the Sudo Profiles SDK in order to obtain an ownershipProofToken. See the Sudo section for more information.

The fundingSourceId is another required input parameter and is used to associate the virtual card with a funding source used to fund that particular virtual card.

Input properties cardHolder, billingAddress, and metadata are indicative of the user's information that they wish to be associated with the card.

cardHolder is the name that will appear on the card and is needed to perform transactions.

billingAddress is an optional property that the user can provide. If this is left undefined/nil/null, the billingAddress will be set by the platform itself.

metadata is a JSON object that contain application specific information about each virtual card. Examples of such information include an alias for the virtual card to help the user remember why they created it or perhaps a color for the virtual card to be rendered in by the application.

The currency is the three character ISO 4217 alphabetic currency code of the currency in which the virtual card is to be denominated.

Currently only USD is supported.

A call to the provisionVirtualCard method initiates the process of provisioning a virtual card and will return a ProvisionalCard on completion. During this process the ProvisionalCard traverses between a PROVISIONING and COMPLETED state.

To check the provisioning state after calling this API, calls to getProvisionalCard is used to poll for state changes of a card during its provisioning cycle. Once the ProvisionalCard has reached a COMPLETED state, the fully provisioned card can be accessed via the card property on the card (or via get/list of virtual cards).

try {
  const provisionalCard = await virtualCardsClient.provisionVirtualCard({
    // Refer to Sudo Profiles SDK for the information on how to obtain
    // a Sudo ownership proof. The audience parameter for the ownership
    // proof must be "sudoplatform.virtual-cards.virtual-card" to be
    // able to provision a virtual card for a Sudo.
    ownershipProofs: [ownershipProof],
    fundingSourceId: fundingSource.id,
    currency: 'USD',
    cardHolder: 'John Smith',
    billingAddress: {
      addressLine1: '123 Street Rd',
      addressLine2: undefined,
      city: 'Salt Lake City',
      state: 'UT',
      postalCode: '84044',
      country: 'US',
    },
    metadata: {
      alias: 'Shopping',
    }
  })
} catch (error) {
  // Handle/notify user of error.
}

Updating a Virtual Card

The user may want to update details on their virtual card. The updateVirtualCard method is used to do this.

The modifiable fields of a virtual card are contained in the UpdateVirtualCardInput:

  • cardHolder

  • metadata

  • billingAddress

  • alias

These fields can all be updated independently.

The alias property is deprecated and replaced by the more general metadata property. To record an alias property for a card, set an alias property in the metadata JSON object.

A SingleAPIResult type is returned from this method call which contains the status of the update operation. Two possible statuses can be returned:

StatusDefinition

Success

The virtual card succeeded to update and the returned virtual card decrypted successfully.

Partial

The virtual card updated successfully however the returned virtual card failed to decrypt. The return object will include the virtual card without the decrypted fields and an associated error.

If you only want to update the alias to 'Banking' and the cardHolder to 'J Smith' then the API should be called like so:

try {
  const result = await virtualCardsClient.updateVirtualCard({
    id: card.id,
    expectedCardVersion: card.version,
    cardHolder: 'J Smith',
    metadata: {
      alias: 'Banking'
    }
  })
  if (result.status === APIResult.Success) {
    const card = result.result
  } else if (result.status === APIResult.Partial) {
    const cardMetadata = result.item
    const error = result.cause
  } 
} catch (error) {
  // Notify/handle errors
}

The virtual card metadata property is a single attribute and all metadata properties must be specified on each update.

Canceling a Virtual Card

A virtual card can be cancelled using the cancelVirtualCard method by passing in the id of an existing virtual card object.

This API call is idempotent, so any subsequent call to cancel with the same id will always yield the same result.

When cancelling a virtual card, the card will not be deleted, but instead will be transitioned to the CLOSED state and remain accessible via retrieval methods. Closed cards remain available so that transaction history can be retained and so that refunds that happen after the card is closed can be shown.

Once a virtual card is cancelled and its state is set to CLOSED, it cannot be reactivated - a new virtual card will need to be provisioned.

A SingleAPIResult type is returned from this method call which contains the status of the cancellation operation. Two possible statuses can be returned:

StatusDefinition

Success

The virtual card succeeded to cancel and the returned virtual card decrypted successfully.

Partial

The virtual card cancelled successfully however the returned virtual card failed to decrypt. The return object will include the virtual card without the decrypted fields and an associated error.

// Collect the input virtual card id however makes sense for your implementation.
try {
  const result = await virtualCardsClient.cancelVirtualCard({ id: card.id })
  if (result.status === APIResult.Success) {
    const card = result.result
  } else if (result.status === APIResult.Partial) {
    const cardMetadata = result.item
    const error = result.cause
  }
} catch (error) {
  // Handle/notify error
}

Retrieving Virtual Cards

Previously provisioned (or closed and suspended) virtual cards can be accessed in two ways: via its identifier (Single Virtual Card by Id), or via a list method (Multiple Provisioned Virtual Cards).

A fetch of single or multiple virtual cards can be performed remotely or locally by specifying the appropriate CachePolicy as part of the input.

Single Virtual Card by Id

To retrieve a single virtual card given its unique id, use the getVirtualCard method. This method will return the record if it exists.

try {
  const virtualCard = await virtualCardsClient.getVirtualCard({
    id,
    cachePolicy: CachePolicy.RemoteOnly
  })
  // `virtual card` contains the virtual card object, else `undefined` if not found.
} catch (error) {
  // Handle/notify error
}

Multiple Provisioned Virtual Cards

The ability to retrieve multiple or all virtual cards available to the user is supported. These results can be paginated and can contain virtual cards in various states.

A call to a list API will return a ListVirtualCardsResult with a status and depending on the status, a list of matching items and a nextToken to support pagination. If no results matching the input are found, the result will contain empty items. There can be three possible statuses returned:

StatusDefinition

Success

A list of all requested virtual cards are returned.

Partial

A list of all virtual cards that were successfully fetched and decrypted are returned as well as a list of all virtual cards that failed to decrypt successfully, including an error indicating the reason for the failure.

Failure

All virtual cards failed to be fetched or decrypted. Contains an error indicating the reason for the failure.

A virtual card may fail to be unencrypted if the version of the client is not up-to-date or if the required cryptographic key is missing from the client device.

All Provisioned Virtual Cards

To retrieve multiple virtual cards that are owned by the signed in user, call the listVirtualCards method.

try {
  const result = await virtualCardsClient.listVirtualCards({
      cachePolicy: CachePolicy.RemoteOnly,
      limit: 20,
      nextToken
  })
  if (result.status === ListOperationResultStatus.Success) {
      // `result.items` contains the list of items matching the input.
      // Page through the results if result.nextToken != undefined. 
  } else if (result.status === ListOperationResultStatus.Partial) {
     // `result.items` contains the list of items matching the input that decrypted successfully.
     // `result.failed` contains the list of items that failed decryption with associated error.
     //  Page through the results if `partial.nextToken` != undefined.
  } else {
     // `result.cause` contains the error which caused the failure.
  }
} catch (error) {
  // Handle/notify error
}

Last updated