Create Card

Use the createVirtualCard mutation to create a virtual card with configurable funding sources, limits, and lifecycle controls.

Prerequisites: a user access token with the CREATE_VIRTUALCARD scope, and a CreateVirtualCardInput object. To find an offerId, see Get Virtual Card Offers.

Billing address must be verifiable. The billing address — whether passed inline as billingAddress or referenced by userAddressId — must be a real, deliverable US address (US, USA, or United States) with a correct city, state, and ZIP; PO boxes are not accepted. It is validated against USPS data (via Smarty) as the cardholder is set up. If it can’t be verified, the card is not created and the request fails with VC-0025 (UnableToCreateAuthUser), returned on extensions.code. See Address Formatting Requirements.

Sandbox test offers

Offer ID	Program Name	Reward Value
`ed669305-5e43-40a0-9a25-7a15ed174628`	Virtual Card	1.5%
`b23630f6-8d91-43df-84aa-a541e7691197`	Virtual Card - Mastercard Prepaid	1.5%
`592c394e-26cc-44ac-a145-a5f81301fe77`	Brand Locked Virtual Card - Mastercard Prepaid	1.5%

Important considerations

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

Field	Type	Description	Required
`idempotencyKey`	`UUID!`	A unique client-generated UUID to ensure a request is processed only once.	Yes
`spendLimit`	`Float!`	The maximum amount you can charge to the card. You are only charged for the amount actually used.	Yes
`spendLimitDuration`	`VirtualCardSpendLimitDuration`	Card limit duration type. Default is `LIFETIME`.	No
`lockDate`	`String`	The date when the card will be locked. The default is 47 months from creation. Format: yyyy-mm-dd	No
`lockCardNextUse`	`Boolean`	Setting to lock the card after its next use. The default is `false`.	No
`cardNickname`	`String`	The card’s nickname.	No
`primaryFundingSource`	`VirtualCardFundingSource`	Primary Funding Source for Virtual Card. Default is `FLUZ_BALANCE`.	No
`bankAccountId`	`UUID`	The unique identifier for the bank account. Required if `primaryFundingSource` is `BANK_ACCOUNT`.	No
`offerId`	`UUID`	The Offer Id of Virtual Card Offer. Use `getVirtualCardOffers` to fetch a list of active offers.	No
`userCashBalanceId`	`UUID`	The cash balance (spend account) to be used for that purchase.	No
`usePrepaymentBalance`	`Boolean`	When `false`, the card will not draw from the prepaid (gift card) balance. Defaults to `true`, preserving the existing behavior where prepaid funds may be used in addition to the specified spend account.	No
`useRewardsBalance`	`Boolean`	When `false`, the card will not draw from the rewards balance. Defaults to `true`, preserving the existing behavior where rewards may be used in addition to the specified spend account.	No
`billingAddress`	`VirtualCardBillingAddressInput`	Billing address for the virtual card. If it doesn’t match an existing address on the user’s account (by street, city, state, and postal code), a new one is created. All fields are required except streetAddressLine2. Only U.S. addresses are supported. If userAddressId is provided, this field is ignored.	No
`userAddressId`	`UUID`	The ID of an existing billing address on the user’s account to use for the virtual card. If provided, it takes precedence over billingAddress. The ID must reference a UserAddress belonging to the calling user.	No
`memo`	`String`	An optional note to attach to the transaction.	No
`transactionCategory`	`String`	An optional category name. A matching category will be found or created for the account.	No

VirtualCardBillingAddressInput fields

Field	Type	Description	Required
`streetAddressLine1`	`String!`	The primary street address (e.g., “123 Main St”). PO boxes are not accepted by the card issuer.	Yes
`streetAddressLine2`	`String`	Optional secondary address line (e.g., apartment, suite, or unit number).	No
`country`	`String!`	The country name. Currently only “United States” is supported.	Yes
`city`	`String!`	The city name.	Yes
`state`	`String!`	The state name (e.g., “New York”) or two-letter US state code (e.g., “NY”).	Yes
`postalCode`	`String!`	A 5-digit US ZIP code.	Yes

Addresses that fail verification return VC-0025 (UnableToCreateAuthUser). See Address Formatting Requirements and Virtual Card Error Codes.

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 fields

Field	Type	Description
`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.

Next steps

Reveal the card

Retrieve the PAN, CVV, and expiry so the card can actually be used.

Get virtual card offers

Enumerate every program available to your account to pick the right offerId.

​Sandbox test offers

​Important considerations

​Arguments

​CreateVirtualCardInput fields

​VirtualCardBillingAddressInput fields

​cURL Example

​Sample Mutation

​Sample Mutation — Cash-Only Balance

​Sample Response

​Response fields

​Next steps

Reveal the card

Get virtual card offers

Sandbox test offers

Important considerations

Arguments

CreateVirtualCardInput fields

VirtualCardBillingAddressInput fields

cURL Example

Sample Mutation

Sample Mutation — Cash-Only Balance

Sample Response

Response fields

Next steps