Add virtual cards

You can add one or multiple virtual cards, as well as single-use virtual cards. After adding a virtual card, you can update that card, view sensitive card information, and cancel or deactivate the card.

Prerequisites

You need to add account memberships before creating cards. Follow the guides to add one membership or multiple memberships.

Add a virtual card

Add a new card for an existing account member by calling the addCard mutation. This mutation can only be called on behalf of an account member with the canManageAccountMembership rights. When you do this, make sure you are authenticated with a user access token in the name of the account member.

The new card is thus created with the ConsentPending status. A consentUrl is returned which invites the user to start Strong Customer Authentication with Swan. After the user completes the Strong Customer Authentication process, the new card changes to Activated status.

In the mutation, you can use cardProductId field (optional) to choose which card design the user will receive. If don't use this field, they'll receive your default card product design.

Users can add virtual cards

Users with CanManageCards permission can add their own virtual card directly from Swan's Web Banking interface, and they can use the virtual card immediately.

Mutation

🔎 Open the mutation in API Explorer

mutation AddVirtualCard {
  addCard(
    input: {
      accountMembershipId: "$YOUR_ACCOUNT_MEMBERSHIP_ID"
      withdrawal: true
      international: true
      nonMainCurrencyTransactions: true
      eCommerce: true
      consentRedirectUrl: "$REDIRECT_URL"
      name: "My First Swan Card"
    }
  ) {
    ... on AddCardSuccessPayload {
      __typename
      card {
        statusInfo {
          ... on CardConsentPendingStatusInfo {
            __typename
            consent {
              consentUrl
            }
          }
        }
        id
      }
    }
  }
}

Payload

{
  "data": {
    "addCard": {
      "__typename": "AddCardSuccessPayload",
      "card": {
        "statusInfo": {
          "__typename": "CardConsentPendingStatusInfo",
          "consent": {
            "consentUrl": "$YOUR_CONSENT_URL"
          }
        },
        "id": "$YOUR_CARD_ID"
      }
    }
  }
}

Add multiple virtual cards

Add multiple cards to different existing account members by calling the addCards mutation. It works nearly the same way as addCard with two additional features:

Add the physical card at the same time you add the virtual card by using the physicalCard field in the addCards mutation, plus entering a delivery address.
Configure the spending limit when adding the card with the spendingLimit field in the addCards mutation.

The cards are created asynchronously and then change to the Enabled status.

Depending on how many cards you're creating, it can take up to several minutes to complete the process. For performance reasons, you can create up to 250 cards per API call.

Print physical cards when adding virtual cards

Please refer to the guides in the physical cards section to learn more about creating virtual and physical cards at the same time. These guides cover settings, spending limits, and allowing your cardholders to choose their own PIN.

Add single-use virtual cards

Add new single-use virtual cards to an existing account member by calling the addSingleUseVirtualCard mutation.

This mutation can be called on behalf of any account member with the permission canManageCards. The permission canManageAccountMembership is optional. Learn more about permissions and card management.

When you do this, make sure you are authenticated with a user access token using the name of the card's account member. The new card is thus created with the ConsentPending status and a consentUrl is returned which invites the user to start the Strong Customer Authentication with Swan. After the user completes the Strong Customer Authentication process, the new card changes to Enabled status.

The Single Use Virtual Card is never renewed. It cannot be physically printed, and it can't be added to digital Wallets (Apple or Google).

Single-use virtual cards & server-to-server consent

If you want to issue single-use virtual cards without having direct human interaction to consent and reveal card numbers, you must be the account holder (not available for end-users) and have server-to-server consent implemented.

For both the single-use virtual card mutations (addSingleUseVirtualCard and addSingleUseVirtualCards), the SuccessForProjectOwnerPayload will return a card in ConsentPending status. The status changes to Enabled after the consent is validated. It's recommended to verify the card status before using it.

Add virtual cards

Add a virtual card​

Mutation​

Payload​

Add multiple virtual cards​

Print physical cards when adding virtual cards​

Add single-use virtual cards​