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.

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.

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 y Códigos de error de tarjeta virtual.

Ejemplo cURL

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

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.

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

{
  "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

Revelar la tarjeta

Obtén el PAN, CVV y vencimiento para que la tarjeta pueda usarse realmente.

Obtener ofertas de tarjeta virtual

Enumera cada programa disponible para tu cuenta para elegir el offerId correcto.

​Ofertas de prueba en sandbox

​Consideraciones importantes

​Argumentos

​Campos de CreateVirtualCardInput

​Campos de VirtualCardBillingAddressInput

​Ejemplo cURL

​Mutación de ejemplo

​Mutación de ejemplo — Solo saldo en efectivo

​Respuesta de ejemplo

​Campos de la respuesta

​Próximos pasos

Revelar la tarjeta

Obtener ofertas de tarjeta virtual

Ofertas de prueba en sandbox

Consideraciones importantes

Argumentos

Campos de CreateVirtualCardInput

Campos de VirtualCardBillingAddressInput

Ejemplo cURL

Mutación de ejemplo

Mutación de ejemplo — Solo saldo en efectivo

Respuesta de ejemplo

Campos de la respuesta

Próximos pasos