Create Virtual Card

Use the createVirtualCard mutation to create a virtual card with configurable funding sources, limits, and lifecycle controls. This mutation requires a CreateVirtualCardInput object and CREATE_VIRTUALCARD scope.

Sandbox Valid Virtual Card Test Offers:

Important Considerations for Virtual Card Creation

• Funding Source: You can fund your virtual cards using either your Fluz balance or a linked bank account as the primary funding source.
  • If you select a bank account as the primaryFundingSource, you must provide the bankAccountId.
• Spend Limits: The spendLimit you set must adhere to the program's defined spend limits for the chosen spendLimitDuration. An error will occur if the limit is exceeded.
• Balance Composition: By default, virtual cards may be funded by a combination of your specified spend account, prepaid (gift card) balance, and rewards balance when available. You can restrict the card to draw only from the spend account by setting usePrepaymentBalance: false and useRewardsBalance: false in the input.
• Transaction Annotations: You may optionally attach a memo and/or transactionCategory at card creation time. These will be associated with the resulting transaction for tracking and organization purposes.
  • If transactionCategory is provided, a matching category will be found or created for the account.
  • attachmentId is not supported

Arguments

• input (CreateVirtualCardInput!): The input object containing details for the new virtual card.

CreateVirtualCardInput Fields

VirtualCardBillingAddressInput Fields

cURL Example

curl -X POST \
  https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_USER_ACCESS_TOKEN' \
  -d '{
    "query": "mutation CreateVirtualCard { createVirtualCard( input: { spendLimit: 150.00, idempotencyKey: \"63b2c9e0-62d1-42ab-b1c2-1a7ee2f8c0a9\", offerId: \"b3355504-ad30-4b2f-873d-b8795277b918\", spendLimitDuration: MONTHLY, lockCardNextUse: false, cardNickname: \"My New Test Card\", primaryFundingSource: FLUZ_BALANCE, memo: \"Office supplies\", transactionCategory: \"Expenses\" } ) { virtualCardId userId cardholderName expiryMonth expiryYear virtualCardLast4 status cardType initialAmount usedAmount createdAt } }"
  }'

Sample Mutation

mutation {
  createVirtualCard(
    input: {
      idempotencyKey: "07df5653-43a8-4532-9881-3ab5857bbe12"
      spendLimit: 123.45
      spendLimitDuration: DAILY
      lockDate: "2030-10-10"
      lockCardNextUse: true
      cardNickname: "xyz789"
      primaryFundingSource: FLUZ_BALANCE
      offerId: "b3355504-ad30-4b2f-873d-b8795277b918"
      userCashBalanceId: "b1155504-ad30-4b2f-873d-b8795277b128"
    }
  ) {
    virtualCardId
    userId
    cardholderName
    expiryMonth
    expiryYear
    virtualCardLast4
    status
    cardType
    initialAmount
    usedAmount
    createdAt
  }
}

Sample Mutation — Cash-Only Balance

Restrict a virtual card to draw only from the specified userCashBalanceId, excluding prepaid and rewards funds.

mutation {
  createVirtualCard(
    input: {
      idempotencyKey: "07df5653-43a8-4532-9881-3ab5857bbe13"
      spendLimit: 150.00
      offerId: "b3355504-ad30-4b2f-873d-b8795277b918"
      primaryFundingSource: FLUZ_BALANCE
      userCashBalanceId: "b1155504-ad30-4b2f-873d-b8795277b128"
      usePrepaymentBalance: false
      useRewardsBalance: false
    }
  ) {
    virtualCardId
    virtualCardLast4
    status
    initialAmount
  }
}

Sample Response

{
  "data": {
    "createVirtualCard": {
      "virtualCardId": "07df5653-43a8-4532-9881-3ab5857bbe11",
      "userId": "07df5653-43a8-4532-9881-3ab5857bbe11",
      "cardholderName": "xyz789",
      "expiryMonth": "12",
      "expiryYear": "27",
      "virtualCardLast4": "7890",
      "status": "ACTIVE",
      "cardType": "MULTI_USE",
      "initialAmount": 150.00,
      "usedAmount": 0,
      "createdAt": "2025-07-09T10:00:00Z"
    }
  }
}

Response Field Explanations

• virtualCardId (UUID): The unique identifier assigned to the newly created virtual card.
• userId (UUID): The unique identifier of the user who created this virtual card.
• cardholderName (String): The name of the cardholder as it appears on the virtual card.
• expiryMonth (String): The two-digit expiration month of the virtual card (e.g., "12" for December).
• expiryYear (String): The two-digit expiration year of the virtual card (e.g., "27" for 2027).
• virtualCardLast4 (String): The last four digits of the virtual card number.
• status (VirtualCardStatus): The current status of the virtual card (e.g., ACTIVE, PENDING).
• cardType (VirtualCardType): Indicates if the card is MULTI_USE or SINGLE_USE.
• initialAmount (Float): The original spendLimit set when the card was created.
• usedAmount (Float): The total amount that has been spent using this virtual card so far.
• createdAt (DateTime): Timestamp when the virtual card was created.

Code Example: