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.

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

{
  "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 -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -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 -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -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"
      }
    }
  }
}'

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 -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <developer_access_token>" \
  -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 -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <account_owner_access_token>" \
  -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 -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <account_owner_access_token>" \
  -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 -X POST https://transactional-graph.staging.fluzapp.com/api/v1/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <account_owner_access_token>" \
  -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`.

​Parámetros

​Respuesta

​Respuesta exitosa

​Campos de respuesta

​Ejemplos de solicitudes

​Flujo completo: Registrar usuario, agregar usuario autorizado, agregar dirección, crear tarjeta

​Códigos de error