> ## 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
Usa la mutación `createVirtualCard` para crear una tarjeta virtual con fuentes de fondos, límites y controles de ciclo de vida configurables.
**Requisitos previos:** un token de acceso de usuario con el alcance `CREATE_VIRTUALCARD`, y un objeto `CreateVirtualCardInput`. Para encontrar un `offerId`, consulta [Obtener ofertas de tarjeta virtual](/features/get-card-offers).
**La dirección de facturación debe ser verificable.** La dirección de facturación —ya sea pasada en línea como `billingAddress` o referenciada por `userAddressId`— debe ser una dirección real y entregable de **EE. UU.** (`US`, `USA` o `United States`) con ciudad, estado y código ZIP correctos; **no se aceptan apartados postales (PO Box)**. Se valida contra datos del USPS (a través de Smarty) al configurar al tarjetahabiente. Si no puede verificarse, la tarjeta no se crea y la solicitud falla con `VC-0025` (`UnableToCreateAuthUser`), devuelto en `extensions.code`. Consulta [Requisitos de formato de direcciones](/concepts/address-formatting-requirements).
## Ofertas de prueba en sandbox
| 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% |
## Consideraciones importantes
* **Fuente de fondos:** Puedes fondear tus tarjetas virtuales usando tu saldo de Fluz o una cuenta bancaria vinculada como fuente de fondos principal.
* Si seleccionas una cuenta bancaria como `primaryFundingSource`, debes proporcionar el `bankAccountId`.
* **Límites de gasto:** El spendLimit que configures debe cumplir con los límites de gasto definidos por el programa para el `spendLimitDuration` elegido. Ocurrirá un error si se excede el límite.
* **Composición del saldo:** De forma predeterminada, las tarjetas virtuales pueden fondearse con una combinación de tu cuenta de gasto especificada, saldo prepago (tarjeta de regalo) y saldo de recompensas cuando estén disponibles. Puedes restringir la tarjeta para que solo tome fondos de la cuenta de gasto configurando `usePrepaymentBalance: false` y `useRewardsBalance: false` en el input.
* **Anotaciones de transacción:** Opcionalmente puedes adjuntar un `memo` y/o `transactionCategory` al momento de crear la tarjeta. Estos se asociarán con la transacción resultante para fines de seguimiento y organización.
* Si se proporciona `transactionCategory`, se encontrará o creará una categoría coincidente para la cuenta.
* `attachmentId` no es compatible
## Argumentos
* `input` (`CreateVirtualCardInput!`): El objeto de entrada que contiene los detalles para la nueva tarjeta virtual.
## Campos de CreateVirtualCardInput
| Field | Type | Description | Required |
| ---------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `idempotencyKey` | `UUID!` | Un UUID único generado por el cliente para asegurar que una solicitud se procese solo una vez. | Yes |
| `spendLimit` | `Float!` | El monto máximo que puedes cargar a la tarjeta. Solo se te cobra el monto realmente utilizado. | Yes |
| `spendLimitDuration` | `VirtualCardSpendLimitDuration` | Tipo de duración del límite de la tarjeta. El valor predeterminado es `LIFETIME`. | No |
| `lockDate` | `String` | La fecha en la que la tarjeta se bloqueará. El valor predeterminado es 47 meses desde la creación. Formato: yyyy-mm-dd | No |
| `lockCardNextUse` | `Boolean` | Configuración para bloquear la tarjeta después de su próximo uso. El valor predeterminado es `false`. | No |
| `cardNickname` | `String` | El apodo de la tarjeta. | No |
| `primaryFundingSource` | `VirtualCardFundingSource` | Fuente de fondos principal para la tarjeta virtual. El valor predeterminado es `FLUZ_BALANCE`. | No |
| `bankAccountId` | `UUID` | El identificador único de la cuenta bancaria. Requerido si `primaryFundingSource` es `BANK_ACCOUNT`. | No |
| `offerId` | `UUID` | El Offer Id de la oferta de tarjeta virtual. Usa `getVirtualCardOffers` para obtener una lista de ofertas activas. | No |
| `userCashBalanceId` | `UUID` | El saldo en efectivo (cuenta de gasto) que se usará para esa compra. | No |
| `usePrepaymentBalance` | `Boolean` | Cuando es `false`, la tarjeta no tomará fondos del saldo prepago (tarjeta de regalo). De manera predeterminada es `true`, preservando el comportamiento existente donde los fondos prepagados pueden usarse además de la cuenta de gasto especificada. | No |
| `useRewardsBalance` | `Boolean` | Cuando es `false`, la tarjeta no tomará fondos del saldo de recompensas. De manera predeterminada es `true`, preservando el comportamiento existente donde las recompensas pueden usarse además de la cuenta de gasto especificada. | No |
| `billingAddress` | `VirtualCardBillingAddressInput` | Dirección de facturación para la tarjeta virtual. Si no coincide con una dirección existente en la cuenta del usuario (por calle, ciudad, estado y código postal), se crea una nueva. Todos los campos son obligatorios excepto streetAddressLine2. Solo se admiten direcciones de EE. UU. Si se proporciona userAddressId, este campo se ignora. | No |
| `userAddressId` | `UUID` | El ID de una dirección de facturación existente en la cuenta del usuario para usarla con la tarjeta virtual. Si se proporciona, tiene precedencia sobre billingAddress. El ID debe hacer referencia a un UserAddress perteneciente al usuario que realiza la llamada. | No |
| `memo` | `String` | Una nota opcional para adjuntar a la transacción. | No |
| `transactionCategory` | `String` | Un nombre de categoría opcional. Se encontrará o creará una categoría coincidente para la cuenta. | No |
## Campos de VirtualCardBillingAddressInput
| Field | Type | Description | Required |
| -------------------- | --------- | ------------------------------------------------------------------------------------------------------------------- | -------- |
| `streetAddressLine1` | `String!` | La dirección principal (por ejemplo, "123 Main St"). El emisor de la tarjeta no acepta apartados postales (PO Box). | Yes |
| `streetAddressLine2` | `String` | Línea de dirección secundaria opcional (por ejemplo, número de apartamento, suite o unidad). | No |
| `country` | `String!` | El nombre del país. Actualmente solo se admite "United States". | Yes |
| `city` | `String!` | El nombre de la ciudad. | Yes |
| `state` | `String!` | El nombre del estado (por ejemplo, "New York") o el código estatal de EE. UU. de dos letras (por ejemplo, "NY"). | Yes |
| `postalCode` | `String!` | Un código ZIP de EE. UU. de 5 dígitos. | Yes |
Las direcciones que no pasen la verificación devuelven `VC-0025` (`UnableToCreateAuthUser`). Consulta [Requisitos de formato de direcciones](/concepts/address-formatting-requirements) y [Códigos de error de tarjeta virtual](/features/virtual-card-error-codes).
## Ejemplo cURL
```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 } }"
}'
```
## Mutación de ejemplo
```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
}
}
```
## Mutación de ejemplo — Solo saldo en efectivo
Restringe una tarjeta virtual para que solo tome fondos del `userCashBalanceId` especificado, excluyendo fondos prepagos y de recompensas.
```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
}
}
```
## Respuesta de ejemplo
```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"
}
}
}
```
### Campos de la respuesta
| Field | Type | Description |
| ------------------ | ------------------- | ---------------------------------------------------------------------------------------------- |
| `virtualCardId` | `UUID` | El identificador único asignado a la tarjeta virtual recién creada. |
| `userId` | `UUID` | El identificador único del usuario que creó esta tarjeta virtual. |
| `cardholderName` | `String` | El nombre del tarjetahabiente tal como aparece en la tarjeta virtual. |
| `expiryMonth` | `String` | El mes de vencimiento de dos dígitos de la tarjeta virtual (por ejemplo, "12" para diciembre). |
| `expiryYear` | `String` | El año de vencimiento de dos dígitos de la tarjeta virtual (por ejemplo, "27" para 2027). |
| `virtualCardLast4` | `String` | Los últimos cuatro dígitos del número de la tarjeta virtual. |
| `status` | `VirtualCardStatus` | El estado actual de la tarjeta virtual (por ejemplo, ACTIVE, PENDING). |
| `cardType` | `VirtualCardType` | Indica si la tarjeta es MULTI\_USE o SINGLE\_USE. |
| `initialAmount` | `Float` | El `spendLimit` original configurado cuando se creó la tarjeta. |
| `usedAmount` | `Float` | El monto total que se ha gastado con esta tarjeta virtual hasta ahora. |
| `createdAt` | `DateTime` | Marca de tiempo cuando se creó la tarjeta virtual. |
## Próximos pasos
Obtén el PAN, CVV y vencimiento para que la tarjeta pueda usarse realmente.
Enumera cada programa disponible para tu cuenta para elegir el `offerId` correcto.