Skip to main content

Virtual cards

Swan's default, dematerialized cards. A virtual card must exist before creating a physical card or adding a card to a digital Wallet. Virtual cards are also available in a single-use format.

Whenever you issue a new card, a virtual card number is created and enabled instantly, and the cardholder can start using it online right away. The virtual card must exist before a physical card can be printed or a virtual card added to a digital wallet.

A virtual card represents the card contract for all associated cards. After adding a virtual card, you can update that card, view sensitive card information, and cancel or deactivate the card. If you deactivate a virtual card, all physical and digital cards attached to it are also deactivated.

Card number & PIN​

Each virtual card has a unique card number, different even from a physical card added at the same time. Virtual cards don't have a PIN (Personal Identification Number).

Swan makes the virtual card's number, CVC, and expiry date available in Web Banking. The card number and CVC are considered sensitive data and must be masked by default. The cardholder must complete a consent request before the numbers can be unmasked.

Virtual & physical card numbers

Why do virtual and physical cards have different card numbers and CVCs? The two card types function as independent entities. Each has its own transaction history, can be added to the same digital wallet, and more.

This also means that if a cardholder loses their physical card, they can suspend or cancel the physical card without losing access to their virtual card.

Single-use virtual cards​

Single-use virtual (SUV) cards can either be used once or for one dedicated merchant. Therefore, you can consider SUV card use like this: they're for (a) one time, or (b) one place.

Because of their very limited scope, users can avoid 3-D Secure (3DS) consent when paying with SUV cards. SUV cards can be either one-off or recurring.

One-off​

One-off SUV cards, in theory, work one time for one transaction. It's not that simple, however, because some merchants send multiple authorizations for a single debit. Pre-authorization is a good example, as the merchant pre-authorizes an amount, and then a separate transaction is created for the actual debit.

Ideally, the card issuer (you or your customer) should cancel one-off SUV cards after the expected debit has been used. Note that setting a spending limit is mandatory. Consider setting the expected debit amount as the spending limit, rendering the card unusable after that limit is reached.

For one-off cards, the AccountHolderSpendingLimit.period is Always.

Recurring​

You can think of recurring SUV cards as single merchant virtual cards. The AccountHolderSpendingLimit.period is not Always.

When the cardholder uses a recurring SUV card for the first time, Swan restricts the card to the merchant ID that triggered the authorization.

If the card is used with the same merchant, the merchant ID matches and the transaction can go through. However, if the cardholder tries to use the card elsewhere, the transaction will be rejected because the merchant IDs don't match.

Virtual card statuses​

These statuses also represent the status of the Swan card contract.

Virtual card statusExplanation
ConsentPendingVirtual card was added and is waiting for the cardholder's consent

Next steps:
  • If consent is refused or fails, the status moves directly to Canceled
  • Otherwise, the status moves to Processing
ProcessingConsent has been received and the card is being prepared

Status used uniquely when adding multiple virtual cards (addCards mutation)
EnabledVirtual card is available for use
CancelingCard is in the process of being canceled

After a card is assigned the Canceling status, the process can't be reversed
CanceledCard is canceled, no longer available for use, and can't be reactivated

Guides​