> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fluz.app/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/features/get-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](/concepts/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](/concepts/address-formatting-requirements) and [Virtual Card Error Codes](/features/virtual-card-error-codes).
## cURL Example
```bash theme={null}
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
```graphql theme={null}
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.
```graphql theme={null}
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
```json theme={null}
{
"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
Retrieve the PAN, CVV, and expiry so the card can actually be used.
Enumerate every program available to your account to pick the right `offerId`.