> ## 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 Virtual Card for Authorized User
Create a virtual card on behalf of an authorized user on the caller's account. Pass the authorized user's `authUserId` (the UAC role assignment ID returned by `addAuthorizedUser`) to create the card for that user's underlying cardholder record while keeping the card scoped to the caller's account.
The `authUserId` must belong to the caller's account, must be ACTIVE, and cannot be an `OWNER` assignment. If `addAuthorizedUser` returns `PENDING`, the authorized user must accept the invite before this mutation can use that `authUserId`.
Virtual card creation can use a saved billing address (`userAddressId`) or an inline `billingAddress`. For select offers, providing either address value triggers billing-address registration with the card issuer before the card is issued. If issuer approval is still pending after the server-side wait window, the mutation returns GraphQL error code `VC-0020` with `extensions.addressId`; retry with that value as `userAddressId`.
🔒 Restricted Access
This mutation requires a Bearer token with the `CREATE_VIRTUALCARD` scope.
```graphql theme={null}
mutation CreateVirtualCard($input: CreateVirtualCardInput!) {
createVirtualCard(input: $input) {
virtualCardId
userId
cardholderName
expiryMonth
expiryYear
virtualCardLast4
status
cardType
initialAmount
usedAmount
createdAt
authorizationSetting {
lockDate
dailySpendLimit
weeklySpendLimit
monthlySpendLimit
}
}
}
```
### Parameters
| Parameter | Type | Required | Description |
| :------------------------- | :----------------------------- | :------- | :--------------------------------------------------------------------------------------------------------- |
| input | CreateVirtualCardInput! | Yes | Wrapper object for the virtual card creation request. |
| input.idempotencyKey | UUID! | Yes | Unique client-generated UUID. The same key prevents the same request from being processed more than once. |
| input.spendLimit | Float! | Yes | Maximum amount that can be charged to the card. Minimum is `$5`; at most two decimal places are allowed. |
| input.offerId | UUID | Yes | Virtual card offer ID. Use `getVirtualCardOffers` to fetch active offers. |
| input.authUserId | UUID | No | Authorized user ID (UAC role assignment ID) to create the card on behalf of. Must be ACTIVE and non-owner. |
| input.userAddressId | UUID | No | Saved billing address ID for the caller or authorized cardholder. Takes precedence over `billingAddress`. |
| input.billingAddress | VirtualCardBillingAddressInput | No | New billing address to save and register with the card program before issuing the card. |
| input.spendLimitDuration | VirtualCardSpendLimitDuration | No | Card limit duration. Defaults to `LIFETIME`. |
| input.lockDate | String | No | Future lock date. Defaults to 47 months from the request date. |
| input.lockCardNextUse | Boolean | No | Whether to lock the card after the next use. Defaults to `false`. |
| input.cardNickname | String | No | Card nickname. Must be 1-50 characters when provided. |
| input.primaryFundingSource | VirtualCardFundingSource | No | Primary funding source. Defaults to `FLUZ_BALANCE`. If `BANK_ACCOUNT`, `bankAccountId` is required. |
| input.bankAccountId | UUID | No | Bank account ID used when `primaryFundingSource` is `BANK_ACCOUNT`. |
| input.userCashBalanceId | UUID | No | Spend account ID to attach to the card. |
| input.usePrepaymentBalance | Boolean | No | When `false`, the card will not draw from prepaid balance. Defaults to `true`. |
| input.useRewardsBalance | Boolean | No | When `false`, the card will not draw from rewards balance. Defaults to `true`. |
| input.memo | String | No | Optional note attached to the transaction. Maximum 255 characters. |
| input.transactionCategory | String | No | Optional category name. A matching category is found or created for the account. Maximum 100 characters. |
### Response
#### Success Response
```json theme={null}
{
"data": {
"createVirtualCard": {
"virtualCardId": "6d9f0d0f-21f0-4ad1-8fc7-2fb7dd58ce11",
"userId": "f1320ac4-52dc-4c67-9e80-24e506b18450",
"cardholderName": "Ada Lovelace",
"expiryMonth": "08",
"expiryYear": "2029",
"virtualCardLast4": "4242",
"status": "ACTIVE",
"cardType": "MULTI_USE",
"initialAmount": 100,
"usedAmount": 0,
"createdAt": "2026-05-15T15:18:00.000Z",
"authorizationSetting": {
"lockDate": "2029-08-15",
"dailySpendLimit": null,
"weeklySpendLimit": null,
"monthlySpendLimit": null
}
}
}
}
```
### Response Fields
| Field | Type | Description |
| :--------------------- | :------- | :----------------------------------------------------------------------------------------------- |
| `virtualCardId` | UUID | Created virtual card ID. |
| `userId` | UUID | User ID of the cardholder. When `authUserId` is provided, this is the authorized user's user ID. |
| `cardholderName` | String | Cardholder name shown on the virtual card. |
| `expiryMonth` | String | Virtual card expiration month. |
| `expiryYear` | String | Virtual card expiration year. |
| `virtualCardLast4` | String | Last 4 digits of the virtual card number. |
| `status` | String | Virtual card status, such as `ACTIVE`. |
| `cardType` | String | Virtual card type. |
| `initialAmount` | Float | Initial spend limit requested for the card. |
| `usedAmount` | Float | Amount already spent on the card. |
| `createdAt` | DateTime | Time when the card was created. |
| `authorizationSetting` | Object | Authorization settings attached to the virtual card. |
### Example Requests
Create a card for an authorized user with a saved address:
```curl theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"query": "mutation CreateVirtualCard($input: CreateVirtualCardInput!) { createVirtualCard(input: $input) { virtualCardId userId cardholderName virtualCardLast4 status cardType initialAmount usedAmount createdAt } }",
"variables": {
"input": {
"idempotencyKey": "931e8841-cf23-4f36-8bf8-169384042ec2",
"offerId": "09a9c8d1-9c4b-46fa-8a7a-508812a2a0d9",
"authUserId": "8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d",
"userAddressId": "1f6b2c3d-4e5f-4a67-9a10-2b3c4d5e6f70",
"spendLimit": 100,
"spendLimitDuration": "LIFETIME",
"cardNickname": "Ada Travel Card",
"primaryFundingSource": "FLUZ_BALANCE"
}
}
}'
```
Create a card for an authorized user with a new inline billing address:
```curl theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"query": "mutation CreateVirtualCard($input: CreateVirtualCardInput!) { createVirtualCard(input: $input) { virtualCardId userId cardholderName virtualCardLast4 status cardType initialAmount usedAmount createdAt } }",
"variables": {
"input": {
"idempotencyKey": "c20341f0-47e3-4d52-8361-1d7c37736b65",
"offerId": "09a9c8d1-9c4b-46fa-8a7a-508812a2a0d9",
"authUserId": "8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d",
"spendLimit": 100,
"billingAddress": {
"streetAddressLine1": "456 Market St",
"streetAddressLine2": "Suite 200",
"country": "United States",
"city": "San Francisco",
"state": "CA",
"postalCode": "94105"
}
}
}
}'
```
```typescript theme={null}
const response = await fetch('https://transactional-graph.staging.fluzapp.com/api/v1/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${accessToken}`,
},
body: JSON.stringify({
query: `
mutation CreateVirtualCard(
$input: CreateVirtualCardInput!
) {
createVirtualCard(input: $input) {
virtualCardId
userId
cardholderName
virtualCardLast4
status
cardType
initialAmount
usedAmount
createdAt
}
}
`,
variables: {
input: {
idempotencyKey: '931e8841-cf23-4f36-8bf8-169384042ec2',
offerId: '09a9c8d1-9c4b-46fa-8a7a-508812a2a0d9',
authUserId: '8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d',
userAddressId: '1f6b2c3d-4e5f-4a67-9a10-2b3c4d5e6f70',
spendLimit: 100,
spendLimitDuration: 'LIFETIME',
cardNickname: 'Ada Travel Card',
primaryFundingSource: 'FLUZ_BALANCE',
},
},
}),
});
const data = await response.json();
if (data.errors?.[0]?.extensions?.code === 'VC-0020') {
const userAddressId = data.errors[0].extensions.addressId;
console.log('Billing address pending issuer approval. Retry with userAddressId:', userAddressId);
} else {
console.log('Virtual card created:', data.data.createVirtualCard);
}
```
### Full Flow: Register User, Add Authorized User, Add Address, Create Card
This flow registers a new Fluz user, adds that user to the caller's account as an authorized user, saves a billing address for that authorized cardholder, then creates a virtual card on their behalf.
Step 1: Register the user. This requires a Bearer token for the developer user of an ACTIVE application with registration enabled.
```curl theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"query": "mutation RegisterUser($firstName: String!, $lastName: String!, $phoneNumber: String!, $regionCode: String!, $emailAddress: String!, $dateOfBirth: String!) { registerUser(firstName: $firstName, lastName: $lastName, phoneNumber: $phoneNumber, regionCode: $regionCode, emailAddress: $emailAddress, dateOfBirth: $dateOfBirth) { success error { code message } } }",
"variables": {
"firstName": "Ada",
"lastName": "Lovelace",
"phoneNumber": "5555555555",
"regionCode": "US",
"emailAddress": "ada.lovelace@example.com",
"dateOfBirth": "1990-01-31"
}
}'
```
Step 2: Add the registered user as an authorized user on the caller's account.
```curl theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"query": "mutation AddAuthorizedUser($email: String, $roles: [UACRoleType!]!) { addAuthorizedUser(email: $email, roles: $roles) { success authUserId roles status pendingActionId error { code message } } }",
"variables": {
"email": "ada.lovelace@example.com",
"roles": ["SPENDER"]
}
}'
```
Continue only after the returned `status` is `ACTIVE`. If the status is `PENDING`, the authorized user must accept the invite before `addVirtualCardAddress` or `createVirtualCard` can use the returned `authUserId`.
Step 3: Save the authorized user's billing address.
```curl theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"query": "mutation AddVirtualCardAddress($input: AddVirtualCardAddressInput!) { addVirtualCardAddress(input: $input) { userAddressId streetAddressLine1 streetAddressLine2 country city state postalCode } }",
"variables": {
"input": {
"authUserId": "8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d",
"billingAddress": {
"streetAddressLine1": "456 Market St",
"streetAddressLine2": "Suite 200",
"country": "United States",
"city": "San Francisco",
"state": "CA",
"postalCode": "94105"
}
}
}
}'
```
Step 4: Create the virtual card for the authorized user with the saved address.
```curl theme={null}
curl -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer " \
-d '{
"query": "mutation CreateVirtualCard($input: CreateVirtualCardInput!) { createVirtualCard(input: $input) { virtualCardId userId cardholderName virtualCardLast4 status cardType initialAmount usedAmount createdAt } }",
"variables": {
"input": {
"idempotencyKey": "931e8841-cf23-4f36-8bf8-169384042ec2",
"offerId": "09a9c8d1-9c4b-46fa-8a7a-508812a2a0d9",
"authUserId": "8b2c1e0a-7d4f-4a9b-9c2d-1f3e4a5b6c7d",
"userAddressId": "1f6b2c3d-4e5f-4a67-9a10-2b3c4d5e6f70",
"spendLimit": 100,
"spendLimitDuration": "LIFETIME",
"cardNickname": "Ada Travel Card",
"primaryFundingSource": "FLUZ_BALANCE"
}
}
}'
```
### Error Codes
| Code | Message | Description |
| :---------- | :----------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ARG-0001` | Invalid arguments received | Required input is missing or invalid, `spendLimit` is below `$5`, `lockDate` is not in the future, `offerId` is invalid, `authUserId` is invalid, `userAddressId` does not belong to the account/cardholder, or `BANK_ACCOUNT` funding was selected without `bankAccountId`. |
| `AUTH-0008` | Invalid user access | The Bearer token could not be resolved to a caller. Verify the token is valid. |
| `AUTH-0031` | The requested scopes must be granted by the user first. | The token is missing the `CREATE_VIRTUALCARD` scope required to create virtual cards. |
| `AUTH-0034` | No authorized user found with this id on the caller's account. | The `authUserId` does not exist on the caller's account, is not ACTIVE, or refers to an OWNER assignment. |
| `VC-0001` | Please try another payment method. If you continue experiencing issues, please contact our support team. | The card could not be created or the issuer rejected the billing address. |
| `VC-0019` | We are unable to get the virtual card offer. If you continue experiencing issues, please contact our support team. | The requested virtual card offer could not be resolved. |
| `VC-0020` | Virtual card billing address is pending approval. Please retry shortly using the returned addressId. | The billing address was submitted to the issuer but was not approved before the server-side wait window ended. Retry using `extensions.addressId` as `userAddressId`. |