> ## 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.
# Crear tarjeta virtual para usuario autorizado
Cree una tarjeta virtual en nombre de un usuario autorizado en la cuenta del solicitante. Pase el `authUserId` del usuario autorizado (el ID de asignación de rol UAC devuelto por `addAuthorizedUser`) para crear la tarjeta para el registro subyacente del titular de la tarjeta de ese usuario mientras mantiene la tarjeta dentro del alcance de la cuenta del solicitante.
El `authUserId` debe pertenecer a la cuenta del solicitante, debe estar ACTIVE y no puede ser una asignación `OWNER`. Si `addAuthorizedUser` devuelve `PENDING`, el usuario autorizado debe aceptar la invitación antes de que esta mutación pueda usar ese `authUserId`.
La creación de la tarjeta virtual puede usar una dirección de facturación guardada (`userAddressId`) o un `billingAddress` en línea. Para ofertas seleccionadas, proporcionar cualquiera de los valores de dirección dispara el registro de la dirección de facturación con el emisor de la tarjeta antes de que se emita la tarjeta. Si la aprobación del emisor aún está pendiente después de la ventana de espera del lado del servidor, la mutación devuelve el código de error de GraphQL `VC-0020` con `extensions.addressId`; reintente con ese valor como `userAddressId`.
🔒 Acceso restringido
Esta mutación requiere un token Bearer con el alcance `CREATE_VIRTUALCARD`.
```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
}
}
}
```
### Parámetros
| Parámetro | Tipo | Requerido | Descripción |
| :------------------------- | :----------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------ |
| input | CreateVirtualCardInput! | Sí | Objeto contenedor para la solicitud de creación de la tarjeta virtual. |
| input.idempotencyKey | UUID! | Sí | UUID único generado por el cliente. La misma clave evita que la misma solicitud sea procesada más de una vez. |
| input.spendLimit | Float! | Sí | Monto máximo que se puede cargar a la tarjeta. El mínimo es `$5`; se permiten como máximo dos decimales. |
| input.offerId | UUID | Sí | ID de la oferta de tarjeta virtual. Use `getVirtualCardOffers` para obtener ofertas activas. |
| input.authUserId | UUID | No | ID de usuario autorizado (ID de asignación de rol UAC) en cuyo nombre crear la tarjeta. Debe estar ACTIVE y no ser propietario. |
| input.userAddressId | UUID | No | ID de la dirección de facturación guardada para el solicitante o el titular autorizado. Tiene prioridad sobre `billingAddress`. |
| input.billingAddress | VirtualCardBillingAddressInput | No | Nueva dirección de facturación para guardar y registrar con el programa de tarjeta antes de emitir la tarjeta. |
| input.spendLimitDuration | VirtualCardSpendLimitDuration | No | Duración del límite de la tarjeta. Predeterminado `LIFETIME`. |
| input.lockDate | String | No | Fecha futura de bloqueo. Predeterminado a 47 meses desde la fecha de la solicitud. |
| input.lockCardNextUse | Boolean | No | Si se debe bloquear la tarjeta después del próximo uso. Predeterminado `false`. |
| input.cardNickname | String | No | Apodo de la tarjeta. Debe tener entre 1 y 50 caracteres cuando se proporciona. |
| input.primaryFundingSource | VirtualCardFundingSource | No | Fuente de fondos principal. Predeterminado `FLUZ_BALANCE`. Si es `BANK_ACCOUNT`, se requiere `bankAccountId`. |
| input.bankAccountId | UUID | No | ID de cuenta bancaria usado cuando `primaryFundingSource` es `BANK_ACCOUNT`. |
| input.userCashBalanceId | UUID | No | ID de la cuenta de gasto para adjuntar a la tarjeta. |
| input.usePrepaymentBalance | Boolean | No | Cuando es `false`, la tarjeta no tomará de saldo prepago. Predeterminado `true`. |
| input.useRewardsBalance | Boolean | No | Cuando es `false`, la tarjeta no tomará de saldo de recompensas. Predeterminado `true`. |
| input.memo | String | No | Nota opcional adjunta a la transacción. Máximo 255 caracteres. |
| input.transactionCategory | String | No | Nombre de categoría opcional. Se encuentra o crea una categoría coincidente para la cuenta. Máximo 100 caracteres. |
### Respuesta
#### Respuesta exitosa
```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
}
}
}
}
```
### Campos de respuesta
| Campo | Tipo | Descripción |
| :--------------------- | :------- | :-------------------------------------------------------------------------------------------------------------- |
| `virtualCardId` | UUID | ID de la tarjeta virtual creada. |
| `userId` | UUID | ID de usuario del titular. Cuando se proporciona `authUserId`, este es el ID de usuario del usuario autorizado. |
| `cardholderName` | String | Nombre del titular que se muestra en la tarjeta virtual. |
| `expiryMonth` | String | Mes de vencimiento de la tarjeta virtual. |
| `expiryYear` | String | Año de vencimiento de la tarjeta virtual. |
| `virtualCardLast4` | String | Últimos 4 dígitos del número de la tarjeta virtual. |
| `status` | String | Estado de la tarjeta virtual, como `ACTIVE`. |
| `cardType` | String | Tipo de tarjeta virtual. |
| `initialAmount` | Float | Límite de gasto inicial solicitado para la tarjeta. |
| `usedAmount` | Float | Monto ya gastado en la tarjeta. |
| `createdAt` | DateTime | Momento en que se creó la tarjeta. |
| `authorizationSetting` | Object | Configuración de autorización asociada a la tarjeta virtual. |
### Ejemplos de solicitudes
Cree una tarjeta para un usuario autorizado con una dirección guardada:
```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"
}
}
}'
```
Cree una tarjeta para un usuario autorizado con una nueva dirección de facturación en línea:
```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);
}
```
### Flujo completo: Registrar usuario, agregar usuario autorizado, agregar dirección, crear tarjeta
Este flujo registra a un nuevo usuario de Fluz, agrega a ese usuario a la cuenta del solicitante como usuario autorizado, guarda una dirección de facturación para ese titular autorizado y luego crea una tarjeta virtual en su nombre.
Paso 1: Registre al usuario. Esto requiere un token Bearer para el usuario desarrollador de una aplicación ACTIVE con el registro habilitado.
```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"
}
}'
```
Paso 2: Agregue al usuario registrado como usuario autorizado en la cuenta del solicitante.
```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"]
}
}'
```
Continúe solo después de que el `status` devuelto sea `ACTIVE`. Si el estado es `PENDING`, el usuario autorizado debe aceptar la invitación antes de que `addVirtualCardAddress` o `createVirtualCard` puedan usar el `authUserId` devuelto.
Paso 3: Guarde la dirección de facturación del usuario autorizado.
```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"
}
}
}
}'
```
Paso 4: Cree la tarjeta virtual para el usuario autorizado con la dirección guardada.
```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"
}
}
}'
```
### Códigos de error
| Código | Mensaje | Descripción |
| :---------- | :----------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ARG-0001` | Invalid arguments received | La entrada requerida falta o es inválida, `spendLimit` es menor a `$5`, `lockDate` no está en el futuro, `offerId` es inválido, `authUserId` es inválido, `userAddressId` no pertenece a la cuenta/titular, o se seleccionó financiación `BANK_ACCOUNT` sin `bankAccountId`. |
| `AUTH-0008` | Invalid user access | El token Bearer no se pudo resolver a un solicitante. Verifique que el token sea válido. |
| `AUTH-0031` | The requested scopes must be granted by the user first. | Al token le falta el alcance `CREATE_VIRTUALCARD` requerido para crear tarjetas virtuales. |
| `AUTH-0034` | No authorized user found with this id on the caller's account. | El `authUserId` no existe en la cuenta del solicitante, no está ACTIVE o se refiere a una asignación OWNER. |
| `VC-0001` | Please try another payment method. If you continue experiencing issues, please contact our support team. | No se pudo crear la tarjeta o el emisor rechazó la dirección de facturación. |
| `VC-0019` | We are unable to get the virtual card offer. If you continue experiencing issues, please contact our support team. | No se pudo resolver la oferta de tarjeta virtual solicitada. |
| `VC-0020` | Virtual card billing address is pending approval. Please retry shortly using the returned addressId. | La dirección de facturación se envió al emisor pero no fue aprobada antes de que terminara la ventana de espera del lado del servidor. Reintente usando `extensions.addressId` como `userAddressId`. |